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 different places :
10
11       •   in the main configuration in your working directory (rbm.conf)
12
13       •   in a module configuration at the root of a module directory
14           (rbm.module.conf)
15
16       •   in the local configuration in your working directory
17           (rbm.local.conf)
18
19       •   in the global system configuration (/etc/rbm.conf)
20
21       •   in a project configuration
22
23       •   with a command line option
24
25       The option values are used with the following priority order :
26
27       •   command line options
28
29       •   project config for matching step and target
30
31       •   project config for matching step
32
33       •   project config for matching target
34
35       •   project config
36
37       •   local config for matching step and target
38
39       •   local config for matching step
40
41       •   local config for matching target
42
43       •   local config
44
45       •   workspace config for matching step and target
46
47       •   workspace config for matching step
48
49       •   workspace config for matching target
50
51       •   workspace config
52
53       •   modules config for matching step and target
54
55       •   modules config for matching step
56
57       •   modules config for matching target
58
59       •   modules config
60
61       •   system config for matching step and target
62
63       •   system config for matching step
64
65       •   system config for matching target
66
67       •   system config
68
69       •   default config
70
71       •   undefined
72
73       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
78       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
85       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
92       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
98       An example rbm.conf file will look like this :
99
100           compress_tar: xz
101           output_dir: "out/[% project %]"
102
103       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
109       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

OPTIONS

117       The following configuration options are available :
118
119       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
124       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
130       projects_dir
131           The directory containing the projects definitions. The default
132           value is projects.
133
134       git_clone_dir
135           The directory used to store clones of git repositories. The default
136           value is git_clones.
137
138       hg_clone_dir
139           The directory used to store clones of mercurial repositories. The
140           default value is hg_clones.
141
142       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
147       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
154       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
160       rbmdir
161           The directory where the rbm script is located.
162
163       output_dir
164           The directory where output files (tarballs, spec files or packages)
165           are created. The default value is out.
166
167       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
171       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
176       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
183       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
191       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
196       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
201       git_hash
202           A git hash, branch name or tag. This is what is used to create the
203           tarball.
204
205       hg_hash
206           A mercurial changeset hash. This is what is used to create the
207           tarball.
208
209       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
213       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
218       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
230       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
243       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
248       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
252       gpg_bin
253           The gpg command to be used. The default is gpg.
254
255       gpg_args
256           Optional gpg arguments. The default is empty.
257
258       gpg_allow_expired_keys
259           Allowing expired keys to successfully verify e.g. signed git tags.
260           By default this is not allowed.
261
262       arch
263           The architecture, as returned by uname -m.
264
265       version
266           Version number of the software. This is used to create the tarball,
267           and as the package version number.
268
269       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
274       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
282       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
286       targets
287           The targets definitions. See rbm_targets(7) for details.
288
289       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
293       input_files
294           Configuration for external input files. See rbm_input_files(7) for
295           details.
296
297       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
302       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
314       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
320       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
329       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
335       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
339       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
347       steps
348           The steps definitions. See rbm_steps(7) for details.
349
350       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
354       remote_exec
355           Run the build on a remote host. See rbm_remote(7) for details.
356
357       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
362       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
367       abbrev
368           This option returns the abbreviated commit hash of the git_hash or
369           hg_hash commit.
370
371       abbrev_length
372           This option sets the length of the abbreviated commits, when using
373           the abbrev option.
374
375       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
385       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
393       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
399       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
404       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
409       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

WRITTING CONFIGURATION IN PERL

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
421       •   if the document is a hash, use it as configuration
422
423       •   if the document is a string, evaluate it as perl, and get the
424           return value as as hash containing configuration
425
426       If multpiple documents define the same options, the value from the last
427       one override the values from previous documents.
428
429       A configuration file that includes perl code will look like this :
430
431           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
440       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
444       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
452       An option defined using a perl function will look like this :
453
454           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

SEE ALSO

465       rbm(1), rbm_targets(7), rbm_templates(7), rbm_modules(7)
466
467
468
469                                  01/20/2023                     RBM_CONFIG(7)
Impressum