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_opt
143 This option contains options that should be passed on the mercurial
144 command line. This can for instance be useful if you want to use
145 the --config option to enable some mercurial plugins.
146 tmp_dir
148 The directory used to create temporary directories and files. This
149 is the directory where builds will be done, so you want to use a
150 directory on a fast device, with enough space available. This
151 directory will contains some scripts that will be executed, so it
152 should not be on a partition mounted as noexec.
153 rbm_tmp_dir
155 A directory created inside tmp_dir using File::Temp, that you can
156 use to store temporary files. This directory is removed
157 automatically when rbm exits. When running scripts, the TMPDIR
158 environment variable is also set to this directory.
159 rbmdir
161 The directory where the rbm script is located.
162 output_dir
164 The directory where output files (tarballs, spec files or packages)
165 are created. The default value is out.
166 build_log
168 The file where the build logs will be written. If the value is -
169 (the default), the logs will be output on stdout and stderr.
170 build_log_append
172 If you set to build_log_append to 0, the log file (defined in
173 build_log) will be cleaned when starting a new build. The default
174 is 1.
175 fetch
177 The value should be 0 or 1, depending on whether the commits from
178 the remote git or hg repository should be fetched automatically. If
179 the value is if_needed, the git or hg repository is fetched only if
180 the selected commit cannot be found in the local clone. The default
181 is if_needed.
182 ENV
184 This option, defined in the workspace config, is a hash containing
185 the environment variables that will be defined when rbm is
186 starting. This is useful for defining variables that can affect how
187 the templates are processed (for instance the TZ variable if dates
188 are used). If this option is not defined TZ will be set to UTC and
189 LC_ALL to C.
190 git_url
192 The URL of a git repository that will be cloned and used to create
193 the tarball. If this option is set, git_hash should be set to
194 select the commit to use.
195 hg_url
197 The URL of a mercurial repository that will be cloned and used to
198 create the tarball. If this option is set, hg_hash should be set to
199 select the commit to use.
200 git_hash
202 A git hash, branch name or tag. This is what is used to create the
203 tarball.
204 hg_hash
206 A mercurial changeset hash. This is what is used to create the
207 tarball.
208 git_submodule
210 If this option is enabled, git submodules are fetched and included
211 in the tarball. This option is disabled by default.
212 compress_tar
214 If set, the tarball created will be compressed in the select
215 format. Possible values: xz, gz, bz2. The default is gz but it can
216 stay empty to disable compression.
217 commit_gpg_id
219 If set, the commit selected with git_hash will have its signature
220 checked. The tarball will not be created if there is no valid
221 signature, and if the key used to sign it does not match the key ID
222 from commit_gpg_id. The option can be set to a single gpg ID, or to
223 a list of gpg IDs. The IDs can be short or long IDs, or full
224 fingerprint (with no spaces). For this to work, the GPG keys should
225 be present in the selected keyring (see keyring option). If the
226 option is set to 1 or an array containing 1 then any key from the
227 selected keyring is accepted. On command line, the --commit-gpg-id
228 option can be listed multiple times to define a list of keys.
229 tag_gpg_id
231 If set, the commit selected with git_hash should be a tag and will
232 have its signature checked. The tarball will not be created if the
233 tag doesn’t have a valid signature, and if the key used to sign it
234 does not match the key ID from tag_gpg_id. The option can be set to
235 a single gpg ID, or to a list of gpg IDs. The IDs can be short or
236 long IDs, or full fingerprint (with no spaces). For this to work,
237 the GPG keys should be present in the selected keyring (see keyring
238 option). If the option is set to 1 or an array containing 1 then
239 any key from the selected keyring is accepted. On command line, the
240 --tag-gpg-id option can be listed multiple times to define a list
241 of keys.
242 gpg_wrapper
244 This is a template for a gpg wrapper script. The default wrapper
245 will call gpg with the keyring specified by option gpg_keyring if
246 defined.
247 gpg_keyring
249 The filename of the gpg keyring to use. Path is relative to the
250 keyring directory. This can also be an absolute path.
251 gpg_bin
253 The gpg command to be used. The default is gpg.
254 gpg_args
256 Optional gpg arguments. The default is empty.
257 gpg_allow_expired_keys
259 Allowing expired keys to successfully verify e.g. signed git tags.
260 By default this is not allowed.
261 arch
263 The architecture, as returned by uname -m.
264 version
266 Version number of the software. This is used to create the tarball,
267 and as the package version number.
268 distribution
270 The name of the distribution for which you wish to build a package.
271 The syntax is distribution-release. This value is used by the
272 lsb_release option.
273 lsb_release
275 A hash containing id (name of the distribution), codename and
276 release. This option is useful in template to do different things
277 for different distributions. By default, the output of the
278 lsb_release command will be used if available. If the distribution
279 option is defined, it will be used instead to for the id and
280 release (codename will be undefined).
281 target
283 The target for which you want to build. This is usually set on
284 command line. See rbm_targets(7) for details.
285 targets
287 The targets definitions. See rbm_targets(7) for details.
288 copy_files
290 A list of files that should be copied when building the package.
291 Path is relative to the project’s template directory.
292 input_files
294 Configuration for external input files. See rbm_input_files(7) for
295 details.
296 input_files_by_name
298 This option contains an hash of all the input_files filenames, with
299 their name as index. The input files without a name are not in this
300 hash.
301 input_files_id
303 The value of this option is an identifier of the input_files. When
304 any of the input files is changed, the identifier changes. This
305 identifier is something that can be used in a project’s filename to
306 trigger a rebuild when any of its input files is changed. This
307 identifier is based on: the input_file_id option of an input file
308 if it is present, the filename for an input file of type project,
309 the value of exec for an input file of type exec, and the filename
310 and the sha256sum of the file for any other type of input file. In
311 the case of an input file of type exec, the value of exec is
312 computed with getting_id set to true.
313 input_files_paths
315 The value of this option is an array of all the paths of input
316 files that currently exist and are used in the build of the current
317 project and its dependencies. This is useful when cleaning old
318 build files, to find which ones are still used.
319 link_input_files
321 When building a project, input files are collected in a temporary
322 directory. If this option is set to 1, we try to use hard links
323 instead of copies. You should only enable this if you don’t modify
324 the input files during the build, or if you are using remote_exec
325 (in which case the temporary directory is only used to copy files
326 to the remote). This option is disabled by default, unless
327 remote_exec is used.
328 timestamp
330 This is the UNIX timestamp, set as modification time on files
331 created such as the sources tarball. The default is to use the
332 commit time of the commit used. If set to 0 it will use the current
333 time.
334 notmpl
336 An array containing a list of options that should not be processed
337 as template (see the template section below for details).
338 step
340 The value of this option is the name of the build script we are
341 going to be running (by default build, but you could have an other
342 one for publishing your build, or for different types of
343 packaging). This option should be used read only. If you want to
344 change it, use the --step command line option, or the pkg_type
345 option.
346 steps
348 The steps definitions. See rbm_steps(7) for details.
349 build
351 This is the content of the build script used by the build command.
352 The default is to include the template file named build.
353 remote_exec
355 Run the build on a remote host. See rbm_remote(7) for details.
356 suexec
358 This options takes the suexec_cmd options, and make it run as root.
359 By default, it uses sudo for that. You need to set this option if
360 you want to use an other mechanism to run commands as root.
361 debug
363 This option enable or disable the debug mode. When enabled, a shell
364 will be opened in the temporary build directory in case of build
365 failure.
366 abbrev
368 This option returns the abbreviated commit hash of the git_hash or
369 hg_hash commit.
370 abbrev_length
372 This option sets the length of the abbreviated commits, when using
373 the abbrev option.
374 tar
376 Use this options instead of tar in build scripts when you want to
377 create deterministic tar files. This options set tar arguments so
378 that owner and group of files is set to root, and mtime is set to
379 timestamp. This option takes a tar_src argument which is an array
380 containing source files or directories, and a tar_args argument
381 which is the tar arguments to create the file (something like -cf
382 filename.tar). By default, GNU options are used in tar and find,
383 but you can disable that with gnu_utils.
384 zip
386 Use this option instead of zip in build scripts when you want to
387 create deterministic zip files. This option takes a zip_src
388 argument which is an array containing source files or directories,
389 and a zip_args arguments which is usually the destination zip file,
390 and optionally other zip options. By default, GNU options are used
391 in find, but you can disable that with gnu_utils.
392 install_package
394 This option can be used in a script when you need to install a
395 package. The packages to be installed should be set in option
396 pkg_name. It will use apt-get on Debian/Ubuntu, yum on Fedora,
397 zypper on openSUSE and urpmi on Mageia/Mandriva.
398 num_procs
400 This option allows to specify the number of CPUs used to
401 parallelize the build. By default it is set to whatever value nrpoc
402 is returning on the build machine.
403 touch
405 This option can be used to set the mtime of files to timestamp. It
406 expects the file to touch as as argument following on the same
407 line.
408 In addition to the configuration options listed here, you are free to
410 add any other options that you want, and use them in the template
411 files. Unfortunately this also means that you won’t have an error
412 message in case of typo in an option name.
413
415 The configuration is in YAML, but you can also use the perl syntax to
416 set some configuration options. A YAML file can contain multiple
417 documents, separated by a line with tree dashes (---). When reading a
418 configuration file, rbm will read all documents contained in the file,
419 and for each of them will :
420 • if the document is a hash, use it as configuration
422 • if the document is a string, evaluate it as perl, and get the
424 return value as as hash containing configuration
425 If multpiple documents define the same options, the value from the last
427 one override the values from previous documents.
428 A configuration file that includes perl code will look like this :
430 option_1: value 1
432 option_2: value 2
433 option_3: value 3
434 --- |
435 (
436 option_4 => "value 4",
437 option_5 => "value 5",
438 )
439 In this example, option_4 and option_5 and defined using perl syntax.
441 Note that the perl code block needs to be indented with at least one
442 space.
443 An interesting benefit of writting options in perl is that you can
445 define some options using a perl function reference. If the value of an
446 option is a function reference, then when that option is looked up the
447 function will be executed, and the value of the option will be the
448 return value of the function. The function will receive as parameters
449 the project’s name, an options array reference, and the option that is
450 queried.
451 An option defined using a perl function will look like this :
453 option_1: value 1
455 --- |
456 (
457 option_2 => "value 2",
458 option_3 => sub {
459 my ($project, @option) = @_;
460 return "value 3";
461 },
462 )
463
465 rbm(1), rbm_targets(7), rbm_templates(7), rbm_modules(7)
466 01/20/2023 RBM_CONFIG(7)