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
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
|
.. _user_config:
User configuration
==================
User configuration and preferences can be specified in a user provided
configuration file, and usually also on the command line.
Values specified in a user provided configuration file override the
defaults, while command line options take precedence over any other
specified configurations.
Configuration file
------------------
Users can provide a configuration file to override parameters in
the default configuration.
Unless a configuration file is explicitly specified on the command line when
invoking ``bst``, an attempt is made to load user specific configuration from
``$XDG_CONFIG_HOME/buildstream.conf``. On most Linux based systems, the location
will be ``~/.config/buildstream.conf``
Project specific value
----------------------
The ``projects`` key can be used to specify project specific configurations,
the supported configurations on a project wide basis are listed here.
.. _config_artifacts:
Artifact server
~~~~~~~~~~~~~~~
Although project's often specify a :ref:`remote artifact cache <artifacts>` in
their ``project.conf``, you may also want to specify extra caches.
Assuming that your host/server is reachable on the internet as ``artifacts.com``
(for example), there are two ways to declare remote caches in your user
configuration:
1. Adding global caches:
.. code:: yaml
#
# Artifacts
#
artifacts:
# Add a cache to pull from
- url: https://artifacts.com/artifacts:11001
server-cert: server.crt
# Add a cache to push/pull to/from
- url: https://artifacts.com/artifacts:11002
server-cert: server.crt
client-cert: client.crt
client-key: client.key
push: true
# Add another cache to pull from
- url: https://anothercache.com/artifacts:8080
server-cert: another_server.crt
.. note::
Caches declared here will be used by **all** BuildStream project's on the user's
machine and are considered a lower priority than those specified in the project
configuration.
2. Specifying caches for a specific project within the user configuration:
.. code:: yaml
projects:
project-name:
artifacts:
# Add a cache to pull from
- url: https://artifacts.com/artifacts:11001
server-cert: server.crt
# Add a cache to push/pull to/from
- url: https://artifacts.com/artifacts:11002
server-cert: server.crt
client-cert: client.crt
client-key: client.key
push: true
# Add another cache to pull from
- url: https://ourprojectcache.com/artifacts:8080
server-cert: project_server.crt
.. note::
Caches listed here will be considered a higher priority than those specified
by the project. Furthermore, for a given list of URLs, earlier entries will
have higher priority.
Notice that the use of different ports for the same server distinguishes between
pull only access and push/pull access. For information regarding this and the
server/client certificates and keys, please see:
:ref:`Key pair for the server <server_authentication>`.
.. _user_config_remote_execution:
Remote execution
~~~~~~~~~~~~~~~~
The same configuration for :ref:`remote execution <project_remote_execution>`
in ``project.conf`` can be provided in the user configuation.
There is only one remote execution configuration used per project.
The project overrides will be taken in priority. The global
configuration will be used as fallback.
1. Global remote execution fallback:
.. code:: yaml
remote-execution:
execution-service:
url: http://execution.fallback.example.com:50051
instance-name: main
storage-service:
url: https://storage.fallback.example.com:11002/
server-cert: /keys/server.crt
client-cert: /keys/client.crt
client-key: /keys/client.key
instance-name: main
action-cache-service:
url: http://action.flalback.example.com:50052
2. Project override:
.. code:: yaml
projects:
some_project:
remote-execution:
execution-service:
url: http://execution.some_project.example.com:50051
instance-name: main
storage-service:
url: https://storage.some_project.example.com:11002/
server-cert: /some_project_keys/server.crt
client-cert: /some_project_keys/client.crt
client-key: /some_project_keys/client.key
instance-name: main
action-cache-service:
url: http://action.some_project.example.com:50052
Strict build plan
~~~~~~~~~~~~~~~~~
The strict build plan option decides whether you want elements
to rebuild when their dependencies have changed. This is enabled
by default, but recommended to turn off in developer scenarios where
you might want to build a large system and test it quickly after
modifying some low level component.
**Example**
.. code:: yaml
projects:
project-name:
strict: False
.. note::
It is always possible to override this at invocation time using
the ``--strict`` and ``--no-strict`` command line options.
.. _config_default_mirror:
Default Mirror
~~~~~~~~~~~~~~
When using :ref:`mirrors <project_essentials_mirrors>`, a default mirror can
be defined to be fetched first.
The default mirror is defined by its name, e.g.
.. code:: yaml
projects:
project-name:
default-mirror: oz
.. note::
It is possible to override this at invocation time using the
``--default-mirror`` command-line option.
Local cache expiry
~~~~~~~~~~~~~~~~~~
BuildStream locally caches artifacts, build trees, log files and sources within a
cache located at ``~/.cache/buildstream`` (unless a $XDG_CACHE_HOME environment
variable exists). When building large projects, this cache can get very large,
thus BuildStream will attempt to clean up the cache automatically by expiring the least
recently *used* artifacts.
By default, cache expiry will begin once the file system which contains the cache
approaches maximum usage. However, it is also possible to impose a quota on the local
cache in the user configuration. This can be done in two ways:
1. By restricting the maximum size of the cache directory itself.
For example, to ensure that BuildStream's cache does not grow beyond 100 GB,
simply declare the following in your user configuration (``~/.config/buildstream.conf``):
.. code:: yaml
cache:
quota: 100G
This quota defines the maximum size of the artifact cache in bytes.
Other accepted values are: K, M, G or T (or you can simply declare the value in bytes, without the suffix).
This uses the same format as systemd's
`resource-control <https://www.freedesktop.org/software/systemd/man/systemd.resource-control.html>`_.
2. By expiring artifacts once the file system which contains the cache exceeds a specified usage.
To ensure that we start cleaning the cache once we've used 80% of local disk space (on the file system
which mounts the cache):
.. code:: yaml
cache:
quota: 80%
Default configuration
---------------------
The default BuildStream configuration is specified here for reference:
.. literalinclude:: ../../buildstream/data/userconfig.yaml
:language: yaml
|
