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 parantheses) is passed
26
exactly as is to getopts(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
\subsection macros_writing Writing a Macro
44
Within the body of a macro, there are several constructs that permit
45
testing for the presence of optional parameters. The simplest construct
46
is "%{-f}" which expands (literally) to "-f" if -f was mentioned when the
47
macro was invoked. There are also provisions for including text if flag
48
was present using "%{-f:X}". This macro expands to (the expansion of) X
49
if the flag was present. The negative form, "%{!-f:Y}", expanding to (the
50
expansion of) Y if -f was *not* present, is also supported.
52
In addition to the "%{...}" form, shell expansion can be performed
53
using "%(shell command)". The expansion of "%(...)" is the output of
54
(the expansion of) ... fed to /bin/sh. For example, "%(date
55
+%%y%%m%%d)" expands to the string "YYMMDD" (final newline is
56
deleted). Note the 2nd % needed to escape the arguments to /bin/date.
57
There is currently an 8K limit on the size that this macro can expand
60
\subsection macros_builtin Builtin Macros
62
There are several builtin macros (with reserved names) that are needed
63
to perform useful operations. The current list is
66
%trace toggle print of debugging information before/after
68
%dump print the active (i.e. non-covered) macro table
70
%{echo:...} print ... to stderr
71
%{warn:...} print ... to stderr
72
%{error:...} print ... to stderr and return BADSPEC
74
%define ... define a macro
75
%undefine ... undefine a macro
76
%global ... define a macro whose body is available in global context
78
%{uncompress:...} expand ... to <file> and test to see if <file> is
79
compressed. The expansion is
80
cat <file> # if not compressed
81
gzip -dc <file> # if gzip'ed
82
bzip2 -dc <file> # if bzip'ed
83
%{expand:...} like eval, expand ... to <body> and (re-)expand <body>
85
%{S:...} expand ... to <source> file name
86
%{P:...} expand ... to <patch> file name
87
%{F:...} expand ... to <file> file name
90
Macros may also be automatically included from /usr/lib/rpm/macros.
91
In addition, rpm itself defines numerous macros. To display the current
92
set, add "%dump" to the beginning of any spec file, process with rpm, and
93
examine the output from stderr.
95
\subsection macros_example Example of a Macro
97
Here is an example %patch definition from /usr/lib/rpm/macros:
101
%define patch_file %{P:%{-P:%{-P*}}%{!-P:%%PATCH0}} \
102
%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*})}}} \
103
%{uncompress:%patch_file} | patch %{-p:-p%{-p*}} %patch_suffix %{-R} %{-E} \
108
The first line defines %patch with its options. The body of %patch is
111
%{uncompress:%patch_file} | patch %{-p:-p%{-p*}} %patch_suffix %{-R} %{-E}
114
The body contains 7 macros, which expand as follows
117
%{uncompress:...} copy uncompressed patch to stdout
118
%patch_file ... the name of the patch file
119
%{-p:...} if "-p N" was present, (re-)generate "-pN" flag
120
-p%{-p*} ... note patch-2.1 insists on contiguous "-pN"
121
%patch_suffix override (default) ".orig" suffix if desired
122
%{-R} supply -R (reversed) flag if desired
123
%{-E} supply -E (delete empty?) flag if desired
126
There are two "private" helper macros:
129
%patch_file the gory details of generating the patch file name
130
%patch_suffix the gory details of overriding the (default) ".orig"
133
\subsection macros_using Using a Macro
135
To use a macro, write:
147
The %{...} form allows you to place the expansion adjacent to other text.
148
The %<name> form, if a parameterized macro, will do argc/argv processing
149
of the rest of the line as described above. Normally you will likely want
150
to invoke a parameterized macro by using the %<name> form so that
151
parameters are expanded properly.
155
%define mymacro() (echo -n "My arg is %1" ; sleep %1 ; echo done.)
167
(echo -n "My arg is 5" ; sleep 5 ; echo done.)
170
This will cause all occurances of %1 in the macro definition to be
171
replaced by the first argument to the macro, but only if the macro
172
is invoked as "%mymacro 5". Invoking as "%{mymacro} 5" will not work
173
as desired in this case.
175
\subsection macros_commandline Command Line Options
177
When the command line option "--define 'macroname value'" allows the
178
user to specify the value that a macro should have during the build.
179
Note lack of leading % for the macro name. We will try to support
180
users who accidentally type the leading % but this should not be
183
Evaluating a macro can be difficult outside of an rpm execution context. If
184
you wish to see the expanded value of a macro, you may use the option
186
--eval '<macro expression>'
188
that will read rpm config files and print the macro expansion on stdout.
190
Note: This works only macros defined in rpm configuration files, not for
191
macros defined in specfiles. You can use %{echo: %{your_macro_here}} if
192
you wish to see the expansion of a macro defined in a spec file.
194
\subsection macros_configuration Configuration using Macros
196
Starting in rpm 3.0, macros rather than rpmrc lines are used to configure rpm.
197
In general, all the rpmrc configuration lines documented in "Maximum RPM"
198
have been converted to macros, usually with a leading underscore, and the
199
same name that was used in rpmrc files. In some cases, there is no leading
200
underscore. Those macros existed in rpm-2.5.x and the underscore is omitted
201
in order to preserve the meaning and usage of macros that are defined during
204
Here's an example to illustrate configuration using macros:
208
In /etc/rpmrc and/or ~/.rpmrc you put
209
something: some_value
212
In /etc/rpm/macros and/or ~/.rpmmacros
213
%_something some_value
216
Here are 2 common FAQ for experienced users of rpm:
219
1) --rcfile works differently.
220
Old way: rpm --rcfile whatever
221
New way: rpm --rcfile /usr/lib/rpm/rpmrc:whatever
223
2) topdir (and other rpmrc configurables) work differently.
230
/usr/lib/rpm/rpmrc contains
231
macrofiles: /usr/lib/rpm/macros: ... :~/.rpmmacros
232
~/.rpmmacros contains
236
\subsection macros_autoconf Macro Analogues of Autoconf Variables
238
Several macro definitions provided by the default rpm macro set have uses in
239
packaging similar to the autoconf variables that are used in building packages:
243
%_exec_prefix %{_prefix}
244
%_bindir %{_exec_prefix}/bin
245
%_sbindir %{_exec_prefix}/sbin
246
%_libexecdir %{_exec_prefix}/libexec
247
%_datadir %{_prefix}/share
248
%_sysconfdir %{_prefix}/etc
249
%_sharedstatedir %{_prefix}/com
250
%_localstatedir %{_prefix}/var
251
%_libdir %{_exec_prefix}/lib
252
%_includedir %{_prefix}/include
253
%_oldincludedir /usr/include
254
%_infodir %{_prefix}/info
255
%_mandir %{_prefix}/man
added
removed
doc/manual/macros
