rbm_config - Man Page

The rbm configuration

Description

All configuration options can be defined in different places :

The option values are used with the following priority order :

The system configuration is by default located at /etc/rbm.conf, or the path defined in the sysconf_file option. If the path does not exists, it is ignored. This is where you will put configuration only relevant to your local use of rbm.

The main configuration file is rbm.conf, in YAML format. It can be located anywhere on your filesystem, but you will need to run the rbm commands from the same directory, or one of its subdirectories. This is where you will put configuration relevant to all projects under this working directory. All relative paths used in the configuration are relative from the rbm.conf location.

The local configuration file is rbm.local.conf (or the file defined by the localconf_file option), in the same directory as the rbm.conf file. If the file does not exists, it is ignored. The rbm.local.conf file is used to override some options from rbm.conf relevent to your local setup, whithout modifying the rbm.conf file which is usually maintained in a VCS.

The module configuration files are rbm.module.conf located at the root of each module directory: a module named A will have its configuration in modules/A/rbm.module.conf. Module configuration is used in alphabetical order: configuration from a module named A will have priority over a module named B.

An example rbm.conf file will look like this :

compress_tar: xz
output_dir: "out/[% project %]"

Adding a new project is done by creating a directory with the name of the project inside the projects directory, and adding a config file in this new directory. The config file contains the configuration for the project. At the minimum it should contain the git_url configuration, and any other configuration option you want to set for this project.

Projects can also be defined inside a module. In this case the module directory will include a projects directory working in a similar way to the main projects directory. If a project exists with the same name both in a module and the main projects directory, the module one will be ignored. If a project is defined in multiple modules, only the project from the first module in alphabetic order will be used.

Options

The following configuration options are available :

sysconf_file

The path to an optional system configuration file. The default is /etc/rbm.conf. This can also be set with the --sysconf-file command line parameter.

localconf_file

The path to an optional local configuration file. The default is rbm.local.conf. If the path is relative, it is relative to the directory where the rbm.conf file is located. This can also be set with the --localconf-file command line parameter.

projects_dir

The directory containing the projects definitions. The default value is projects.

git_clone_dir

The directory used to store clones of git repositories. The default value is git_clones.

hg_clone_dir

The directory used to store clones of mercurial repositories. The default value is hg_clones.

hg_clone_subdir

If this option is set, the repository is cloned in a subdirectory with that name. This is useful if a single project requires clones of multiple mercurial repositories, for example using a different hg_url in each targets or steps. The default value is ., which means that no subdirectory is used.

hg_opt

This option contains options that should be passed on the mercurial command line. This can for instance be useful if you want to use the --config option to enable some mercurial plugins.

tmp_dir

The directory used to create temporary directories and files. This is the directory where builds will be done, so you want to use a directory on a fast device, with enough space available. This directory will contains some scripts that will be executed, so it should not be on a partition mounted as noexec.

rbm_tmp_dir

A directory created inside tmp_dir using File::Temp, that you can use to store temporary files. This directory is removed automatically when rbm exits. When running scripts, the TMPDIR environment variable is also set to this directory.

rbmdir

The directory where the rbm script is located.

output_dir

The directory where output files (tarballs, spec files or packages) are created. The default value is out.

build_log

The file where the build logs will be written. If the value is - (the default), the logs will be output on stdout and stderr.

build_log_append

If you set to build_log_append to 0, the log file (defined in build_log) will be cleaned when starting a new build. The default is 1.

fetch

The value should be 0 or 1, depending on whether the commits from the remote git or hg repository should be fetched automatically. If the value is if_needed, the git or hg repository is fetched only if the selected commit cannot be found in the local clone. The default is if_needed.

ENV

This option, defined in the workspace config, is a hash containing the environment variables that will be defined when rbm is starting. This is useful for defining variables that can affect how the templates are processed (for instance the TZ variable if dates are used). If this option is not defined TZ will be set to UTC and LC_ALL to C.

git_url

The URL of a git repository that will be cloned and used to create the tarball. If this option is set, git_hash should be set to select the commit to use.

hg_url

The URL of a mercurial repository that will be cloned and used to create the tarball. If this option is set, hg_hash should be set to select the commit to use.

git_hash

A git hash, branch name or tag. This is what is used to create the tarball.

hg_hash

A mercurial changeset hash. This is what is used to create the tarball.

git_submodule

If this option is enabled, git submodules are fetched and included in the tarball. This option is disabled by default.

git_depth

An integer specifying a depth for shallow Git clone/fetch depth, to decrease network and storage usage. If not set, shallow clone/fetch is disabled.

git_branch

A Git ref name that will be exclusively cloned/fetched, to decrease network and storage usage. Must be a descendent (inclusive) of git_hash. If not set, all Git refs are cloned/fetched.

compress_tar

If set, the tarball created will be compressed in the select format. Possible values: xz, gz, bz2, zst. The default is gz but it can stay empty to disable compression.

commit_gpg_id

If set, the commit selected with git_hash will have its signature checked. The tarball will not be created if there is no valid signature, and if the key used to sign it does not match the key ID from commit_gpg_id. The option can be set to a single gpg ID, or to a list of gpg IDs. The IDs can be short or long IDs, or full fingerprint (with no spaces). For this to work, the GPG keys should be present in the selected keyring (see keyring option). If the option is set to 1 or an array containing 1 then any key from the selected keyring is accepted. On command line, the --commit-gpg-id option can be listed multiple times to define a list of keys.

tag_gpg_id

If set, the commit selected with git_hash should be a tag and will have its signature checked. The tarball will not be created if the tag doesn’t have a valid signature, and if the key used to sign it does not match the key ID from tag_gpg_id. The option can be set to a single gpg ID, or to a list of gpg IDs. The IDs can be short or long IDs, or full fingerprint (with no spaces). For this to work, the GPG keys should be present in the selected keyring (see keyring option). If the option is set to 1 or an array containing 1 then any key from the selected keyring is accepted. On command line, the --tag-gpg-id option can be listed multiple times to define a list of keys.

gpg_wrapper

This is a template for a gpg wrapper script. The default wrapper will call gpg with the keyring specified by option gpg_keyring if defined.

gpg_keyring

The filename of the gpg keyring to use. Path is relative to the keyring directory. This can also be an absolute path.

gpg_bin

The gpg command to be used. The default is gpg.

gpg_args

Optional gpg arguments. The default is empty.

gpg_allow_expired_keys

Allowing expired keys to successfully verify e.g. signed git tags. By default this is not allowed.

arch

The architecture, as returned by uname -m.

version

Version number of the software. This is used to create the tarball, and as the package version number.

distribution

The name of the distribution for which you wish to build a package. The syntax is distribution-release. This value is used by the lsb_release option.

lsb_release

A hash containing id (name of the distribution), codename and release. This option is useful in template to do different things for different distributions. By default, the output of the lsb_release command will be used if available. If the distribution option is defined, it will be used instead to for the id and release (codename will be undefined).

target

The target for which you want to build. This is usually set on command line. See rbm_targets(7) for details.

targets

The targets definitions. See rbm_targets(7) for details.

copy_files

A list of files that should be copied when building the package. Path is relative to the project’s template directory.

input_files

Configuration for external input files. See rbm_input_files(7) for details.

input_files_by_name

This option contains an hash of all the input_files filenames, with their name as index. The input files without a name are not in this hash.

input_files_id

The value of this option is an identifier of the input_files. When any of the input files is changed, the identifier changes. This identifier is something that can be used in a project’s filename to trigger a rebuild when any of its input files is changed. This identifier is based on: the input_file_id option of an input file if it is present, the filename for an input file of type project, the value of exec for an input file of type exec, and the filename and the sha256sum of the file for any other type of input file. In the case of an input file of type exec, the value of exec is computed with getting_id set to true.

input_files_paths

The value of this option is an array of all the paths of input files that currently exist and are used in the build of the current project and its dependencies. This is useful when cleaning old build files, to find which ones are still used.

link_input_files

When building a project, input files are collected in a temporary directory. If this option is set to 1, we try to use hard links instead of copies. You should only enable this if you don’t modify the input files during the build, or if you are using remote_exec (in which case the temporary directory is only used to copy files to the remote). This option is disabled by default, unless remote_exec is used.

timestamp

This is the UNIX timestamp, set as modification time on files created such as the sources tarball. The default is to use the commit time of the commit used. If set to 0 it will use the current time.

notmpl

An array containing a list of options that should not be processed as template (see the template section below for details).

step

The value of this option is the name of the build script we are going to be running (by default build, but you could have an other one for publishing your build, or for different types of packaging). This option should be used read only. If you want to change it, use the --step command line option, or the pkg_type option.

steps

The steps definitions. See rbm_steps(7) for details.

build

This is the content of the build script used by the build command. The default is to include the template file named build.

remote_exec

Run the build on a remote host. See rbm_remote(7) for details.

suexec

This options takes the suexec_cmd options, and make it run as root. By default, it uses sudo for that. You need to set this option if you want to use an other mechanism to run commands as root.

debug

This option enable or disable the debug mode. When enabled, a shell will be opened in the temporary build directory in case of build failure.

abbrev

This option returns the abbreviated commit hash of the git_hash or hg_hash commit.

abbrev_length

This option sets the length of the abbreviated commits, when using the abbrev option.

isatty

This option is true when stdout is connected to a tty.

tar

Use this options instead of tar in build scripts when you want to create deterministic tar files. This options set tar arguments so that owner and group of files is set to root, and mtime is set to timestamp. This option takes a tar_src argument which is an array containing source files or directories, and a tar_args argument which is the tar arguments to create the file (something like -cf filename.tar). By default, GNU options are used in tar and find, but you can disable that with gnu_utils.

zip

Use this option instead of zip in build scripts when you want to create deterministic zip files. This option takes a zip_src argument which is an array containing source files or directories, and a zip_args arguments which is usually the destination zip file, and optionally other zip options. By default, GNU options are used in find, but you can disable that with gnu_utils. The zip command will be used to create the zip file, unless use_7z is set, in which case 7z will be used instead. In this case, 7z_bin can be used to select the 7z command (for cases where the command is 7zz instead of 7z) and 7z_opts can be used to set additional options to the 7z command.

install_package

This option can be used in a script when you need to install a package. The packages to be installed should be set in option pkg_name. It will use apt-get on Debian/Ubuntu, yum on Fedora, zypper on openSUSE and urpmi on Mageia/Mandriva.

num_procs

This option allows to specify the number of CPUs used to parallelize the build. By default it is set to whatever value nrpoc is returning on the build machine.

touch

This option can be used to set the mtime of files to timestamp. It expects the file to touch as as argument following on the same line.

In addition to the configuration options listed here, you are free to add any other options that you want, and use them in the template files. Unfortunately this also means that you won’t have an error message in case of typo in an option name.

Writting Configuration in Perl

The configuration is in YAML, but you can also use the perl syntax to set some configuration options. A YAML file can contain multiple documents, separated by a line with tree dashes (---). When reading a configuration file, rbm will read all documents contained in the file, and for each of them will :

If multpiple documents define the same options, the value from the last one override the values from previous documents.

A configuration file that includes perl code will look like this :

option_1: value 1
option_2: value 2
option_3: value 3
--- |
 (
      option_4 => "value 4",
      option_5 => "value 5",
 )

In this example, option_4 and option_5 and defined using perl syntax. Note that the perl code block needs to be indented with at least one space.

An interesting benefit of writting options in perl is that you can define some options using a perl function reference. If the value of an option is a function reference, then when that option is looked up the function will be executed, and the value of the option will be the return value of the function. The function will receive as parameters the project’s name, an options array reference, and the option that is queried.

An option defined using a perl function will look like this :

option_1: value 1
--- |
 (
    option_2 => "value 2",
    option_3 => sub {
        my ($project, @option) = @_;
        return "value 3";
    },
 )

See Also

rbm(1), rbm_targets(7), rbm_templates(7), rbm_modules(7)

Referenced By

rbm(1), rbm-build(1), rbm_cli(7), rbm_input_files(7), rbm_layout(7), rbm_remote(7), rbm-showconf(1), rbm_steps(7), rbm-tar(1), rbm_targets(7), rbm_templates(7).

07/19/2024