doc/manual/macros

   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 \section 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 \section macros_writing Writing a Macro
  43
  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.
  51
  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
  58 to.
  59
  60 \section macros_builtin Builtin Macros
  61
  62 There are several builtin macros (with reserved names) that are needed
  63 to perform useful operations. The current list is
  64
  65 \verbatim
  66         %trace          toggle print of debugging information before/after
  67                         expansion
  68         %dump           print the active (i.e. non-covered) macro table
  69         %verbose        is rpm in verbose mode?
  70
  71         %{echo:...}     print ... to stdout
  72         %{warn:...}     print warning: ... to stderr
  73         %{error:...}    print error: ... to stderr and return an error
  74
  75         %define ...     define a macro
  76         %undefine ...   undefine a macro
  77         %global ...     define a macro whose body is available in global context
  78
  79         %{basename:...} basename(1) macro analogue
  80         %{dirname:...}  dirname(1) macro analogue
  81         %{suffix:...}   expand to suffix part of a file name
  82         %{url2path:...} convert url to a local path
  83         %{getenv:...}   getenv(3) macro analogue
  84         %{getconfdir:...}       expand to rpm "home" directory (typically /usr/lib/rpm)
  85         %{uncompress:...} expand ... to <file> and test to see if <file> is
  86                         compressed.  The expansion is
  87                                 cat <file>              # if not compressed
  88                                 gzip -dc <file>         # if gzip'ed
  89                                 bzip2 -dc <file>        # if bzip'ed
  90
  91         %{load:...}     load a macro file
  92         %{lua:...}      expand using the embedded Lua interpreter
  93         %{expand:...}   like eval, expand ... to <body> and (re-)expand <body>
  94         %{shrink:...}   trim leading and trailing whitespace, reduce
  95                         intermediate whitespace to a single space
  96         %{quote:...}    quote a parametric macro argument, needed to pass
  97                         empty strings or strings with whitespace
  98
  99         %{S:...}        expand ... to <source> file name
 100         %{P:...}        expand ... to <patch> file name
 101         %{F:...}        expand ... to <file> file name
 102 \endverbatim
 103
 104 Macros may also be automatically included from /usr/lib/rpm/macros.
 105 In addition, rpm itself defines numerous macros. To display the current
 106 set, add "%dump" to the beginning of any spec file, process with rpm, and
 107 examine the output from stderr.
 108
 109 \section macros_example Example of a Macro
 110
 111 Here is an example %patch definition from /usr/lib/rpm/macros:
 112
 113 \verbatim
 114         %patch(b:p:P:REz:) \
 115         %define patch_file      %{P:%{-P:%{-P*}}%{!-P:%%PATCH0}} \
 116         %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*})}}} \
 117                 %{uncompress:%patch_file} | patch %{-p:-p%{-p*}} %patch_suffix %{-R} %{-E} \
 118         ...
 119 \endverbatim
 120
 121
 122 The first line defines %patch with its options. The body of %patch is
 123
 124 \verbatim
 125         %{uncompress:%patch_file} | patch %{-p:-p%{-p*}} %patch_suffix %{-R} %{-E}
 126 \endverbatim
 127
 128 The body contains 7 macros, which expand as follows
 129
 130 \verbatim
 131         %{uncompress:...}       copy uncompressed patch to stdout
 132           %patch_file           ... the name of the patch file
 133         %{-p:...}               if "-p N" was present, (re-)generate "-pN" flag
 134           -p%{-p*}              ... note patch-2.1 insists on contiguous "-pN"
 135         %patch_suffix           override (default) ".orig" suffix if desired
 136         %{-R}                   supply -R (reversed) flag if desired
 137         %{-E}                   supply -E (delete empty?) flag if desired
 138 \endverbatim
 139
 140 There are two "private" helper macros:
 141
 142 \verbatim
 143         %patch_file     the gory details of generating the patch file name
 144         %patch_suffix   the gory details of overriding the (default) ".orig"
 145 \endverbatim
 146
 147 \section macros_using Using a Macro
 148
 149 To use a macro, write:
 150
 151 \verbatim
 152         %<name> ...
 153 \endverbatim
 154
 155 or
 156
 157 \verbatim
 158         %{<name>}
 159 \endverbatim
 160
 161 The %{...} form allows you to place the expansion adjacent to other text.
 162 The %\<name\> form, if a parameterized macro, will do argc/argv processing
 163 of the rest of the line as described above.  Normally you will likely want
 164 to invoke a parameterized macro by using the %\<name\> form so that
 165 parameters are expanded properly.
 166
 167 Example:
 168 \verbatim
 169         %define mymacro() (echo -n "My arg is %1" ; sleep %1 ; echo done.)
 170 \endverbatim
 171
 172 Usage:
 173
 174 \verbatim
 175         %mymacro 5
 176 \endverbatim
 177
 178 This expands to:
 179
 180 \verbatim
 181         (echo -n "My arg is 5" ; sleep 5 ; echo done.)
 182 \endverbatim
 183
 184 This will cause all occurrences of %1 in the macro definition to be
 185 replaced by the first argument to the macro, but only if the macro
 186 is invoked as "%mymacro 5".  Invoking as "%{mymacro} 5" will not work
 187 as desired in this case.
 188
 189 \section macros_commandline Command Line Options
 190
 191 When the command line option "--define 'macroname value'" allows the
 192 user to specify the value that a macro should have during the build.
 193 Note lack of leading % for the macro name.  We will try to support
 194 users who accidentally type the leading % but this should not be
 195 relied upon.
 196
 197 Evaluating a macro can be difficult outside of an rpm execution context. If
 198 you wish to see the expanded value of a macro, you may use the option
 199 \verbatim
 200         --eval '<macro expression>'
 201 \endverbatim
 202 that will read rpm config files and print the macro expansion on stdout.
 203
 204 Note: This works only macros defined in rpm configuration files, not for
 205 macros defined in specfiles. You can use %{echo: %{your_macro_here}} if
 206 you wish to see the expansion of a macro defined in a spec file.
 207
 208 \section macros_configuration Configuration using Macros
 209
 210 Starting in rpm 3.0, macros rather than rpmrc lines are used to configure rpm.
 211 In general, all the rpmrc configuration lines documented in "Maximum RPM"
 212 have been converted to macros, usually with a leading underscore, and the
 213 same name that was used in rpmrc files. In some cases, there is no leading
 214 underscore. Those macros existed in rpm-2.5.x and the underscore is omitted
 215 in order to preserve the meaning and usage of macros that are defined during
 216 spec file parsing.
 217
 218 Here's an example to illustrate configuration using macros:
 219
 220 \verbatim
 221    Old way:
 222         In /etc/rpmrc and/or ~/.rpmrc you put
 223                 something:      some_value
 224
 225    New way:
 226         In /etc/rpm/macros and/or ~/.rpmmacros
 227                 %_something     some_value
 228 \endverbatim
 229
 230 Here are 2 common FAQ for experienced users of rpm:
 231
 232 \verbatim
 233   1) --rcfile works differently.
 234     Old way:    rpm --rcfile whatever
 235     New way:    rpm --rcfile /usr/lib/rpm/rpmrc:whatever
 236
 237   2) topdir (and other rpmrc configurables) work differently.
 238
 239     Old way:
 240         ~/.rpmrc contains
 241                 topdir:         whatever
 242
 243     New way:
 244         /usr/lib/rpm/rpmrc contains
 245                 macrofiles:     /usr/lib/rpm/macros: ... :~/.rpmmacros
 246         ~/.rpmmacros contains
 247                 %_topdir        whatever
 248 \endverbatim
 249
 250 \section macros_autoconf Macro Analogues of Autoconf Variables
 251
 252 Several macro definitions provided by the default rpm macro set have uses in
 253 packaging similar to the autoconf variables that are used in building packages:
 254
 255 \verbatim
 256     %_prefix            /usr
 257     %_exec_prefix       %{_prefix}
 258     %_bindir            %{_exec_prefix}/bin
 259     %_sbindir           %{_exec_prefix}/sbin
 260     %_libexecdir        %{_exec_prefix}/libexec
 261     %_datadir           %{_prefix}/share
 262     %_sysconfdir        /etc
 263     %_sharedstatedir    %{_prefix}/com
 264     %_localstatedir     %{_prefix}/var
 265     %_libdir            %{_exec_prefix}/lib
 266     %_includedir        %{_prefix}/include
 267     %_oldincludedir     /usr/include
 268     %_infodir           %{_datadir}/info
 269     %_mandir            %{_datadir}/man
 270 \endverbatim
 271
 272 */