rbm_config man page

rbm_config — The rbm configuration

Description

All configuration options can be defined in 3 different places :

· in the main configuration in your working directory

· in the global system configuration

· in a project configuration

· with a command line option

The option values are used with the following priority order :

· command line options

· project config for matching step and target

· project config for matching step

· project config for matching target

· project config

· workspace config for matching step and target

· workspace config for matching step

· workspace config for matching target

· workspace config

· system config for matching step and target

· system config for matching step

· system config for matching target

· system config

· default config

· undefined

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.

An example rbm.conf file will look like this :

projects_dir: projects
compress_tar: xz

The projects_dir option define the path to the directory containing the projects definitions.

Adding a new project is done by creating a directory with the name of the project inside the projects_dir 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.

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.

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_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.

output_dir

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

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.

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.

compress_tar

If set, the tarball created will be compressed in the select format. Possible values: xz, gz, bz2.

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 gpg_keyring_dir directory. This can also be an absolute path.

gpg_keyring_dir

The directory containing gpg keyring files. The default is $basedir/keyring (with $basedir the directory where the main config file is located).

gpg_bin

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

gpg_args

Optional gpg arguments. The default is empty.

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.

version_command

A command to run in the checked out source tree to determine the version, if the version option is not set. The command should print the version on stdout.

pkg_rel

Package release 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, and the filename and the sha256sum of the file for any other type of input file.

timestamp

This is the UNIX timestamp, set as modification time on files created such as the sources tarball and rpm spec file. 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 (deb if building a Debian package, rpm if building an rpm, etc ...). This can be useful in the input_files definition, if you want to enable an input file only for some type of package. This option should be used read only.

steps

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

rpm_rel

RPM package release number. The default is to use the option pkg_rel if defined, otherwise use a release number containing the number of commits since the last git tag, and the hash of the commit used.

rpmspec

This is the content of the rpm spec file, used by the rpm and srpm commands. The default is to include the template file named project.spec (with project replaced by the project’s name).

rpmbuild

This is the content of the script to build a rpm or srpm. It is using the rpmbuild_action option to select the build action (-bs to build a source package, or -ba to build all packages).

rpm

This is the script that is used to build an rpm package, in the rpm command. By default it is using the rpmbuild option with the -ba action.

srpm

This is the script that is used to build a source rpm package, in the srpm command. By default it is using the rpmbuild option with the -bs action.

debian_revision

The package revision used in debian packages. By default, when the option pkg_rel is defined, this is what is used. Otherwise a revision containing the number of commits since the last git tag, and the hash of the commit is used.

deb_src

This is the script that is used to create the debian source package. By default it will use the debian files listed in the option debian_files and create the source package with dpkg-source.

deb

This is the script that is used to create the debian packages. By default it will use the debian files listed in the option debian_files and build the package using debuild or pdebuild depending on whether the use_pbuilder option is set. The packages will be signed using the key defined in the option debsign_keyid.

debian_files

This is an array containing the files to create in the debian directory. Each item in the array is an hash, with the following two keys : name is the file name in the debian directory of the file to create, and content is the content of the file. The filename and content are processed as template, so for instance if you want to store the content of a file in a separate file, you can use the INCLUDE directive.

use_pbuilder

If set to a true value, pbuilder will be used to build the debian packages.

debsign_keyid

This is the gpg key that will be used to sign the debian packages. Set to 0 if you don’t want to sign the packages.

pkg_type

This is the name of the option that will be used by the pkg command as the script to build the package. This can be rpm or deb for rpm and debian packages. This option is usually set in distribution specific configuration as it depends on the distribution being used.

build

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

publish

This is the content of the script that is used to upload the packages or files to a repository. This script will be executed from the directory containing the files to publish. This option has no default value.

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_lenght

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

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).

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 optionaly other zip options.

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.

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 the document is a hash, use it as configuration

· if the document is a string, evaluate it as perl, and get the return value as as hash containing configuration

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)

Referenced By

rbm(1), rbm_cli(7), rbm-deb(1), rbm-deb-src(1), rbm_input_files(7), rbm-pkg(1), rbm-publish(1), rbm_remote(7), rbm-rpm(1), rbm-showconf(1), rbm-srpm(1), rbm_steps(7), rbm-tar(1), rbm_targets(7), rbm_templates(7).

11/04/2016