1RBM_CONFIG(7) RBM_CONFIG(7)
2
6 rbm_config - The rbm configuration
7
9 All configuration options can be defined in different places :
10 • in the main configuration in your working directory (rbm.conf)
12 • in a module configuration at the root of a module directory
14 (rbm.module.conf)
15 • in the local configuration in your working directory
17 (rbm.local.conf)
18 • in the global system configuration (/etc/rbm.conf)
20 • in a project configuration
22 • with a command line option
24 The option values are used with the following priority order :
26 • command line options
28 • project config for matching step and target
30 • project config for matching step
32 • project config for matching target
34 • project config
36 • local config for matching step and target
38 • local config for matching step
40 • local config for matching target
42 • local config
44 • workspace config for matching step and target
46 • workspace config for matching step
48 • workspace config for matching target
50 • workspace config
52 • modules config for matching step and target
54 • modules config for matching step
56 • modules config for matching target
58 • modules config
60 • system config for matching step and target
62 • system config for matching step
64 • system config for matching target
66 • system config
68 • default config
70 • undefined
72 The system configuration is by default located at /etc/rbm.conf, or the
74 path defined in the sysconf_file option. If the path does not exists,
75 it is ignored. This is where you will put configuration only relevant
76 to your local use of rbm.
77 The main configuration file is rbm.conf, in YAML format. It can be
79 located anywhere on your filesystem, but you will need to run the rbm
80 commands from the same directory, or one of its subdirectories. This is
81 where you will put configuration relevant to all projects under this
82 working directory. All relative paths used in the configuration are
83 relative from the rbm.conf location.
84 The local configuration file is rbm.local.conf (or the file defined by
86 the localconf_file option), in the same directory as the rbm.conf file.
87 If the file does not exists, it is ignored. The rbm.local.conf file is
88 used to override some options from rbm.conf relevent to your local
89 setup, whithout modifying the rbm.conf file which is usually maintained
90 in a VCS.
91 The module configuration files are rbm.module.conf located at the root
93 of each module directory: a module named A will have its configuration
94 in modules/A/rbm.module.conf. Module configuration is used in
95 alphabetical order: configuration from a module named A will have
96 priority over a module named B.
97 An example rbm.conf file will look like this :
99 compress_tar: xz
101 output_dir: "out/[% project %]"
102 Adding a new project is done by creating a directory with the name of
104 the project inside the projects directory, and adding a config file in
105 this new directory. The config file contains the configuration for the
106 project. At the minimum it should contain the git_url configuration,
107 and any other configuration option you want to set for this project.
108 Projects can also be defined inside a module. In this case the module
110 directory will include a projects directory working in a similar way to
111 the main projects directory. If a project exists with the same name
112 both in a module and the main projects directory, the module one will
113 be ignored. If a project is defined in multiple modules, only the
114 project from the first module in alphabetic order will be used.
115
117 The following configuration options are available :
118 sysconf_file
120 The path to an optional system configuration file. The default is
121 /etc/rbm.conf. This can also be set with the --sysconf-file command
122 line parameter.
123 localconf_file
125 The path to an optional local configuration file. The default is
126 rbm.local.conf. If the path is relative, it is relative to the
127 directory where the rbm.conf file is located. This can also be set
128 with the --localconf-file command line parameter.
129 projects_dir
131 The directory containing the projects definitions. The default
132 value is projects.
133 git_clone_dir
135 The directory used to store clones of git repositories. The default
136 value is git_clones.
137 hg_clone_dir
139 The directory used to store clones of mercurial repositories. The
140 default value is hg_clones.
141 hg_clone_subdir
143 If this option is set, the repository is cloned in a subdirectory
144 with that name. This is useful if a single project requires clones
145 of multiple mercurial repositories, for example using a different
146 hg_url in each targets or steps. The default value is ., which
147 means that no subdirectory is used.
148 hg_opt
150 This option contains options that should be passed on the mercurial
151 command line. This can for instance be useful if you want to use
152 the --config option to enable some mercurial plugins.
153 tmp_dir
155 The directory used to create temporary directories and files. This
156 is the directory where builds will be done, so you want to use a
157 directory on a fast device, with enough space available. This
158 directory will contains some scripts that will be executed, so it
159 should not be on a partition mounted as noexec.
160 rbm_tmp_dir
162 A directory created inside tmp_dir using File::Temp, that you can
163 use to store temporary files. This directory is removed
164 automatically when rbm exits. When running scripts, the TMPDIR
165 environment variable is also set to this directory.
166 rbmdir
168 The directory where the rbm script is located.
169 output_dir
171 The directory where output files (tarballs, spec files or packages)
172 are created. The default value is out.
173 build_log
175 The file where the build logs will be written. If the value is -
176 (the default), the logs will be output on stdout and stderr.
177 build_log_append
179 If you set to build_log_append to 0, the log file (defined in
180 build_log) will be cleaned when starting a new build. The default
181 is 1.
182 fetch
184 The value should be 0 or 1, depending on whether the commits from
185 the remote git or hg repository should be fetched automatically. If
186 the value is if_needed, the git or hg repository is fetched only if
187 the selected commit cannot be found in the local clone. The default
188 is if_needed.
189 ENV
191 This option, defined in the workspace config, is a hash containing
192 the environment variables that will be defined when rbm is
193 starting. This is useful for defining variables that can affect how
194 the templates are processed (for instance the TZ variable if dates
195 are used). If this option is not defined TZ will be set to UTC and
196 LC_ALL to C.
197 git_url
199 The URL of a git repository that will be cloned and used to create
200 the tarball. If this option is set, git_hash should be set to
201 select the commit to use.
202 hg_url
204 The URL of a mercurial repository that will be cloned and used to
205 create the tarball. If this option is set, hg_hash should be set to
206 select the commit to use.
207 git_hash
209 A git hash, branch name or tag. This is what is used to create the
210 tarball.
211 hg_hash
213 A mercurial changeset hash. This is what is used to create the
214 tarball.
215 git_submodule
217 If this option is enabled, git submodules are fetched and included
218 in the tarball. This option is disabled by default.
219 git_depth
221 An integer specifying a depth for shallow Git clone/fetch depth, to
222 decrease network and storage usage. If not set, shallow clone/fetch
223 is disabled.
224 git_branch
226 A Git ref name that will be exclusively cloned/fetched, to decrease
227 network and storage usage. Must be a descendent (inclusive) of
228 git_hash. If not set, all Git refs are cloned/fetched.
229 compress_tar
231 If set, the tarball created will be compressed in the select
232 format. Possible values: xz, gz, bz2. The default is gz but it can
233 stay empty to disable compression.
234 commit_gpg_id
236 If set, the commit selected with git_hash will have its signature
237 checked. The tarball will not be created if there is no valid
238 signature, and if the key used to sign it does not match the key ID
239 from commit_gpg_id. The option can be set to a single gpg ID, or to
240 a list of gpg IDs. The IDs can be short or long IDs, or full
241 fingerprint (with no spaces). For this to work, the GPG keys should
242 be present in the selected keyring (see keyring option). If the
243 option is set to 1 or an array containing 1 then any key from the
244 selected keyring is accepted. On command line, the --commit-gpg-id
245 option can be listed multiple times to define a list of keys.
246 tag_gpg_id
248 If set, the commit selected with git_hash should be a tag and will
249 have its signature checked. The tarball will not be created if the
250 tag doesn’t have a valid signature, and if the key used to sign it
251 does not match the key ID from tag_gpg_id. The option can be set to
252 a single gpg ID, or to a list of gpg IDs. The IDs can be short or
253 long IDs, or full fingerprint (with no spaces). For this to work,
254 the GPG keys should be present in the selected keyring (see keyring
255 option). If the option is set to 1 or an array containing 1 then
256 any key from the selected keyring is accepted. On command line, the
257 --tag-gpg-id option can be listed multiple times to define a list
258 of keys.
259 gpg_wrapper
261 This is a template for a gpg wrapper script. The default wrapper
262 will call gpg with the keyring specified by option gpg_keyring if
263 defined.
264 gpg_keyring
266 The filename of the gpg keyring to use. Path is relative to the
267 keyring directory. This can also be an absolute path.
268 gpg_bin
270 The gpg command to be used. The default is gpg.
271 gpg_args
273 Optional gpg arguments. The default is empty.
274 gpg_allow_expired_keys
276 Allowing expired keys to successfully verify e.g. signed git tags.
277 By default this is not allowed.
278 arch
280 The architecture, as returned by uname -m.
281 version
283 Version number of the software. This is used to create the tarball,
284 and as the package version number.
285 distribution
287 The name of the distribution for which you wish to build a package.
288 The syntax is distribution-release. This value is used by the
289 lsb_release option.
290 lsb_release
292 A hash containing id (name of the distribution), codename and
293 release. This option is useful in template to do different things
294 for different distributions. By default, the output of the
295 lsb_release command will be used if available. If the distribution
296 option is defined, it will be used instead to for the id and
297 release (codename will be undefined).
298 target
300 The target for which you want to build. This is usually set on
301 command line. See rbm_targets(7) for details.
302 targets
304 The targets definitions. See rbm_targets(7) for details.
305 copy_files
307 A list of files that should be copied when building the package.
308 Path is relative to the project’s template directory.
309 input_files
311 Configuration for external input files. See rbm_input_files(7) for
312 details.
313 input_files_by_name
315 This option contains an hash of all the input_files filenames, with
316 their name as index. The input files without a name are not in this
317 hash.
318 input_files_id
320 The value of this option is an identifier of the input_files. When
321 any of the input files is changed, the identifier changes. This
322 identifier is something that can be used in a project’s filename to
323 trigger a rebuild when any of its input files is changed. This
324 identifier is based on: the input_file_id option of an input file
325 if it is present, the filename for an input file of type project,
326 the value of exec for an input file of type exec, and the filename
327 and the sha256sum of the file for any other type of input file. In
328 the case of an input file of type exec, the value of exec is
329 computed with getting_id set to true.
330 input_files_paths
332 The value of this option is an array of all the paths of input
333 files that currently exist and are used in the build of the current
334 project and its dependencies. This is useful when cleaning old
335 build files, to find which ones are still used.
336 link_input_files
338 When building a project, input files are collected in a temporary
339 directory. If this option is set to 1, we try to use hard links
340 instead of copies. You should only enable this if you don’t modify
341 the input files during the build, or if you are using remote_exec
342 (in which case the temporary directory is only used to copy files
343 to the remote). This option is disabled by default, unless
344 remote_exec is used.
345 timestamp
347 This is the UNIX timestamp, set as modification time on files
348 created such as the sources tarball. The default is to use the
349 commit time of the commit used. If set to 0 it will use the current
350 time.
351 notmpl
353 An array containing a list of options that should not be processed
354 as template (see the template section below for details).
355 step
357 The value of this option is the name of the build script we are
358 going to be running (by default build, but you could have an other
359 one for publishing your build, or for different types of
360 packaging). This option should be used read only. If you want to
361 change it, use the --step command line option, or the pkg_type
362 option.
363 steps
365 The steps definitions. See rbm_steps(7) for details.
366 build
368 This is the content of the build script used by the build command.
369 The default is to include the template file named build.
370 remote_exec
372 Run the build on a remote host. See rbm_remote(7) for details.
373 suexec
375 This options takes the suexec_cmd options, and make it run as root.
376 By default, it uses sudo for that. You need to set this option if
377 you want to use an other mechanism to run commands as root.
378 debug
380 This option enable or disable the debug mode. When enabled, a shell
381 will be opened in the temporary build directory in case of build
382 failure.
383 abbrev
385 This option returns the abbreviated commit hash of the git_hash or
386 hg_hash commit.
387 abbrev_length
389 This option sets the length of the abbreviated commits, when using
390 the abbrev option.
391 tar
393 Use this options instead of tar in build scripts when you want to
394 create deterministic tar files. This options set tar arguments so
395 that owner and group of files is set to root, and mtime is set to
396 timestamp. This option takes a tar_src argument which is an array
397 containing source files or directories, and a tar_args argument
398 which is the tar arguments to create the file (something like -cf
399 filename.tar). By default, GNU options are used in tar and find,
400 but you can disable that with gnu_utils.
401 zip
403 Use this option instead of zip in build scripts when you want to
404 create deterministic zip files. This option takes a zip_src
405 argument which is an array containing source files or directories,
406 and a zip_args arguments which is usually the destination zip file,
407 and optionally other zip options. By default, GNU options are used
408 in find, but you can disable that with gnu_utils.
409 install_package
411 This option can be used in a script when you need to install a
412 package. The packages to be installed should be set in option
413 pkg_name. It will use apt-get on Debian/Ubuntu, yum on Fedora,
414 zypper on openSUSE and urpmi on Mageia/Mandriva.
415 num_procs
417 This option allows to specify the number of CPUs used to
418 parallelize the build. By default it is set to whatever value nrpoc
419 is returning on the build machine.
420 touch
422 This option can be used to set the mtime of files to timestamp. It
423 expects the file to touch as as argument following on the same
424 line.
425 In addition to the configuration options listed here, you are free to
427 add any other options that you want, and use them in the template
428 files. Unfortunately this also means that you won’t have an error
429 message in case of typo in an option name.
430
432 The configuration is in YAML, but you can also use the perl syntax to
433 set some configuration options. A YAML file can contain multiple
434 documents, separated by a line with tree dashes (---). When reading a
435 configuration file, rbm will read all documents contained in the file,
436 and for each of them will :
437 • if the document is a hash, use it as configuration
439 • if the document is a string, evaluate it as perl, and get the
441 return value as as hash containing configuration
442 If multpiple documents define the same options, the value from the last
444 one override the values from previous documents.
445 A configuration file that includes perl code will look like this :
447 option_1: value 1
449 option_2: value 2
450 option_3: value 3
451 --- |
452 (
453 option_4 => "value 4",
454 option_5 => "value 5",
455 )
456 In this example, option_4 and option_5 and defined using perl syntax.
458 Note that the perl code block needs to be indented with at least one
459 space.
460 An interesting benefit of writting options in perl is that you can
462 define some options using a perl function reference. If the value of an
463 option is a function reference, then when that option is looked up the
464 function will be executed, and the value of the option will be the
465 return value of the function. The function will receive as parameters
466 the project’s name, an options array reference, and the option that is
467 queried.
468 An option defined using a perl function will look like this :
470 option_1: value 1
472 --- |
473 (
474 option_2 => "value 2",
475 option_3 => sub {
476 my ($project, @option) = @_;
477 return "value 3";
478 },
479 )
480
482 rbm(1), rbm_targets(7), rbm_templates(7), rbm_modules(7)
483 07/28/2023 RBM_CONFIG(7)