rpm  5.4.10
macros
Go to the documentation of this file.
1 /*! \page macros Macro syntax
2 
3 RPM has fully recursive spec file macros. Simple macros do straight text
4 substitution. Parameterized macros include an options field, and perform
5 argc/argv processing on white space separated tokens to the next newline.
6 During macro expansion, both flags and arguments are available as macros
7 which are deleted at the end of macro expansion. Macros can be used
8 (almost) anywhere in a spec file, and, in particular, in "included file
9 lists" (i.e. those read in using %files -f FILE). In addition, macros
10 can be nested, hiding the previous definition for the duration of the
11 expansion of the macro which contains nested macros.
12 
13 \subsection macros_defining Defining a Macro
14 
15 To define a macro use:
16 
17 \verbatim
18  %define NAME[(OPTS)] BODY
19 \endverbatim
20 
21 All whitespace surrounding BODY is removed. Name may be composed
22 of alphanumeric characters, and the character `_' and must be at least
23 3 characters in length. A macro without an (opts) field is "simple" in that
24 only recursive macro expansion is performed. A parameterized macro contains
25 an (opts) field. The opts (i.e. string between parentheses) is passed
26 exactly as is to getopt(3) for argc/argv processing at the beginning of
27 a macro invocation. While a parameterized macro is being expanded, the
28 following shell-like macros are available:
29 
30 \verbatim
31  %0 the name of the macro being invoked
32  %* all arguments (unlike shell, not including any processed flags)
33  %# the number of arguments
34  %{-f} if present at invocation, the flag f itself
35  %{-f*} if present at invocation, the argument to flag f
36  %1, %2 the arguments themselves (after getopt(3) processing)
37 \endverbatim
38 
39 At the end of invocation of a parameterized macro, the above macros are
40 (at the moment, silently) discarded.
41 
42 If a macro name begins with '.', then later attempts to redefine the
43 macro are an error. Note that the '.' is not part of the name itself.
44 
45 \subsection macros_writing Writing a Macro
46 
47 Within the body of a macro, there are several constructs that permit
48 testing for the presence of optional parameters. The simplest construct
49 is "%{-f}" which expands (literally) to "-f" if -f was mentioned when the
50 macro was invoked. There are also provisions for including text if flag
51 was present using "%{-f:X}". This macro expands to (the expansion of) X
52 if the flag was present. The negative form, "%{!-f:Y}", expanding to (the
53 expansion of) Y if -f was *not* present, is also supported.
54 
55 In addition to the "%{...}" form, shell expansion can be performed
56 using "%(shell command)". The expansion of "%(...)" is the output of
57 (the expansion of) ... fed to /bin/sh. For example, "%(date
58 +%%y%%m%%d)" expands to the string "YYMMDD" (final newline is
59 deleted). Note the 2nd % needed to escape the arguments to /bin/date.
60 There is currently an 8K limit on the size that this macro can expand
61 to.
62 
63 \subsection macros_builtin Builtin Macros
64 
65 There are several builtin macros (with reserved names) that are needed
66 to perform useful operations. The current list is
67 
68 \verbatim
69  %trace toggle print of debugging information before/after
70  expansion
71  %dump print the active (i.e. non-covered) macro table
72  %{load:...} load macros from a ... file
73 
74  %{echo:...} print ... to stderr
75  %{warn:...} print ... to stderr
76  %{error:...} print ... to stderr and return BADSPEC
77  %{verbose:...} expand ... argument iff --verbose has been specified
78 
79  %define ... define a macro
80  %undefine ... undefine a macro
81  %global ... define a macro whose body is available in global context
82 
83  %{uncompress:...} expand ... to FILE and test to see if FILE is
84  compressed. The expansion is
85  cat FILE # if not compressed
86  gzip -dc FILE # if gzip'ed
87  bzip2 -dc FILE # if bzip'ed
88  unzip -qq FILE # if zip'ed
89  lzop -dc FILE # if LZO compressed
90  lzma -dc FILE # if LZMA compressed
91  %{expand:...} like eval, expand ... to BODY and (re-)expand BODY
92 
93  %{basename:...} the trailing portion of ... with directory path removed
94  %{dirname:...} the leading directory path of the ... argument
95  %{realpath:...} the canonicalized path of the ... argument
96  %{getenv:...} the value of the ... envvar
97  %{shrink:...} trim from ends, horten intermediate, whitespace in ...
98  %{suffix:...} the trailing part after '.' of the ... argument
99  %{url2path:...} skip "scheme://user:pass@host:port" of a ... URI
100  %{u2p:...} same as %{url2path:...}
101 
102  %{mkstemp:...} a temporary file from ... template (see mkstemp(3))
103 
104  %{S:...} expand ... to SOURCE file name
105  %{P:...} expand ... to PATCH file name
106  %{F:...} expand ... to FILE file name
107 \endverbatim
108 
109 Macros may also be automatically included from /usr/lib/rpm/macros.
110 In addition, rpm itself defines numerous macros. To display the current
111 set, add "%dump" to the beginning of any spec file, process with rpm, and
112 examine the output from stderr.
113 
114 \subsection macros_example Example of a Macro
115 
116 Here is an example %patch definition from /usr/lib/rpm/macros:
117 
118 \verbatim
119  %patch(b:p:P:REz:) \
120  %define patch_file %{P:%{-P:%{-P*}}%{!-P:%%PATCH0}} \
121  %define patch_suffix %{!-z:%{-b:--suffix %{-b*}}}%{!-b:%{-z:--suffix %{-z*}}}%{!-z:%{!-b: }}%{-z:%{-b:%{error:Can't specify both -z(%{-z*}) and -b(%{-b*})}}} \
122  %{uncompress:%patch_file} | patch %{-p:-p%{-p*}} %patch_suffix %{-R} %{-E} \
123  ...
124 \endverbatim
125 
126 
127 The first line defines %patch with its options. The body of %patch is
128 
129 \verbatim
130  %{uncompress:%patch_file} | patch %{-p:-p%{-p*}} %patch_suffix %{-R} %{-E}
131 \endverbatim
132 
133 The body contains 7 macros, which expand as follows
134 
135 \verbatim
136  %{uncompress:...} copy uncompressed patch to stdout
137  %patch_file ... the name of the patch file
138  %{-p:...} if "-p N" was present, (re-)generate "-pN" flag
139  -p%{-p*} ... note patch-2.1 insists on contiguous "-pN"
140  %patch_suffix override (default) ".orig" suffix if desired
141  %{-R} supply -R (reversed) flag if desired
142  %{-E} supply -E (delete empty?) flag if desired
143 \endverbatim
144 
145 There are two "private" helper macros:
146 
147 \verbatim
148  %patch_file the gory details of generating the patch file name
149  %patch_suffix the gory details of overriding the (default) ".orig"
150 \endverbatim
151 
152 \subsection macros_using Using a Macro
153 
154 To use a macro, write:
155 
156 \verbatim
157  %NAME ...
158 \endverbatim
159 
160 or
161 
162 \verbatim
163  %{NAME}
164 \endverbatim
165 
166 The %{...} form allows you to place the expansion adjacent to other text.
167 The %NAME form, if a parameterized macro, will do argc/argv processing
168 of the rest of the line as described above. Normally you will likely want
169 to invoke a parameterized macro by using the %NAME form so that
170 parameters are expanded properly.
171 
172 Example:
173 \verbatim
174  %define mymacro() (echo -n "My arg is %1" ; sleep %1 ; echo done.)
175 \endverbatim
176 
177 Usage:
178 
179 \verbatim
180  %mymacro 5
181 \endverbatim
182 
183 This expands to:
184 
185 \verbatim
186  (echo -n "My arg is 5" ; sleep 5 ; echo done.)
187 \endverbatim
188 
189 This will cause all occurrences of %1 in the macro definition to be
190 replaced by the first argument to the macro, but only if the macro
191 is invoked as "%mymacro 5". Invoking as "%{mymacro} 5" will not work
192 as desired in this case.
193 
194 \subsection macros_commandline Command Line Options
195 
196 When the command line option "--define 'macroname value'" allows the
197 user to specify the value that a macro should have during the build.
198 Note lack of leading % for the macro name. We will try to support
199 users who accidentally type the leading % but this should not be
200 relied upon.
201 
202 Evaluating a macro can be difficult outside of an rpm execution context. If
203 you wish to see the expanded value of a macro, you may use the option
204 \verbatim
205  --eval '%MACRO'
206 \endverbatim
207 that will read rpm config files and print the macro expansion on stdout.
208 
209 Note: This works only macros defined in rpm configuration files, not for
210 macros defined in specfiles. You can use %{echo: %{your_macro_here}} if
211 you wish to see the expansion of a macro defined in a spec file.
212 
213 \subsection macros_configuration Configuration using Macros
214 
215 Starting in rpm 3.0, macros rather than rpmrc lines are used to configure rpm.
216 In general, all the rpmrc configuration lines documented in "Maximum RPM"
217 have been converted to macros, usually with a leading underscore, and the
218 same name that was used in rpmrc files. In some cases, there is no leading
219 underscore. Those macros existed in rpm-2.5.x and the underscore is omitted
220 in order to preserve the meaning and usage of macros that are defined during
221 spec file parsing.
222 
223 Here's an example to illustrate configuration using macros:
224 
225 \verbatim
226  Old way:
227  In /etc/rpmrc and/or ~/.rpmrc you put
228  something: some_value
229 
230  New way:
231  In /etc/rpm/macros and/or ~/.rpmmacros
232  %_something some_value
233 \endverbatim
234 
235 Here are 2 common FAQ for experienced users of rpm:
236 
237 \verbatim
238  1) --rcfile works differently.
239  Old way: rpm --rcfile whatever
240  New way: rpm --rcfile /usr/lib/rpm/rpmrc:whatever
241 
242  2) topdir (and other rpmrc configurables) work differently.
243 
244  Old way:
245  ~/.rpmrc contains
246  topdir: whatever
247 
248  New way:
249  /usr/lib/rpm/rpmrc contains
250  macrofiles: /usr/lib/rpm/macros: ... :~/.rpmmacros
251  ~/.rpmmacros contains
252  %_topdir whatever
253 \endverbatim
254 
255 \subsection macros_autoconf Macro Analogues of Autoconf Variables
256 
257 Several macro definitions provided by the default rpm macro set have uses in
258 packaging similar to the autoconf variables that are used in building packages:
259 
260 \verbatim
261  %_prefix /usr
262  %_exec_prefix %{_prefix}
263  %_bindir %{_exec_prefix}/bin
264  %_sbindir %{_exec_prefix}/sbin
265  %_libexecdir %{_exec_prefix}/libexec
266  %_datadir %{_prefix}/share
267  %_sysconfdir %{_prefix}/etc
268  %_sharedstatedir %{_prefix}/com
269  %_localstatedir %{_prefix}/var
270  %_libdir %{_exec_prefix}/lib
271  %_includedir %{_prefix}/include
272  %_oldincludedir /usr/include
273  %_infodir %{_prefix}/info
274  %_mandir %{_prefix}/man
275 \endverbatim
276 
277 */