rbm_templates - Man Page

All configuration options are actually templates. So you can use template directives in any of the option. There are a few exceptions however, for the options that are needed to process templates, so they can’t be templated themself. The following options are not templated :

• projects_dir

If you want to make other options not templated, add them to the notmpl config option, which is an array. All the other options are automatically processed as template.

The template 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 the name of the project. Other template files can be added in the directory projects_dir/common, to 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 following variables can be used in the 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, 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 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.

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. 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 argument in command lines. This is the function from 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.

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.

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.

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 -%]

rbm(1), rbm_config(7)

rbm(1), rbm_config(7), rbm_targets(7).