RBM_CONFIG(7)

📦
version 0.4^20241205gitc6a4095 · 2 versions
, in fedora 43

✨ rbm_config — the manual page for RBM_CONFIG(7) ✨

okay bestie, sit down, grab a boba, because we're about to learn the entire configuration system of rbm and honestly? it's giving organized. 💅

🌸 NAME 🌸

rbm_config — the rbm configuration, aka the whole vibe of how rbm knows what you want 🎀

💖 DESCRIPTION 💖

So, like, all configuration options can be defined in different places — it's not just one file, it's a whole ecosystem, and honestly the way it layers? iconic.

  • in the main configuration in your working directory (rbm.conf)
  • in a module configuration at the root of a module directory (rbm.module.conf)
  • in the local configuration in your working directory (rbm.local.conf)
  • in the global system configuration (/etc/rbm.conf)
  • in a project configuration
  • with a command line option

🦋 priority order 🦋

when the same option is defined in more than one place, rbm does a little vibe check and picks the winner in this exact order — top of the list is main character energy, bottom is, uh, nobody:

  1. command line options
  2. project config for matching step and target
  3. project config for matching step
  4. project config for matching target
  5. project config
  6. local config for matching step and target
  7. local config for matching step
  8. local config for matching target
  9. local config
  10. workspace config for matching step and target
  11. workspace config for matching step
  12. workspace config for matching target
  13. workspace config
  14. modules config for matching step and target
  15. modules config for matching step
  16. modules config for matching target
  17. modules config
  18. system config for matching step and target
  19. system config for matching step
  20. system config for matching target
  21. system config
  22. default config
  23. undefined

like, undefined is literally last place. it's the "left on read" of config values. 💀

🧚 the system config 🧚

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 exist, it is ignored (no drama, it just moves on). This is where you will put configuration only relevant to your local use of rbm. 🫶

🌈 the main config 🌈

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. no cap, that part matters.

🎀 the local config 🎀

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 exist, it is ignored. The rbm.local.conf file is used to override some options from rbm.conf relevant to your local setup, without modifying the rbm.conf file which is usually maintained in a VCS. it's the "do not touch the sacred file, put your stuff here instead" file. periodt. 💖

🍓 the module configs 🍓

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. so like, alphabet supremacy but make it config. ✨

💜 an example, bestie 💜

An example rbm.conf file will look like this:

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

🌟 adding projects 🌟

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. first alphabetically wins, everyone else can go home. 💅

✨ OPTIONS ✨

The following configuration options are available — and yes, we're doing all of them, no skipping, we're not cowards:

  • 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. 🚨
for real for real: not on a noexec partition. scripts gotta run.
  • 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. it cleans up after itself, we love a self-aware queen. 👑
  • 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 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. lazy fetch = bestie fetch 🦋
  • 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. ⚠️ expired keys stay expired unless you say otherwise.
  • 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.

and that's part 1, bestie — there's more coming, so don't go anywhere 💜

  • lsb_release — a whole lil hash holding id (the name of your distribution), codename, and release. It's giving "let me branch my template per-distro" 💅. By default we just use the output of the lsb_release command if it's available. But if the distribution option is set, that one wins instead and gets used for id and release — heads up tho, codename will be undefined in that case. 🙈
  • target — the target you wanna build. Usually you just set this on the command line. See rbm_targets(7) for the details. 🎯
  • targets — the actual targets definitions. See rbm_targets(7). ✨
  • copy_files — a list of files that should be copied when the package gets built. The path is relative to the project's template directory. 📁
  • input_files — configuration for external input files. See rbm_input_files(7) for the whole situation.
  • input_files_by_name — this one holds a hash of all the input_files filenames, indexed by their name. Input files that have no name are not in this hash, periodt.
  • input_files_id — the value here is an identifier of the input_files. Whenever any of the input files changes, this identifier changes too 🦋. It's the thing you can drop into a project's filename to trigger a rebuild when any of its input files changes. It's built from: the input_file_id option of an input file if that's present, the filename for an input file of type project, the value of exec for an input file of type exec, and the filename plus the sha256sum of the file for any other type of input file. And for an input file of type exec, the value of exec gets computed with getting_id set to true. iykyk 💫
  • input_files_paths — 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. Super useful when you're cleaning out old build files and need to know which ones are still in use. 🧹
  • link_input_files — when a project builds, the input files get collected in a temporary directory. If you set this to 1, we try to use hard links instead of copies. ⚠️ Only turn this on if you're not modifying the input files during the build, or if you're using remote_exec (in which case that temporary directory is only used to copy files over to the remote anyway). It's disabled by default, unless remote_exec is in play.
  • timestamp — the UNIX timestamp that gets set as the modification time on files we create, like the sources tarball. Default is the commit time of the commit being used. If you set it to 0, it uses the current time instead. ⏰
  • notmpl — an array listing options that should not be processed as template (peep the template section below for the tea).
  • step — the name of the build script we're about to run (default is build, but you could have another one for publishing your build, or for different types of packaging). Read only, bestie — do not touch. 🛑 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). 👑
  • 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 one takes the suexec_cmd options and makes it run as root. By default it uses sudo for that. You only need to set this option if you want some other mechanism to run commands as root. 💅
  • debug — enables or disables debug mode. When it's on, a shell gets opened in the temporary build directory if the build fails. 😭 Very "come look at what went wrong with me" energy.
  • abbrev — returns the abbreviated commit hash of the git_hash or hg_hash commit.
  • abbrev_length — sets the length of those abbreviated commits, when you're using the abbrev option. 📏
  • isatty — true when stdout is connected to a tty. cute lil vibe check.
  • tar — use this instead of tar in build scripts when you want deterministic tar files. It sets the tar arguments so that owner and group of files are set to root, and mtime is set to timestamp. It takes a tar_src argument, which is an array of source files or directories, and a tar_args argument, which is the tar arguments used to create the file (something like -cf filename.tar). By default GNU options are used in tar and find, but you can turn that off with gnu_utils. 🎀
  • zip — use this instead of zip in build scripts when you want deterministic zip files. It takes a zip_src argument (an array of source files or directories) and a zip_args argument (usually the destination zip file, optionally plus other zip options). By default GNU options are used in find, but again, gnu_utils turns that off. The zip command creates the zip file — unless use_7z is set, in which case 7z takes over instead. In that case, 7z_bin lets you pick the 7z command (for when it's 7zz instead of 7z) and 7z_opts lets you set extra options for the 7z command. 🗜️✨
  • install_package — use this in a script when you need to install a package. The packages to install go in the pkg_name option. It uses apt-get on Debian/Ubuntu, yum on Fedora, zypper on openSUSE, and urpmi on Mageia/Mandriva. it knows every distro fr fr 🫶
  • num_procs — lets you specify how many CPUs get used to parallelize the build. By default it's whatever value nrpoc returns on the build machine. 🖥️
  • touch — use this to set the mtime of files to timestamp. It expects the file to touch as an argument following on the same line.

And here's the fun part: on top of all the config options listed here, you are totally free to add any other options you want and use them in the template files. 🦋 The trade-off? You also won't get an error message if you typo an option name. 💀 So like... spell carefully, bestie.

✨ WRITTING CONFIGURATION IN PERL ✨

So the configuration is YAML, but plot twist — you can also use perl syntax to set some of those config options. 😌 A YAML file can hold multiple documents, separated by a line with three dashes (---). When rbm reads a config file, it reads all the documents in that file, and for each one it will:

  • if the document is a hash, use it as configuration
  • if the document is a string, evaluate it as perl, and take the return value as a hash containing configuration

If multiple documents define the same options, the value from the last one overrides the values from the previous documents. last one wins, no cap 👑

A configuration file that includes perl code looks 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 are defined using perl syntax. And note — the perl code block needs to be indented with at least one space. 🙈

An interesting little benefit of writing options in perl is that you can define options using a perl function reference. If the value of an option is a function reference, then when that option gets looked up, the function will be executed, and the value of the option becomes the return value of that function. The function receives as parameters the project's name, an options array reference, and the option that is queried. 🧚

An option defined with a perl function looks 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)

That's the whole page, bestie!! 🎀 This was RBM_CONFIG(7) and the version/date stamp on it was 07/25/2025 — go build something iconic with it. 💖✨

📦 where this page comes from