rbm/doc/rbm_templates.asc

rbm_templates(7)
================

NAME
----
rbm_templates - A description of the rbm templates


DESCRIPTION
-----------

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 http://www.template-toolkit.org/[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 files are used :

- the rpm spec file template, named +project.spec+ (replacing +project+
  with the project's name). This is used when you use the +rpmspec+,
  +srpm+ +rpm+, or +build+ commands. This creates the +rpmspec+ option.
  If you don't want to use this file, just replace the +rpmspec+ option
  by something else.

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

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.

project::
        The name of the project for which we are processing a template.

p::
        The project's configuration. This is a shortcut for the value
        of `config.projects.$project`.

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

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.


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
--------
link:rbm.html[rbm(1)],
link:rbm_config.html[rbm_config(7)]