1RBM_TEMPLATES(7) RBM_TEMPLATES(7)
2
6 rbm_templates - A description of the rbm templates
7
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 • projects_dir
15 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 The template are made using perl Template Toolkit. You can read more
21 about the syntax on the Template Toolkit website.
22 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 There are different template files : By default, the following template
31 file is used, but you can add more:
32 • the build script template, named build. This template is used to
34 create a build script, that is executed when you use the build
35 command. This creates the build option.
36 The following variables can be used in the template files :
38 config
40 contains all the configuration. You can view the content with rbm
41 showconf.
42 c
44 This variable is a function reference. Instead of accessing the
45 config variable directly, you can use the c function which will
46 look at the command line parameters, the project specific
47 configuration then the global configuration and return the first
48 defined one. The syntax to use this function is c('option-name').
49 Optionally it can take as a second argument a hash table containing
50 options to override temporarily (in template processing).
51 Additionally the 2nd argument can contain the following options :
52 • no_tmpl : set this to 1 if you want to disable template
54 processing for this option lookup.
55 • error_if_undef : set this to 1 (for default error message) or a
57 string containing an error message if you want to exit with an
58 error when the selected option is undefined.
59 • as_array : if set to 1, then return all matching results as an
61 array reference, instead of only the first one.
62 • norec : this option is useful in the cases where the value of
64 an option depends on the input files of the current project,
65 for example to compute a hash based on the input files. In
66 norec you can define options that will apply to the current
67 project, but will not be applied on the child projects defined
68 in the input_files section. For more details, you can read the
69 "Inheritance of projects options" section in
70 rbm_input_files(7).
71 pc
73 This variable is a function reference. It is the same as c, except
74 that it takes a project name as its first argument. This is useful
75 if you want to access the config value of an other project than the
76 current one. The command line options are not used in this lookup.
77 The current target is used, unless an other target option is
78 defined in the options argument. The current project name is
79 available to the requested option in the origin_project option. The
80 current step is used, unless an other step option is defined in the
81 options argument. The previous step is available in the origin_step
82 option.
83 project
85 The name of the project for which we are processing a template.
86 dest_dir
88 The destination directory, where the resulting files will be stored
89 at the end of the build. This is mainly useful in build script
90 templates, and probably not useful in package template files.
91 exit_error
93 A function that you can use to exit with an error. The first
94 argument is an error message. The second argument is an optional
95 exit code (default is 1).
96 exec
98 A function taking a command line as argument, to be executed in the
99 sources tree. The output of the command is returned, if the exit
100 code was 0. If the argument starts with #, then it is considered to
101 be a script, which will be written to a temporary file and
102 executed. The second argument of the exec function is an optional
103 $options hash, used to override values of git_url, hg_url, fetch,
104 git_hash or hg_hash.
105 path
107 A function to return an absolute path. It takes a path as first
108 argument. If the path is already an absolute path, then it returns
109 the same thing. If the path is a relative path, it returns the path
110 concatenated with basedir which is the directory where the main
111 configuration file is located. Optionally it can take a second
112 argument to set an other value for the basedir.
113 tmpl
115 A function taking a template text as argument, and returning it
116 processed.
117 shell_quote
119 A function to quote strings to use them as argument in command
120 lines. This is the function from String::ShellQuote perl module.
121 versioncmp
123 A function to compare two version numbers. It returns -1, 0, or 1
124 depending on whether the first argument is less than, equal to, or
125 greater than the second argument. This is the function from the
126 Sort::Versions perl module.
127 sha256
129 A function returning the sha256 digest of its argument as an
130 hexadecimal string.
131 sha256file
133 A function returning the sha256 digest of a file as an hexadecimal
134 string. If the file does not exist, an empty string is returned.
135 fileparse
137 A function to parse a path. Returns an array containing the
138 filename, and the directory path. This is the fileparse routine
139 from File::Basename.
140 ENV
142 A hash containing all the process environment variables.
143
145 You want to use the version number somewhere in a template for a rpm or
146 debian package :
147 Version: [% c('version') %]
149 You want to exit with an error if the distribution option is undefined
151 :
152 %description
154 This package is built for distribution [%
156 c('distribution', { error_if_undef => 1 }) %]
157 You know that the remote_ssh option uses the ssh_host option, and you
159 want to change the value of ssh_host just for the lookup of remote_ssh
160 in step deb_src. You can temporarily override the ssh_host option like
161 this :
162 ssh_host: some_hostname
164 steps:
165 deb_src:
166 remote_exec: "[% c('remote_ssh',
167 { ssh_host => 'some_other_hostname' }) %]"
168 You want to be able to define the package revision number using a file
170 in the sources tree of your software. In the config file, you can use
171 the exec function like this :
172 pkg_rel: "[% exec('cat package_revision_number.txt') %]"
174 In your rpm spec file, you want to add a build require, but only for
176 versions higher than 0.3, so you add this to your rpm spec template
177 file :
178 [% IF versioncmp(c('version'), '0.3') > 0 -%]
180 BuildRequires: some_buildrequire
181 [% END -%]
182
184 rbm(1), rbm_config(7)
185 01/20/2023 RBM_TEMPLATES(7)