diff options
Diffstat (limited to 'doc/manual/macros')
| -rw-r--r-- | doc/manual/macros | 135 |
1 files changed, 135 insertions, 0 deletions
diff --git a/doc/manual/macros b/doc/manual/macros new file mode 100644 index 000000000..4fcbfd14f --- /dev/null +++ b/doc/manual/macros @@ -0,0 +1,135 @@ +SPEC FILE MACROS +================ + +RPM 2.4.104 introduces fully recursive spec file macros. Simple macros +do straight text substitution. Parameterized macros include an options +field, and perform argc/argv processing on white space separated tokens +to the next newline. During macro expansion, both flags and arguments are +available as macros which are deleted at the end of macro expansion. +Macros can be used (almost) anywhere in a spec file, and, in particular, +in "included file lists" (i.e. those read in using %files -f <file>). +In addition, macros can be nested, hiding the previous definition for the +duration of the expansion of the macro which contains nested macros. + +Defining a Macro +---------------- + +To define a macro use: + +%define <name>[(opts)] <body> + +All whitespace surrounding <body> is removed. Name may be composed +of alphanumeric characters, and the character `_' and must be at least +3 characters in length. A macro without an (opts) field is "simple" in that +only recursive macro expansion is performed. A parameterized macro contains +an (opts) field. The opts (i.e. string between parantheses) is passed +exactly as is to getopts(3) for argc/argv processing at the beginning of +a macro invocation. While a parameterized macro is being expanded, the +following shell-like macros are available: + + %0 the name of the macro being invoked + %* all arguments (unlike shell, not including any processed flags) + %# the number of arguments + %{-f} if present at invocation, the flag f itself + %{-f*} if present at invocation, the argument to flag f + %1, %2 the arguments themselves (after getopt(3) processing) + +At the end of invocation of a parameterized macro, the above macros are +(at the moment, silently) discarded. + +Writing a Macro +--------------- + +Within the body of a macro, there are several constructs that permit +testing for the presence of optional parameters. The simplest construct +is "%{-f}" which expands (literally) to "-f" if -f was mentioned when the +macro was invoked. There are also provisions for including text if flag +was present using "%{-f:X}". This macro expands to (the expansion of) X +if the flag was present. The negative form, "%{!-f:Y}", expanding to (the +expansion of) Y if -f was *not* present, is also supported. + +In addition to the "%{...}" form, shell expansion can be performed +using "%(shell command)". The expansion of "%(...)" is the output of +(the expansion of) ... fed to /bin/sh. For example, "%(date ++%%y%%m%%d)" expands to the string "YYMMDD" (final newline is +deleted). Note the 2nd % needed to escape the arguments to /bin/date. +There is currently an 8K limit on the size that this macro can expand +to. + +Builtin Macros +-------------- +There are several builtin macros (with reserved names) that are needed +to perform useful operations. The current list is + + %trace toggle print of debugging information before/after + expansion + %dump print the active (i.e. non-covered) macro table + + %{echo:...} print ... to stderr + %{warn:...} print ... to stderr + %{error:...} print ... to stderr and return BADSPEC + + %define ... define a macro + %undefine ... undefine a macro + %global ... define a macro whose body is available in global context + + %{uncompress:...} expand ... to <file> and test to see if <file> is + compressed. The expansion is + cat <file> # if not compressed + gzip -dc <file> # if gzip'ed + bzip2 -dc <file> # if bzip'ed + %{expand:...} like eval, expand ... to <body> and (re-)expand <body> + + %{S:...} expand ... to <source> file name + %{P:...} expand ... to <patch> file name + %{F:...} expand ... to <file> file name + +Macros may also be automatically included from /usr/lib/rpm/macros. +In addition, rpm itself defines numerous macros. To display the current +set, add "%dump" to the beginning of any spec file, process with rpm, and +examine the output from stderr. + +Example of a Macro +------------------ + +Here is an example %patch definition from /usr/lib/rpm/macros: + +%patch(b:p:P:REz:) \ +%define patch_file %{P:%{-P:%{-P*}}%{!-P:%%PATCH0}} \ +%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*})}}} \ + %{uncompress:%patch_file} | patch %{-p:-p%{-p*}} %patch_suffix %{-R} %{-E} \ + ... + +The first line defines %patch with its options. The body of %patch is + + %{uncompress:%patch_file} | patch %{-p:-p%{-p*}} %patch_suffix %{-R} %{-E} + +The body contains 7 macros, which expand as follows + + %{uncompress:...} copy uncompressed patch to stdout + %patch_file ... the name of the patch file + %{-p:...} if "-p N" was present, (re-)generate "-pN" flag + -p%{-p*} ... note patch-2.1 insists on contiguous "-pN" + %patch_suffix override (default) ".orig" suffix if desired + %{-R} supply -R (reversed) flag if desired + %{-E} supply -E (delete empty?) flag if desired + +There are two "private" helper macros: + + %patch_file the gory details of generating the patch file name + %patch_suffix the gory details of overriding the (default) ".orig" + +Using a Macro +------------- + +To use a macro, write: + +%<name> ... + +or + +%{<name>} + +The %{...} form allows you to place the expansion adjacent to other text. +The %<name> form, if a parameterized macro, will do argc/argv processing +of the rest of the line as described above. |