1RBM_CONFIG(7) RBM_CONFIG(7)
2
6 rbm_config - The rbm configuration
7
9 All configuration options can be defined in 3 different places :
10 · in the main configuration in your working directory
12 · in the global system configuration
14 · in a project configuration
16 · with a command line option
18 The option values are used with the following priority order :
20 · command line options
22 · project config for matching step and target
24 · project config for matching step
26 · project config for matching target
28 · project config
30 · workspace config for matching step and target
32 · workspace config for matching step
34 · workspace config for matching target
36 · workspace config
38 · system config for matching step and target
40 · system config for matching step
42 · system config for matching target
44 · system config
46 · default config
48 · undefined
50 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 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 An example rbm.conf file will look like this :
64 projects_dir: projects
66 compress_tar: xz
67 The projects_dir option define the path to the directory containing the
69 projects definitions.
70 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
79 The following configuration options are available :
80 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 projects_dir
87 The directory containing the projects definitions. The default
88 value is projects.
89 git_clone_dir
91 The directory used to store clones of git repositories. The default
92 value is git_clones.
93 hg_clone_dir
95 The directory used to store clones of mercurial repositories. The
96 default value is hg_clones.
97 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 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 output_dir
111 The directory where output files (tarballs, spec files or packages)
112 are created. The default value is out.
113 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 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 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 git_hash
132 A git hash, branch name or tag. This is what is used to create the
133 tarball.
134 hg_hash
136 A mercurial changeset hash. This is what is used to create the
137 tarball.
138 compress_tar
140 If set, the tarball created will be compressed in the select
141 format. Possible values: xz, gz, bz2.
142 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 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 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 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 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 gpg_bin
183 The gpg command to be used. The default is gpg.
184 gpg_args
186 Optional gpg arguments. The default is empty.
187 arch
189 The architecture, as returned by uname -m.
190 version
192 Version number of the software. This is used to create the tarball,
193 and as the package version number.
194 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 pkg_rel
201 Package release number.
202 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 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 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 targets
221 The targets definitions. See rbm_targets(7) for details.
222 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 input_files
228 Configuration for external input files. See rbm_input_files(7) for
229 details.
230 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 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 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 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 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 steps
264 The steps definitions. See rbm_steps(7) for details.
265 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 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 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 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 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 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 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 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 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 use_pbuilder
320 If set to a true value, pbuilder will be used to build the debian
321 packages.
322 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 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 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 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 remote_exec
345 Run the build on a remote host. See rbm_remote(7) for details.
346 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 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 abbrev
358 This option returns the abbreviated commit hash of the git_hash or
359 hg_hash commit.
360 abbrev_lenght
362 This option sets the lenght of the abbreviated commits, when using
363 the abbrev option.
364 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 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 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 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
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 · if the document is a hash, use it as configuration
400 · if the document is a string, evaluate it as perl, and get the
402 return value as as hash containing configuration
403 If multpiple documents define the same options, the value from the last
405 one override the values from previous documents.
406 A configuration file that includes perl code will look like this :
408 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 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 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 An option defined using a perl function will look like this :
431 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
443 rbm(1), rbm_targets(7), rbm_templates(7)
444 07/26/2019 RBM_CONFIG(7)