1RBM_TEMPLATES(7)                                              RBM_TEMPLATES(7)
2
3
4

NAME

6       rbm_templates - A description of the rbm templates
7

DESCRIPTION

9       All configuration options are actually templates. So you can use
10       template directives in any of the option. There are a few exceptions
11       however, for the options that are needed to process templates, so they
12       can’t be templated themself. The following options are not templated :
13
14       •   projects_dir
15
16       If you want to make other options not templated, add them to the notmpl
17       config option, which is an array. All the other options are
18       automatically processed as template.
19
20       The template are made using perl Template Toolkit. You can read more
21       about the syntax on the Template Toolkit website.
22
23       From any template, it is possible to include other template files using
24       the INCLUDE directive. The template files are added to the directory
25       projects_dir/project where projects_dir is the projects directory (the
26       default is projects) and project the name of the project. Other
27       template files can be added in the directory projects_dir/common, to be
28       included from any of the other templates.
29
30       There are different template files : By default, the following template
31       files are used :
32
33       •   the rpm spec file template, named project.spec (replacing project
34           with the project’s name). This is used when you use the rpmspec,
35           srpm rpm, or build commands. This creates the rpmspec option. If
36           you don’t want to use this file, just replace the rpmspec option by
37           something else.
38
39       •   the build script template, named build. This template is used to
40           create a build script, that is executed when you use the build
41           command. This creates the build option.
42
43       The following variables can be used in the template files :
44
45       config
46           contains all the configuration. You can view the content with rbm
47           showconf.
48
49       c
50           This variable is a function reference. Instead of accessing the
51           config variable directly, you can use the c function which will
52           look at the command line parameters, the project specific
53           configuration then the global configuration and return the first
54           defined one. The syntax to use this function is c('option-name').
55           Optionally it can take as a second argument a hash table containing
56           options to override temporarily (in template processing).
57           Additionally the 2nd argument can contain the following options :
58
59no_tmpl : set this to 1 if you want to disable template
60               processing for this option lookup.
61
62error_if_undef : set this to 1 (for default error message) or a
63               string containing an error message if you want to exit with an
64               error when the selected option is undefined.
65
66as_array : if set to 1, then return all matching results as an
67               array reference, instead of only the first one.
68
69       pc
70           This variable is a function reference. It is the same as c, except
71           that it takes a project name as its first argument. This is useful
72           if you want to access the config value of an other project than the
73           current one. The command line options are not used in this lookup.
74           The current target is used, unless an other target option is
75           defined in the options argument. The current project name is
76           available to the requested option in the origin_project option.
77
78       project
79           The name of the project for which we are processing a template.
80
81       p
82           The project’s configuration. This is a shortcut for the value of
83           config.projects.$project.
84
85       dest_dir
86           The destination directory, where the resulting files will be stored
87           at the end of the build. This is mainly useful in build script
88           templates, and probably not useful in package template files.
89
90       exit_error
91           A function that you can use to exit with an error. The first
92           argument is an error message. The second argument is an optional
93           exit code (default is 1).
94
95       exec
96           A function taking a command line as argument, to be executed in the
97           sources tree. The output of the command is returned, if the exit
98           code was 0. If the argument starts with #, then it is considered to
99           be a script, which will be written to a temporary file and
100           executed. The second argument of the exec function is an optional
101           $options hash, used to override values of git_url, hg_url, fetch,
102           git_hash or hg_hash.
103
104       path
105           A function to return an absolute path. It takes a path as first
106           argument. If the path is already an absolute path, then it returns
107           the same thing. If the path is a relative path, it returns the path
108           concatenated with basedir which is the directory where the main
109           configuration file is located. Optionally it can take a second
110           argument to set an other value for the basedir.
111
112       tmpl
113           A function taking a template text as argument, and returning it
114           processed.
115
116       shell_quote
117           A function to quote strings to use them as argument in command
118           lines. This is the function from String::ShellQuote perl module.
119
120       versioncmp
121           A function to compare two version numbers. It returns -1, 0, or 1
122           depending on whether the first argument is less than, equal to, or
123           greater than the second argument. This is the function from the
124           Sort::Versions perl module.
125
126       sha256
127           A function returning the sha256 digest of its argument as an
128           hexadecimal string.
129
130       sha256file
131           A function returning the sha256 digest of a file as an hexadecimal
132           string. If the file does not exist, an empty string is returned.
133
134       fileparse
135           A function to parse a path. Returns an array containing the
136           filename, and the directory path. This is the fileparse routine
137           from File::Basename.
138
139       ENV
140           A hash containing all the process environment variables.
141

EXAMPLES

143       You want to use the version number somewhere in a template for a rpm or
144       debian package :
145
146           Version: [% c('version') %]
147
148       You want to exit with an error if the distribution option is undefined
149       :
150
151           %description
152
153           This package is built for distribution [%
154                   c('distribution', { error_if_undef => 1 }) %]
155
156       You know that the remote_ssh option uses the ssh_host option, and you
157       want to change the value of ssh_host just for the lookup of remote_ssh
158       in step deb_src. You can temporarily override the ssh_host option like
159       this :
160
161           ssh_host: some_hostname
162           steps:
163             deb_src:
164                remote_exec: "[% c('remote_ssh',
165                           { ssh_host => 'some_other_hostname' }) %]"
166
167       You want to be able to define the package revision number using a file
168       in the sources tree of your software. In the config file, you can use
169       the exec function like this :
170
171           pkg_rel: "[% exec('cat package_revision_number.txt') %]"
172
173       In your rpm spec file, you want to add a build require, but only for
174       versions higher than 0.3, so you add this to your rpm spec template
175       file :
176
177           [% IF versioncmp(c('version'), '0.3') > 0 -%]
178           BuildRequires: some_buildrequire
179           [% END -%]
180

SEE ALSO

182       rbm(1), rbm_config(7)
183
184
185
186                                  01/27/2021                  RBM_TEMPLATES(7)
Impressum