1 /*! \page macros Macro syntax
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.
13 \subsection macros_defining Defining a Macro
15 To define a macro use:
18 %define NAME[(OPTS)] BODY
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:
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)
39 At the end of invocation of a parameterized macro, the above macros are
40 (at the moment, silently) discarded.
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.
45 \subsection macros_writing Writing a Macro
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.
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
63 \subsection macros_builtin Builtin Macros
65 There are several builtin macros (with reserved names) that are needed
66 to perform useful operations. The current list is
69 %trace toggle print of debugging information before/after
71 %dump print the active (i.e. non-covered) macro table
72 %{load:...} load macros from a ... file
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
79 %define ... define a macro
80 %undefine ... undefine a macro
81 %global ... define a macro whose body is available in global context
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
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:...}
102 %{mkstemp:...} a temporary file from ... template (see mkstemp(3))
104 %{S:...} expand ... to SOURCE file name
105 %{P:...} expand ... to PATCH file name
106 %{F:...} expand ... to FILE file name
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.
114 \subsection macros_example Example of a Macro
116 Here is an example %patch definition from /usr/lib/rpm/macros:
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} \
127 The first line defines %patch with its options. The body of %patch is
130 %{uncompress:%patch_file} | patch %{-p:-p%{-p*}} %patch_suffix %{-R} %{-E}
133 The body contains 7 macros, which expand as follows
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
145 There are two "private" helper macros:
148 %patch_file the gory details of generating the patch file name
149 %patch_suffix the gory details of overriding the (default) ".orig"
152 \subsection macros_using Using a Macro
154 To use a macro, write:
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.
174 %define mymacro() (echo -n "My arg is %1" ; sleep %1 ; echo done.)
186 (echo -n "My arg is 5" ; sleep 5 ; echo done.)
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.
194 \subsection macros_commandline Command Line Options
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
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
207 that will read rpm config files and print the macro expansion on stdout.
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.
213 \subsection macros_configuration Configuration using Macros
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
223 Here's an example to illustrate configuration using macros:
227 In /etc/rpmrc and/or ~/.rpmrc you put
228 something: some_value
231 In /etc/rpm/macros and/or ~/.rpmmacros
232 %_something some_value
235 Here are 2 common FAQ for experienced users of rpm:
238 1) --rcfile works differently.
239 Old way: rpm --rcfile whatever
240 New way: rpm --rcfile /usr/lib/rpm/rpmrc:whatever
242 2) topdir (and other rpmrc configurables) work differently.
249 /usr/lib/rpm/rpmrc contains
250 macrofiles: /usr/lib/rpm/macros: ... :~/.rpmmacros
251 ~/.rpmmacros contains
255 \subsection macros_autoconf Macro Analogues of Autoconf Variables
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:
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