Skip to content

Commit ec726bf

Browse files
vaikasvaikas
authored
Merge pull request #609 from vaikas/document-build-file
Start of exhaustively documenting the build file.
2 parents a91a4c7 + 6575bf5 commit ec726bf

File tree

1 file changed

+263
-0
lines changed

1 file changed

+263
-0
lines changed

‎docs/BUILD-FILE.md

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
# melange build file
2+
3+
This documents the melange build file structure, fields, when, and why to use various fields.
4+
5+
# High level structure overview
6+
7+
The following are the high level sections for the build file, with detailed descriptions for each of them, and their fields in the sections following.
8+
9+
## Required
10+
### package
11+
12+
Package metadata about this package, name, version, etc.
13+
### environment
14+
15+
Specification for the packages build environment
16+
### pipeline
17+
18+
Ordered list of pipelines that produce this package
19+
20+
## Optional
21+
### subpackages
22+
23+
List of subpackages that this package also produces. For example, docs.
24+
### data
25+
26+
Arbitrary list of data available for templating in the pipeline.
27+
### [update](./UPDATE.md)
28+
29+
Defines how this package is auto updated
30+
### vars
31+
32+
Map of arbitrary variables available for templating in the pipeline.
33+
### [var-transforms](./VAR-TRANSFORMS.md)
34+
35+
List of transformations to create for the builtin template variables.
36+
### options
37+
38+
Deviations to the build
39+
40+
# package
41+
42+
Details about the particular package that will be used to find and use it.
43+
44+
### name
45+
Unique name for the package. Convention is to use the same name as the YAML file without extension. This is what people will search for, so it's a good idea to keep it consistent with how the package is named in other distributions. for example:
46+
```
47+
name: python-3.10
48+
```
49+
50+
### version
51+
Version of the package. For example:
52+
```
53+
version: 3.10.12
54+
```
55+
56+
### epoch
57+
Monotonically increasing value (starting at 0) indicating same version of the
58+
package, but with changes (security patches for example) applied to it.
59+
```
60+
epoch: 0
61+
```
62+
63+
**NOTE** the above 3 fields are used to construct the package filename of the
64+
form: `<name>-<version>-r<epoch>.apk` for our example above, this would be:
65+
`python-3.10-3.10.12-r0.apk`.
66+
67+
### description
68+
Human readable description of the package. Make this meaningful, as this information shows up when searching for the package with apk, for example:
69+
```
70+
description: "the Python programming language"
71+
```
72+
73+
### url [optional]
74+
The URL to the packages homepage.
75+
76+
### commit [optional]
77+
The git commit of the package build configuration
78+
TODO(vaikas): is the 'is package build configuration' this file?
79+
TODO(vaikas): why would I use this? I did not see an example use.
80+
81+
### target-architecture [optional]
82+
List of architectures for which this package should be built for. Valid
83+
architectures are: `386`, `amd64`, `arm/v6`, `arm/v7`, `arm64`, `ppc64le`,
84+
`s390x`, `x86_64`, `aarch64`, special `all` that builds it for all of them.
85+
Leaving this out defaults to `all`.
86+
TODO(vaikas): rekor-cli.yaml sets this to all? So is that not the default?
87+
TODO(vaikas): Saw something about riscv64. Does all include that?
88+
89+
### copyright
90+
List of copyrights for this package. Each entry in the list consists of 3
91+
fields that define the scope (paths, and which license applies to it):
92+
93+
#### license
94+
The license for either the package or part of the package (if there are multiple entries). It is important to note that only packages with OSI-approved licenses can be included in Wolfi. You can check the relevant package info in the licenses page at [opensource.org](https://opensource.org/licenses/).
95+
96+
#### paths [optional]
97+
The license paths that this license applies to
98+
99+
#### attestation
100+
Attestations for this license.
101+
102+
For example, saying that this entire package has license `PSF-2.0`
103+
```
104+
copyright:
105+
- license: PSF-2.0
106+
```
107+
108+
TODO(vaikas): Add attestation example (only found TODO)
109+
TODO(vaikas): Add paths example (only found *)
110+
111+
### dependencies
112+
List of packages that this package depends on at runtime, but not during build
113+
time. These will get installed by apk as system dependencies when the package is
114+
installed. For example, saying that a package depends on `openssl`, `socat`, and
115+
`curl` at runtime:
116+
```
117+
dependencies:
118+
runtime:
119+
- openssl
120+
- socat
121+
- curl
122+
```
123+
124+
TODO(vaikas): How does it decide, or can you control which version to install? Latest? Does anybody care?
125+
126+
### options
127+
Options that describe the package functionality. Currently there are three
128+
options, and these are used by SCA tools to control their behaviour.
129+
130+
`no-provides` - This is a virtual package which provides no files, executables,
131+
or libraries. Turns off the SCA-based dependency generators. A good example of
132+
this is a package placeholder that then provides more targeted packages, for
133+
example:
134+
135+
```
136+
options:
137+
no-provides: true
138+
```
139+
140+
`no-depends` - This is a self contained package that does not depend on any
141+
other package. Turns off SCA-based dependency generators.
142+
143+
```
144+
options:
145+
no-depends: true
146+
```
147+
148+
`no-commands` - This package should not be searched for commands. By default, we
149+
look through /usr/bin, etc looking for commands. If we find commands we
150+
generate provider entries for them. This allows for things like apk search
151+
cmd:foo, apk add cmd:bar to work. By default melange does the right thing, so
152+
you probably need a good reason to turn this off.
153+
154+
```
155+
options:
156+
no-commands: true
157+
```
158+
159+
### scriptlets
160+
List of executable scripts that run at various stages of the package lifecycle,
161+
triggered by configurable events. These are useful to handle tasks that only
162+
happen during install, uninstall, upgrade. The life-cycle events are:
163+
`pre-install`, `post-install`, `pre-deinstall`, `post-deinstall`, `pre-upgrade`,
164+
`post-upgrade`. The script should contain the shebang interpereter, for
165+
example:
166+
167+
```
168+
scriptlets:
169+
post-deinstall: |
170+
#!/bin/busybox sh
171+
/bin/busybox --install -s
172+
```
173+
174+
In addition to lifecycle events, you can define `Trigger` which defines a list
175+
of paths to monitor, which causes a script to run. The script should contain the
176+
shebang interpreter, for example:
177+
178+
```
179+
scriptlets:
180+
trigger:
181+
paths:
182+
- /bin
183+
- /sbin
184+
- /usr/bin
185+
- /usr/sbin
186+
script: |
187+
#!/bin/busybox sh
188+
/bin/busybox --install -s
189+
```
190+
191+
TODO(vaikas): What does it mean to monitor, when new files are added/removed to
192+
those directories? Something else??
193+
194+
# environment
195+
Environment defines the build environment, including what the dependencies are,
196+
including repositories, packages, etc.
197+
198+
## Local building
199+
When building locally, you'll also need to include information about where to find Wolfi packages. This is not needed when submitting the package to the Wolfi OS repository. The "contents" node is used for that:
200+
201+
```yaml
202+
environment:
203+
contents:
204+
repositories:
205+
- https://packages.wolfi.dev/bootstrap/stage3
206+
- https://packages.wolfi.dev/os
207+
keyring:
208+
- https://packages.wolfi.dev/bootstrap/stage3/wolfi-signing.rsa.pub
209+
- https://packages.wolfi.dev/os/wolfi-signing.rsa.pub
210+
```
211+
212+
## contents
213+
Contents has 3 lists that define where to look for packages, how to validate the
214+
repository, and which packages to install.
215+
216+
### repositories
217+
Which repositories to fetch the packages from. **NOTE** Do not mix Alpine apk
218+
repositories with Wolfi apk repositories.
219+
220+
### keyring
221+
These are used to validate the authenticity of a repository.
222+
223+
TODO(vaikas): Are there any constraints here, or if any key in the keyring
224+
matches a repository, then all is well. I'd assume so.
225+
226+
### packages
227+
Packages is the list of packages to install for running the pipeline.
228+
229+
For example:
230+
```
231+
environment:
232+
contents:
233+
repositories:
234+
- https://packages.wolfi.dev/os
235+
keyring:
236+
- https://packages.wolfi.dev/os/wolfi-signing.rsa.pub
237+
packages:
238+
- busybox
239+
- ca-certificates-bundle
240+
- go
241+
```
242+
243+
TODO(vaikas): Are there ways to control which version of the packages gets
244+
installed?
245+
246+
## environment
247+
environment allows you to control environmental variables to set while running
248+
the pipeline. For example, to set the env variable `CGO_ENABLED` to `0`:
249+
250+
```
251+
environment:
252+
environment:
253+
CGO_ENABLED: "0"
254+
```
255+
256+
TODO(vaikas): melange config points to apko here:
257+
https://github.com/chainguard-dev/melange/blob/main/pkg/config/config.go#L256
258+
which points to [ImageConfiguration](https://github.com/chainguard-dev/apko/blob/main/pkg/build/types/types.go#L106), which has a ton of stuff, is all that
259+
really supported, or just `environment`
260+
261+
# pipeline
262+
Pipeline defines the ordered steps to build the package.
263+

0 commit comments

Comments
 (0)