aboutsummaryrefslogtreecommitdiffstats
path: root/builds.sr.ht/manifest.md
blob: c366edd980d50b8a1be1cf7be064a1e20986c7bf (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
---
title: Build manifest reference
---

A build manifest is a YAML file that describes how to perform a build. Here's an
example:

```yaml
image: archlinux
packages:
  - meson
  - scdoc
  - wayland-protocols
  - wlroots-git
  - wayland
  - libxkbcommon
  - cairo
  - pango
  - gdk-pixbuf2
  - pixman
  - libinput
  - xorg-server-xwayland
sources:
  - https://github.com/SirCmpwn/sway
tasks:
  - setup: |
      cd sway
      meson build
  - build: |
      cd sway
      ninja -C build
```

The minimum build manifest has an image and at least one task. The various
properties available are described here:

## image

*string*

Which OS image to build in. A list of available build images can be found on the
[compatibility page](/builds.sr.ht/compatibility.md).

## packages

*list* (of *string*)

A list of packages to install on the image. For image-specific details,
consult the [compatibility list](/builds.sr.ht/compatibility.md)

## repositories

*dictionary* (of *string: string*)

A list of extra repositories to enable with the image's package manager. The
specific format varies by base image, [consult the compatibility
page](/builds.sr.ht/compatibility.md) for details.

## sources

*list* (of *string*)

A list of repositories to clone into the home directory of the build user in the
build environment. Optionally, prefix the protocol with the source control
management scheme, to specify a protocol other than git. Examples:

- `https://git.sr.ht/~sircmpwn/scdoc`: git over https
- `git@git.sr.ht:~sircmpwn/scdoc`: git over SSH ([requires key](private-repos.md))
- `hg+https://hg.sr.ht/~sircmpwn/scdoc`: Mercurial over https
- `hg+ssh://hg.sr.ht/~sircmpwn/scdoc`: Mercurial over SSH ([requires key](private-repos.md))

## tasks

*list* (of *string*)

A list of scripts to execute in the build environment. These scripts are run
with the following preamble:

```sh
#!/usr/bin/env bash
. ~/.buildenv
set -x
set -e
```

~/.buildenv contains environment variables specified by the `environment`
directive.

Task names must use only lowercase alphanumeric characters or underscores
and must be <=128 characters in length. Tasks are executed in the order
specified.

Each task is run in a separate login session, so if you modify the groups of the
`build` user they will be effective starting from the subsequent task.

## triggers

*list* (of *trigger*)

A list of triggers to execute post-build, which can be used to send emails
or do other post-build tasks.

See also: [Build triggers](triggers.md)

## environment

*dictionary* (of *string: string* OR *string: list*)

A list of key/value pairs for options to set in the build environment via
`~/.buildenv`.

Since the value will be parsed twice, once as YAML and once by `bash`,
string literals containing spaces must be 'doubly quoted':

```yaml
environment:
  GIT_SSH_COMMAND: '"ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no"'
```

## secrets

*list* (of *string*)

List of secret UUIDs to be added to the guest during the build. See also:
[secrets](/builds.sr.ht#secrets).