1RBM_CONFIG(7)                                                    RBM_CONFIG(7)
2
3
4

NAME

6       rbm_config - The rbm configuration
7

DESCRIPTION

9       All configuration options can be defined in 5 different places :
10
11       •   in the main configuration in your working directory (rbm.conf)
12
13       •   in the local configuration in your working directory
14           (rbm.local.conf)
15
16       •   in the global system configuration (/etc/rbm.conf)
17
18       •   in a project configuration
19
20       •   with a command line option
21
22       The option values are used with the following priority order :
23
24       •   command line options
25
26       •   project config for matching step and target
27
28       •   project config for matching step
29
30       •   project config for matching target
31
32       •   project config
33
34       •   local config for matching step and target
35
36       •   local config for matching step
37
38       •   local config for matching target
39
40       •   local config
41
42       •   workspace config for matching step and target
43
44       •   workspace config for matching step
45
46       •   workspace config for matching target
47
48       •   workspace config
49
50       •   system config for matching step and target
51
52       •   system config for matching step
53
54       •   system config for matching target
55
56       •   system config
57
58       •   default config
59
60       •   undefined
61
62       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
67       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
74       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
81       An example rbm.conf file will look like this :
82
83           projects_dir: projects
84           compress_tar: xz
85
86       The projects_dir option define the path to the directory containing the
87       projects definitions.
88
89       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

OPTIONS

97       The following configuration options are available :
98
99       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
104       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
110       projects_dir
111           The directory containing the projects definitions. The default
112           value is projects.
113
114       git_clone_dir
115           The directory used to store clones of git repositories. The default
116           value is git_clones.
117
118       hg_clone_dir
119           The directory used to store clones of mercurial repositories. The
120           default value is hg_clones.
121
122       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
127       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
134       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
139       output_dir
140           The directory where output files (tarballs, spec files or packages)
141           are created. The default value is out.
142
143       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
147       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
152       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
159       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
166       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
171       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
176       git_hash
177           A git hash, branch name or tag. This is what is used to create the
178           tarball.
179
180       hg_hash
181           A mercurial changeset hash. This is what is used to create the
182           tarball.
183
184       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
188       compress_tar
189           If set, the tarball created will be compressed in the select
190           format. Possible values: xz, gz, bz2.
191
192       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
204       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
217       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
222       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
226       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
231       gpg_bin
232           The gpg command to be used. The default is gpg.
233
234       gpg_args
235           Optional gpg arguments. The default is empty.
236
237       arch
238           The architecture, as returned by uname -m.
239
240       version
241           Version number of the software. This is used to create the tarball,
242           and as the package version number.
243
244       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
249       pkg_rel
250           Package release number.
251
252       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
257       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
265       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
269       targets
270           The targets definitions. See rbm_targets(7) for details.
271
272       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
276       input_files
277           Configuration for external input files. See rbm_input_files(7) for
278           details.
279
280       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
285       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
295       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
301       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
307       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
311       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
318       steps
319           The steps definitions. See rbm_steps(7) for details.
320
321       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
327       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
332       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
337       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
342       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
347       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
353       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
358       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
365       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
374       use_pbuilder
375           If set to a true value, pbuilder will be used to build the debian
376           packages.
377
378       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
382       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
389       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
393       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
399       remote_exec
400           Run the build on a remote host. See rbm_remote(7) for details.
401
402       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
407       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
412       abbrev
413           This option returns the abbreviated commit hash of the git_hash or
414           hg_hash commit.
415
416       abbrev_length
417           This option sets the length of the abbreviated commits, when using
418           the abbrev option.
419
420       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
429       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
436       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
442       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

WRITTING CONFIGURATION IN PERL

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
454       •   if the document is a hash, use it as configuration
455
456       •   if the document is a string, evaluate it as perl, and get the
457           return value as as hash containing configuration
458
459       If multpiple documents define the same options, the value from the last
460       one override the values from previous documents.
461
462       A configuration file that includes perl code will look like this :
463
464           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
473       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
477       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
485       An option defined using a perl function will look like this :
486
487           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

SEE ALSO

498       rbm(1), rbm_targets(7), rbm_templates(7)
499
500
501
502                                  01/21/2022                     RBM_CONFIG(7)
Impressum