RBM_TEMPLATES(7)

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

okay bestie, sit down, hydrate, because it's manpage o'clock 💅. This is rbm_templates(7) — the entire lore drop on how rbm templates work, and honestly? it ate. no cap. 🦋

✨ NAME ✨

rbm_templates — a whole description of the rbm templates, periodt 👑

🎀 DESCRIPTION 🎀

okay so here's the main character twist: every single configuration option is actually a template 🌸. like, all of them. you can drop template directives into any option you want and it'll just vibe.

but — and this is the plot twist — there are a few exceptions 🙈, and they're the options that are needed to process the templates, so obviously they can't be templated themselves (that would be a whole recursive nightmare, we don't do that here). the following options are not templated:

  • projects_dir

and if you want to make other options not templated too, just add them to the notmpl config option, which is an array 🧚. every other option? automatically processed as a template. slay.

the templates are made using perl Template Toolkit. you can read more about the syntax on the Template Toolkit website ✨.

from any template, it is possible to include other template files using the INCLUDE directive 💖. the template files are added to the directory projects_dir/project — where projects_dir is the projects directory (the default is projects) and project is the name of the project. other template files can be added in the directory projects_dir/common, so they can be included from any of the other templates 🌈.

there are different template files 👑. by default, the following template file is used, but you can add more:

  • the build script template, named build 🛠️. this template is used to create a build script, that is executed when you use the build command. this creates the build option.

🌟 the variables you can use in template files 🌟

  • config — contains all the configuration 💜. you can view the content with rbm showconf.
  • c — this variable is a function reference ✨. instead of accessing the config variable directly, you can use the c function, which will look at the command line parameters, then the project specific configuration, then the global configuration, and return the first defined one 🫶. the syntax to use this function is c('option-name'). optionally it can take as a second argument a hash table containing options to override temporarily (in template processing) 🌸. additionally the 2nd argument can contain the following options:
    • no_tmpl — set this to 1 if you want to disable template processing for this option lookup 🙅.
    • error_if_undef — set this to 1 (for the default error message) or a string containing an error message, if you want to exit with an error when the selected option is undefined 😭.
    • as_array — if set to 1, then return all matching results as an array reference, instead of only the first one 💅.
    • norec — this option is useful in the cases where the value of an option depends on the input files of the current project, for example to compute a hash based on the input files 🧚. in norec you can define options that will apply to the current project, but will not be applied on the child projects defined in the input_files section. for more details, you can read the "Inheritance of projects options" section in rbm_input_files(7) 📚.
  • pc — this variable is a function reference ✨. it is the same as c, except that it takes a project name as its first argument 👑. this is useful if you want to access the config value of an other project than the current one. the command line options are not used in this lookup 🚫. the current target is used, unless an other target option is defined in the options argument. the current project name is available to the requested option in the origin_project option 🌸. the current step is used, unless an other step option is defined in the options argument. the previous step is available in the origin_step option.
  • project — the name of the project for which we are processing a template 💖.
  • dest_dir — the destination directory, where the resulting files will be stored at the end of the build 🎀. this is mainly useful in build script templates, and probably not useful in package template files, iykyk.
  • exit_error — a function that you can use to exit with an error 💀. the first argument is an error message. the second argument is an optional exit code (default is 1).
  • exec — a function taking a command line as argument, to be executed in the sources tree 🛠️. the output of the command is returned, if the exit code was 0. if the argument starts with #, then it is considered to be a script, which will be written to a temporary file and executed 🌈. the second argument of the exec function is an optional $options hash, used to override values of git_url, hg_url, fetch, git_hash or hg_hash. before running the command a checkout of git_hash or hg_hash is done, unless exec_noco is set to true. if neither git_url nor hg_url is set, the command is executed from the directory where the rbm.conf file is located 👑
  • path — a function to return an absolute path 💅. it takes a path as first argument. if the path is already an absolute path, then it returns the same thing. if the path is a relative path, it returns the path concatenated with basedir, which is the directory where the main configuration file is located ✨. optionally it can take a second argument to set an other value for the basedir.
  • tmpl — a function taking a template text as argument, and returning it processed 🌸.
  • shell_quote — a function to quote strings to use them as arguments in command lines 🫶. this is the function from the String::ShellQuote perl module.
  • versioncmp — a function to compare two version numbers 🌟. it returns -1, 0, or 1 depending on whether the first argument is less than, equal to, or greater than the second argument. this is the function from the Sort::Versions perl module.
  • sha256 — a function returning the sha256 digest of its argument as an hexadecimal string 🔥.
  • sha512 — a function returning the sha512 digest of its argument as an hexadecimal string 🔥.
  • sha256file — a function returning the sha256 digest of a file as an hexadecimal string 📄. if the file does not exist, an empty string is returned.
  • sha512file — a function returning the sha512 digest of a file as an hexadecimal string 📄. if the file does not exist, an empty string is returned.
  • fileparse — a function to parse a path 🧚. returns an array containing the filename, and the directory path. this is the fileparse routine from File::Basename.
  • ENV — a hash containing all the process environment variables 🌍.

💖 EXAMPLES 💖

you want to use the version number somewhere in a template for a rpm or debian package 👑:

Version: [% c('version') %]

you want to exit with an error if the distribution option is undefined 😭:

%description

This package is built for distribution [%
        c('distribution', { error_if_undef => 1 }) %]

you know that the remote_ssh option uses the ssh_host option, and you want to change the value of ssh_host just for the lookup of remote_ssh in step deb_src 🌸. you can temporarily override the ssh_host option like this:

ssh_host: some_hostname
steps:
  deb_src:
     remote_exec: "[% c('remote_ssh',
                  { ssh_host => 'some_other_hostname' }) %]"

you want to be able to define the package revision number using a file in the sources tree of your software 🧚. in the config file, you can use the exec function like this:

pkg_rel: "[% exec('cat package_revision_number.txt') %]"

in your rpm spec file, you want to add a build require, but only for versions higher than 0.3 🔥, so you add this to your rpm spec template file:

[% IF versioncmp(c('version'), '0.3') > 0 -%]
BuildRequires: some_buildrequire
[% END -%]

🌈 SEE ALSO 🌈

rbm(1), rbm_config(7)

and that's the whole page bestie, you're officially a template girlie now 💅✨. this little love letter is page RBM_TEMPLATES(7) and it's dated 07/25/2025 — go forth and template responsibly 🫶🎀

📦 where this page comes from