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 3 different places :
10
11       ·   in the main configuration in your working directory
12
13       ·   in the global system configuration
14
15       ·   in a project configuration
16
17       ·   with a command line option
18
19       The option values are used with the following priority order :
20
21       ·   command line options
22
23       ·   project config for matching step and target
24
25       ·   project config for matching step
26
27       ·   project config for matching target
28
29       ·   project config
30
31       ·   workspace config for matching step and target
32
33       ·   workspace config for matching step
34
35       ·   workspace config for matching target
36
37       ·   workspace config
38
39       ·   system config for matching step and target
40
41       ·   system config for matching step
42
43       ·   system config for matching target
44
45       ·   system config
46
47       ·   default config
48
49       ·   undefined
50
51       The system configuration is by default located at /etc/rbm.conf, or the
52       path defined in the sysconf_file option. If the path does not exists,
53       it is ignored. This is where you will put configuration only relevant
54       to your local use of rbm.
55
56       The main configuration file is rbm.conf, in YAML format. It can be
57       located anywhere on your filesystem, but you will need to run the rbm
58       commands from the same directory, or one of its subdirectories. This is
59       where you will put configuration relevant to all projects under this
60       working directory. All relative paths used in the configuration are
61       relative from the rbm.conf location.
62
63       An example rbm.conf file will look like this :
64
65           projects_dir: projects
66           compress_tar: xz
67
68       The projects_dir option define the path to the directory containing the
69       projects definitions.
70
71       Adding a new project is done by creating a directory with the name of
72       the project inside the projects_dir directory, and adding a config file
73       in this new directory. The config file contains the configuration for
74       the project. At the minimum it should contain the git_url
75       configuration, and any other configuration option you want to set for
76       this project.
77

OPTIONS

79       The following configuration options are available :
80
81       sysconf_file
82           The path to an optional system configuration file. The default is
83           /etc/rbm.conf. This can also be set with the --sysconf-file command
84           line parameter.
85
86       projects_dir
87           The directory containing the projects definitions. The default
88           value is projects.
89
90       git_clone_dir
91           The directory used to store clones of git repositories. The default
92           value is git_clones.
93
94       hg_clone_dir
95           The directory used to store clones of mercurial repositories. The
96           default value is hg_clones.
97
98       hg_opt
99           This option contains options that should be passed on the mercurial
100           command line. This can for instance be useful if you want to use
101           the --config option to enable some mercurial plugins.
102
103       tmp_dir
104           The directory used to create temporary directories and files. This
105           is the directory where builds will be done, so you want to use a
106           directory on a fast device, with enough space available. This
107           directory will contains some scripts that will be executed, so it
108           should not be on a partition mounted as noexec.
109
110       output_dir
111           The directory where output files (tarballs, spec files or packages)
112           are created. The default value is out.
113
114       fetch
115           The value should be 0 or 1, depending on whether the commits from
116           the remote git or hg repository should be fetched automatically. If
117           the value is if_needed, the git or hg repository is fetched only if
118           the selected commit cannot be found in the local clone. The default
119           is if_needed.
120
121       git_url
122           The URL of a git repository that will be cloned and used to create
123           the tarball. If this option is set, git_hash should be set to
124           select the commit to use.
125
126       hg_url
127           The URL of a mercurial repository that will be cloned and used to
128           create the tarball. If this option is set, hg_hash should be set to
129           select the commit to use.
130
131       git_hash
132           A git hash, branch name or tag. This is what is used to create the
133           tarball.
134
135       hg_hash
136           A mercurial changeset hash. This is what is used to create the
137           tarball.
138
139       compress_tar
140           If set, the tarball created will be compressed in the select
141           format. Possible values: xz, gz, bz2.
142
143       commit_gpg_id
144           If set, the commit selected with git_hash will have its signature
145           checked. The tarball will not be created if there is no valid
146           signature, and if the key used to sign it does not match the key ID
147           from commit_gpg_id. The option can be set to a single gpg ID, or to
148           a list of gpg IDs. The IDs can be short or long IDs, or full
149           fingerprint (with no spaces). For this to work, the GPG keys should
150           be present in the selected keyring (see keyring option). If the
151           option is set to 1 or an array containing 1 then any key from the
152           selected keyring is accepted. On command line, the --commit-gpg-id
153           option can be listed multiple times to define a list of keys.
154
155       tag_gpg_id
156           If set, the commit selected with git_hash should be a tag and will
157           have its signature checked. The tarball will not be created if the
158           tag doesn’t have a valid signature, and if the key used to sign it
159           does not match the key ID from tag_gpg_id. The option can be set to
160           a single gpg ID, or to a list of gpg IDs. The IDs can be short or
161           long IDs, or full fingerprint (with no spaces). For this to work,
162           the GPG keys should be present in the selected keyring (see keyring
163           option). If the option is set to 1 or an array containing 1 then
164           any key from the selected keyring is accepted. On command line, the
165           --tag-gpg-id option can be listed multiple times to define a list
166           of keys.
167
168       gpg_wrapper
169           This is a template for a gpg wrapper script. The default wrapper
170           will call gpg with the keyring specified by option gpg_keyring if
171           defined.
172
173       gpg_keyring
174           The filename of the gpg keyring to use. Path is relative to the
175           gpg_keyring_dir directory. This can also be an absolute path.
176
177       gpg_keyring_dir
178           The directory containing gpg keyring files. The default is
179           $basedir/keyring (with $basedir the directory where the main config
180           file is located).
181
182       gpg_bin
183           The gpg command to be used. The default is gpg.
184
185       gpg_args
186           Optional gpg arguments. The default is empty.
187
188       arch
189           The architecture, as returned by uname -m.
190
191       version
192           Version number of the software. This is used to create the tarball,
193           and as the package version number.
194
195       version_command
196           A command to run in the checked out source tree to determine the
197           version, if the version option is not set. The command should print
198           the version on stdout.
199
200       pkg_rel
201           Package release number.
202
203       distribution
204           The name of the distribution for which you wish to build a package.
205           The syntax is distribution-release. This value is used by the
206           lsb_release option.
207
208       lsb_release
209           A hash containing id (name of the distribution), codename and
210           release. This option is useful in template to do different things
211           for different distributions. By default, the output of the
212           lsb_release command will be used if available. If the distribution
213           option is defined, it will be used instead to for the id and
214           release (codename will be undefined).
215
216       target
217           The target for which you want to build. This is usually set on
218           command line. See rbm_targets(7) for details.
219
220       targets
221           The targets definitions. See rbm_targets(7) for details.
222
223       copy_files
224           A list of files that should be copied when building the package.
225           Path is relative to the project’s template directory.
226
227       input_files
228           Configuration for external input files. See rbm_input_files(7) for
229           details.
230
231       input_files_by_name
232           This option contains an hash of all the input_files filenames, with
233           their name as index. The input files without a name are not in this
234           hash.
235
236       input_files_id
237           The value of this option is an identifier of the input_files. When
238           any of the input files is changed, the identifier changes. This
239           identifier is something that can be used in a project’s filename to
240           trigger a rebuild when any of its input files is changed. This
241           identifier is based on: the input_file_id option of an input file
242           if it is present, the filename for an input file of type project,
243           and the filename and the sha256sum of the file for any other type
244           of input file.
245
246       timestamp
247           This is the UNIX timestamp, set as modification time on files
248           created such as the sources tarball and rpm spec file. The default
249           is to use the commit time of the commit used. If set to 0 it will
250           use the current time.
251
252       notmpl
253           An array containing a list of options that should not be processed
254           as template (see the template section below for details).
255
256       step
257           The value of this option is the name of the build script we are
258           going to be running (deb if building a Debian package, rpm if
259           building an rpm, etc ...). This can be useful in the input_files
260           definition, if you want to enable an input file only for some type
261           of package. This option should be used read only.
262
263       steps
264           The steps definitions. See rbm_steps(7) for details.
265
266       rpm_rel
267           RPM package release number. The default is to use the option
268           pkg_rel if defined, otherwise use a release number containing the
269           number of commits since the last git tag, and the hash of the
270           commit used.
271
272       rpmspec
273           This is the content of the rpm spec file, used by the rpm and srpm
274           commands. The default is to include the template file named
275           project.spec (with project replaced by the project’s name).
276
277       rpmbuild
278           This is the content of the script to build a rpm or srpm. It is
279           using the rpmbuild_action option to select the build action (-bs to
280           build a source package, or -ba to build all packages).
281
282       rpm
283           This is the script that is used to build an rpm package, in the rpm
284           command. By default it is using the rpmbuild option with the -ba
285           action.
286
287       srpm
288           This is the script that is used to build a source rpm package, in
289           the srpm command. By default it is using the rpmbuild option with
290           the -bs action.
291
292       debian_revision
293           The package revision used in debian packages. By default, when the
294           option pkg_rel is defined, this is what is used. Otherwise a
295           revision containing the number of commits since the last git tag,
296           and the hash of the commit is used.
297
298       deb_src
299           This is the script that is used to create the debian source
300           package. By default it will use the debian files listed in the
301           option debian_files and create the source package with dpkg-source.
302
303       deb
304           This is the script that is used to create the debian packages. By
305           default it will use the debian files listed in the option
306           debian_files and build the package using debuild or pdebuild
307           depending on whether the use_pbuilder option is set. The packages
308           will be signed using the key defined in the option debsign_keyid.
309
310       debian_files
311           This is an array containing the files to create in the debian
312           directory. Each item in the array is an hash, with the following
313           two keys : name is the file name in the debian directory of the
314           file to create, and content is the content of the file. The
315           filename and content are processed as template, so for instance if
316           you want to store the content of a file in a separate file, you can
317           use the INCLUDE directive.
318
319       use_pbuilder
320           If set to a true value, pbuilder will be used to build the debian
321           packages.
322
323       debsign_keyid
324           This is the gpg key that will be used to sign the debian packages.
325           Set to 0 if you don’t want to sign the packages.
326
327       pkg_type
328           This is the name of the option that will be used by the pkg command
329           as the script to build the package. This can be rpm or deb for rpm
330           and debian packages. This option is usually set in distribution
331           specific configuration as it depends on the distribution being
332           used.
333
334       build
335           This is the content of the build script used by the build command.
336           The default is to include the template file named build.
337
338       publish
339           This is the content of the script that is used to upload the
340           packages or files to a repository. This script will be executed
341           from the directory containing the files to publish. This option has
342           no default value.
343
344       remote_exec
345           Run the build on a remote host. See rbm_remote(7) for details.
346
347       suexec
348           This options takes the suexec_cmd options, and make it run as root.
349           By default, it uses sudo for that. You need to set this option if
350           you want to use an other mechanism to run commands as root.
351
352       debug
353           This option enable or disable the debug mode. When enabled, a shell
354           will be opened in the temporary build directory in case of build
355           failure.
356
357       abbrev
358           This option returns the abbreviated commit hash of the git_hash or
359           hg_hash commit.
360
361       abbrev_lenght
362           This option sets the lenght of the abbreviated commits, when using
363           the abbrev option.
364
365       tar
366           Use this options instead of tar in build scripts when you want to
367           create deterministic tar files. This options set tar arguments so
368           that owner and group of files is set to root, and mtime is set to
369           timestamp. This option takes a tar_src argument which is an array
370           containing source files or directories, and a tar_args argument
371           which is the tar arguments to create the file (something like -cf
372           filename.tar).
373
374       zip
375           Use this option instead of zip in build scripts when you want to
376           create deterministic zip files. This option takes a zip_src
377           argument which is an array containing source files or directories,
378           and a zip_args arguments which is usually the destination zip file,
379           and optionaly other zip options.
380
381       install_package
382           This option can be used in a script when you need to install a
383           package. The packages to be installed should be set in option
384           pkg_name. It will use apt-get on Debian/Ubuntu, yum on Fedora,
385           zypper on openSUSE and urpmi on Mageia/Mandriva.
386
387       In addition to the configuration options listed here, you are free to
388       add any other options that you want, and use them in the template
389       files. Unfortunately this also means that you won’t have an error
390       message in case of typo in an option name.
391

WRITTING CONFIGURATION IN PERL

393       The configuration is in YAML, but you can also use the perl syntax to
394       set some configuration options. A YAML file can contain multiple
395       documents, separated by a line with tree dashes (---). When reading a
396       configuration file, rbm will read all documents contained in the file,
397       and for each of them will :
398
399       ·   if the document is a hash, use it as configuration
400
401       ·   if the document is a string, evaluate it as perl, and get the
402           return value as as hash containing configuration
403
404       If multpiple documents define the same options, the value from the last
405       one override the values from previous documents.
406
407       A configuration file that includes perl code will look like this :
408
409           option_1: value 1
410           option_2: value 2
411           option_3: value 3
412           --- |
413            (
414                 option_4 => "value 4",
415                 option_5 => "value 5",
416            )
417
418       In this example, option_4 and option_5 and defined using perl syntax.
419       Note that the perl code block needs to be indented with at least one
420       space.
421
422       An interesting benefit of writting options in perl is that you can
423       define some options using a perl function reference. If the value of an
424       option is a function reference, then when that option is looked up the
425       function will be executed, and the value of the option will be the
426       return value of the function. The function will receive as parameters
427       the project’s name, an options array reference, and the option that is
428       queried.
429
430       An option defined using a perl function will look like this :
431
432           option_1: value 1
433           --- |
434            (
435               option_2 => "value 2",
436               option_3 => sub {
437                   my ($project, @option) = @_;
438                   return "value 3";
439               },
440            )
441

SEE ALSO

443       rbm(1), rbm_targets(7), rbm_templates(7)
444
445
446
447                                  02/02/2019                     RBM_CONFIG(7)
Impressum