1RBM_CONFIG(7) RBM_CONFIG(7)
2
6 rbm_config - The rbm configuration
7
9 All configuration options can be defined in 5 different places :
10 • in the main configuration in your working directory (rbm.conf)
12 • in the local configuration in your working directory
14 (rbm.local.conf)
15 • in the global system configuration (/etc/rbm.conf)
17 • in a project configuration
19 • with a command line option
21 The option values are used with the following priority order :
23 • command line options
25 • project config for matching step and target
27 • project config for matching step
29 • project config for matching target
31 • project config
33 • local config for matching step and target
35 • local config for matching step
37 • local config for matching target
39 • local config
41 • workspace config for matching step and target
43 • workspace config for matching step
45 • workspace config for matching target
47 • workspace config
49 • system config for matching step and target
51 • system config for matching step
53 • system config for matching target
55 • system config
57 • default config
59 • undefined
61 The system configuration is by default located at /etc/rbm.conf, or the
63 path defined in the sysconf_file option. If the path does not exists,
64 it is ignored. This is where you will put configuration only relevant
65 to your local use of rbm.
66 The main configuration file is rbm.conf, in YAML format. It can be
68 located anywhere on your filesystem, but you will need to run the rbm
69 commands from the same directory, or one of its subdirectories. This is
70 where you will put configuration relevant to all projects under this
71 working directory. All relative paths used in the configuration are
72 relative from the rbm.conf location.
73 The local configuration file is rbm.local.conf (or the file defined by
75 the localconf_file option), in the same directory as the rbm.conf file.
76 If the file does not exists, it is ignored. The rbm.local.conf file is
77 used to override some options from rbm.conf relevent to your local
78 setup, whithout modifying the rbm.conf file which is usually maintained
79 in a VCS.
80 An example rbm.conf file will look like this :
82 projects_dir: projects
84 compress_tar: xz
85 The projects_dir option define the path to the directory containing the
87 projects definitions.
88 Adding a new project is done by creating a directory with the name of
90 the project inside the projects_dir directory, and adding a config file
91 in this new directory. The config file contains the configuration for
92 the project. At the minimum it should contain the git_url
93 configuration, and any other configuration option you want to set for
94 this project.
95
97 The following configuration options are available :
98 sysconf_file
100 The path to an optional system configuration file. The default is
101 /etc/rbm.conf. This can also be set with the --sysconf-file command
102 line parameter.
103 localconf_file
105 The path to an optional local configuration file. The default is
106 rbm.local.conf. If the path is relative, it is relative to the
107 directory where the rbm.conf file is located. This can also be set
108 with the --localconf-file command line parameter.
109 projects_dir
111 The directory containing the projects definitions. The default
112 value is projects.
113 git_clone_dir
115 The directory used to store clones of git repositories. The default
116 value is git_clones.
117 hg_clone_dir
119 The directory used to store clones of mercurial repositories. The
120 default value is hg_clones.
121 hg_opt
123 This option contains options that should be passed on the mercurial
124 command line. This can for instance be useful if you want to use
125 the --config option to enable some mercurial plugins.
126 tmp_dir
128 The directory used to create temporary directories and files. This
129 is the directory where builds will be done, so you want to use a
130 directory on a fast device, with enough space available. This
131 directory will contains some scripts that will be executed, so it
132 should not be on a partition mounted as noexec.
133 rbm_tmp_dir
135 A directory created inside tmp_dir using File::Temp, that you can
136 use to store temporary files. This directory is removed
137 automatically when rbm exits.
138 output_dir
140 The directory where output files (tarballs, spec files or packages)
141 are created. The default value is out.
142 build_log
144 The file where the build logs will be written. If the value is -
145 (the default), the logs will be output on stdout and stderr.
146 build_log_append
148 If you set to build_log_append to 0, the log file (defined in
149 build_log) will be cleaned when starting a new build. The default
150 is 1.
151 fetch
153 The value should be 0 or 1, depending on whether the commits from
154 the remote git or hg repository should be fetched automatically. If
155 the value is if_needed, the git or hg repository is fetched only if
156 the selected commit cannot be found in the local clone. The default
157 is if_needed.
158 ENV
160 This option, defined in the workspace config, is a hash containing
161 the environment variables that will be defined when rbm is
162 starting. This is useful for defining variables that can affect how
163 the templates are processed (for instance the TZ variable if dates
164 are used).
165 git_url
167 The URL of a git repository that will be cloned and used to create
168 the tarball. If this option is set, git_hash should be set to
169 select the commit to use.
170 hg_url
172 The URL of a mercurial repository that will be cloned and used to
173 create the tarball. If this option is set, hg_hash should be set to
174 select the commit to use.
175 git_hash
177 A git hash, branch name or tag. This is what is used to create the
178 tarball.
179 hg_hash
181 A mercurial changeset hash. This is what is used to create the
182 tarball.
183 git_submodule
185 If this option is enabled, git submodules are fetched and included
186 in the tarball. This option is disabled by default.
187 compress_tar
189 If set, the tarball created will be compressed in the select
190 format. Possible values: xz, gz, bz2.
191 commit_gpg_id
193 If set, the commit selected with git_hash will have its signature
194 checked. The tarball will not be created if there is no valid
195 signature, and if the key used to sign it does not match the key ID
196 from commit_gpg_id. The option can be set to a single gpg ID, or to
197 a list of gpg IDs. The IDs can be short or long IDs, or full
198 fingerprint (with no spaces). For this to work, the GPG keys should
199 be present in the selected keyring (see keyring option). If the
200 option is set to 1 or an array containing 1 then any key from the
201 selected keyring is accepted. On command line, the --commit-gpg-id
202 option can be listed multiple times to define a list of keys.
203 tag_gpg_id
205 If set, the commit selected with git_hash should be a tag and will
206 have its signature checked. The tarball will not be created if the
207 tag doesn’t have a valid signature, and if the key used to sign it
208 does not match the key ID from tag_gpg_id. The option can be set to
209 a single gpg ID, or to a list of gpg IDs. The IDs can be short or
210 long IDs, or full fingerprint (with no spaces). For this to work,
211 the GPG keys should be present in the selected keyring (see keyring
212 option). If the option is set to 1 or an array containing 1 then
213 any key from the selected keyring is accepted. On command line, the
214 --tag-gpg-id option can be listed multiple times to define a list
215 of keys.
216 gpg_wrapper
218 This is a template for a gpg wrapper script. The default wrapper
219 will call gpg with the keyring specified by option gpg_keyring if
220 defined.
221 gpg_keyring
223 The filename of the gpg keyring to use. Path is relative to the
224 gpg_keyring_dir directory. This can also be an absolute path.
225 gpg_keyring_dir
227 The directory containing gpg keyring files. The default is
228 $basedir/keyring (with $basedir the directory where the main config
229 file is located).
230 gpg_bin
232 The gpg command to be used. The default is gpg.
233 gpg_args
235 Optional gpg arguments. The default is empty.
236 arch
238 The architecture, as returned by uname -m.
239 version
241 Version number of the software. This is used to create the tarball,
242 and as the package version number.
243 version_command
245 A command to run in the checked out source tree to determine the
246 version, if the version option is not set. The command should print
247 the version on stdout.
248 pkg_rel
250 Package release number.
251 distribution
253 The name of the distribution for which you wish to build a package.
254 The syntax is distribution-release. This value is used by the
255 lsb_release option.
256 lsb_release
258 A hash containing id (name of the distribution), codename and
259 release. This option is useful in template to do different things
260 for different distributions. By default, the output of the
261 lsb_release command will be used if available. If the distribution
262 option is defined, it will be used instead to for the id and
263 release (codename will be undefined).
264 target
266 The target for which you want to build. This is usually set on
267 command line. See rbm_targets(7) for details.
268 targets
270 The targets definitions. See rbm_targets(7) for details.
271 copy_files
273 A list of files that should be copied when building the package.
274 Path is relative to the project’s template directory.
275 input_files
277 Configuration for external input files. See rbm_input_files(7) for
278 details.
279 input_files_by_name
281 This option contains an hash of all the input_files filenames, with
282 their name as index. The input files without a name are not in this
283 hash.
284 input_files_id
286 The value of this option is an identifier of the input_files. When
287 any of the input files is changed, the identifier changes. This
288 identifier is something that can be used in a project’s filename to
289 trigger a rebuild when any of its input files is changed. This
290 identifier is based on: the input_file_id option of an input file
291 if it is present, the filename for an input file of type project,
292 and the filename and the sha256sum of the file for any other type
293 of input file.
294 input_files_paths
296 The value of this option is an array of all the paths of input
297 files that currently exist and are used in the build of the current
298 project and its dependencies. This is useful when cleaning old
299 build files, to find which ones are still used.
300 timestamp
302 This is the UNIX timestamp, set as modification time on files
303 created such as the sources tarball and rpm spec file. The default
304 is to use the commit time of the commit used. If set to 0 it will
305 use the current time.
306 notmpl
308 An array containing a list of options that should not be processed
309 as template (see the template section below for details).
310 step
312 The value of this option is the name of the build script we are
313 going to be running (deb if building a Debian package, rpm if
314 building an rpm, etc ...). This can be useful in the input_files
315 definition, if you want to enable an input file only for some type
316 of package. This option should be used read only.
317 steps
319 The steps definitions. See rbm_steps(7) for details.
320 rpm_rel
322 RPM package release number. The default is to use the option
323 pkg_rel if defined, otherwise use a release number containing the
324 number of commits since the last git tag, and the hash of the
325 commit used.
326 rpmspec
328 This is the content of the rpm spec file, used by the rpm and srpm
329 commands. The default is to include the template file named
330 project.spec (with project replaced by the project’s name).
331 rpmbuild
333 This is the content of the script to build a rpm or srpm. It is
334 using the rpmbuild_action option to select the build action (-bs to
335 build a source package, or -ba to build all packages).
336 rpm
338 This is the script that is used to build an rpm package, in the rpm
339 command. By default it is using the rpmbuild option with the -ba
340 action.
341 srpm
343 This is the script that is used to build a source rpm package, in
344 the srpm command. By default it is using the rpmbuild option with
345 the -bs action.
346 debian_revision
348 The package revision used in debian packages. By default, when the
349 option pkg_rel is defined, this is what is used. Otherwise a
350 revision containing the number of commits since the last git tag,
351 and the hash of the commit is used.
352 deb_src
354 This is the script that is used to create the debian source
355 package. By default it will use the debian files listed in the
356 option debian_files and create the source package with dpkg-source.
357 deb
359 This is the script that is used to create the debian packages. By
360 default it will use the debian files listed in the option
361 debian_files and build the package using debuild or pdebuild
362 depending on whether the use_pbuilder option is set. The packages
363 will be signed using the key defined in the option debsign_keyid.
364 debian_files
366 This is an array containing the files to create in the debian
367 directory. Each item in the array is an hash, with the following
368 two keys : name is the file name in the debian directory of the
369 file to create, and content is the content of the file. The
370 filename and content are processed as template, so for instance if
371 you want to store the content of a file in a separate file, you can
372 use the INCLUDE directive.
373 use_pbuilder
375 If set to a true value, pbuilder will be used to build the debian
376 packages.
377 debsign_keyid
379 This is the gpg key that will be used to sign the debian packages.
380 Set to 0 if you don’t want to sign the packages.
381 pkg_type
383 This is the name of the option that will be used by the pkg command
384 as the script to build the package. This can be rpm or deb for rpm
385 and debian packages. This option is usually set in distribution
386 specific configuration as it depends on the distribution being
387 used.
388 build
390 This is the content of the build script used by the build command.
391 The default is to include the template file named build.
392 publish
394 This is the content of the script that is used to upload the
395 packages or files to a repository. This script will be executed
396 from the directory containing the files to publish. This option has
397 no default value.
398 remote_exec
400 Run the build on a remote host. See rbm_remote(7) for details.
401 suexec
403 This options takes the suexec_cmd options, and make it run as root.
404 By default, it uses sudo for that. You need to set this option if
405 you want to use an other mechanism to run commands as root.
406 debug
408 This option enable or disable the debug mode. When enabled, a shell
409 will be opened in the temporary build directory in case of build
410 failure.
411 abbrev
413 This option returns the abbreviated commit hash of the git_hash or
414 hg_hash commit.
415 abbrev_length
417 This option sets the length of the abbreviated commits, when using
418 the abbrev option.
419 tar
421 Use this options instead of tar in build scripts when you want to
422 create deterministic tar files. This options set tar arguments so
423 that owner and group of files is set to root, and mtime is set to
424 timestamp. This option takes a tar_src argument which is an array
425 containing source files or directories, and a tar_args argument
426 which is the tar arguments to create the file (something like -cf
427 filename.tar).
428 zip
430 Use this option instead of zip in build scripts when you want to
431 create deterministic zip files. This option takes a zip_src
432 argument which is an array containing source files or directories,
433 and a zip_args arguments which is usually the destination zip file,
434 and optionaly other zip options.
435 install_package
437 This option can be used in a script when you need to install a
438 package. The packages to be installed should be set in option
439 pkg_name. It will use apt-get on Debian/Ubuntu, yum on Fedora,
440 zypper on openSUSE and urpmi on Mageia/Mandriva.
441 In addition to the configuration options listed here, you are free to
443 add any other options that you want, and use them in the template
444 files. Unfortunately this also means that you won’t have an error
445 message in case of typo in an option name.
446
448 The configuration is in YAML, but you can also use the perl syntax to
449 set some configuration options. A YAML file can contain multiple
450 documents, separated by a line with tree dashes (---). When reading a
451 configuration file, rbm will read all documents contained in the file,
452 and for each of them will :
453 • if the document is a hash, use it as configuration
455 • if the document is a string, evaluate it as perl, and get the
457 return value as as hash containing configuration
458 If multpiple documents define the same options, the value from the last
460 one override the values from previous documents.
461 A configuration file that includes perl code will look like this :
463 option_1: value 1
465 option_2: value 2
466 option_3: value 3
467 --- |
468 (
469 option_4 => "value 4",
470 option_5 => "value 5",
471 )
472 In this example, option_4 and option_5 and defined using perl syntax.
474 Note that the perl code block needs to be indented with at least one
475 space.
476 An interesting benefit of writting options in perl is that you can
478 define some options using a perl function reference. If the value of an
479 option is a function reference, then when that option is looked up the
480 function will be executed, and the value of the option will be the
481 return value of the function. The function will receive as parameters
482 the project’s name, an options array reference, and the option that is
483 queried.
484 An option defined using a perl function will look like this :
486 option_1: value 1
488 --- |
489 (
490 option_2 => "value 2",
491 option_3 => sub {
492 my ($project, @option) = @_;
493 return "value 3";
494 },
495 )
496
498 rbm(1), rbm_targets(7), rbm_templates(7)
499 01/21/2022 RBM_CONFIG(7)