diff options
| author | jbj <devnull@localhost> | 1998-07-08 17:50:48 +0000 |
|---|---|---|
| committer | jbj <devnull@localhost> | 1998-07-08 17:50:48 +0000 |
| commit | 94f5fbeec363059ca9eb986ee294ffcdf20bcb04 (patch) | |
| tree | 9609845f65b81f52f2fbc2ed4b6ba14ad60004e9 /docs | |
| parent | 209af5b9eb64f5aa35666ad6439c5c3db2f25f1b (diff) | |
| download | rpm-94f5fbeec363059ca9eb986ee294ffcdf20bcb04.tar.gz rpm-94f5fbeec363059ca9eb986ee294ffcdf20bcb04.tar.bz2 rpm-94f5fbeec363059ca9eb986ee294ffcdf20bcb04.zip | |
Add new fully recursive macro.c
CVS patchset: 2169
CVS date: 1998/07/08 17:50:48
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/macros | 132 |
1 files changed, 112 insertions, 20 deletions
diff --git a/docs/macros b/docs/macros index cd02378bb..0e9a08e8f 100644 --- a/docs/macros +++ b/docs/macros @@ -1,41 +1,133 @@ SPEC FILE MACROS ================ -RPM 2.3.9 introduces simple spec file macros. The macros can do -straight text substitution only. Macros can be used anywhere in -a spec file, and in "included file lists" (those read in using -%files -f <file>). +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> <expansion> +%define <name>[(opts)] <body> -All whitespace surrounding <expansion> is removed. Name may be composed -of alphanumeric characters, and the character `_'. Macro expansion is -performed on <expansion> so that <expansion> my reference other macros -that have already been defined. +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 + %# 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. + +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> +%<name> ... or %{<name>} -The later allows you to place the expansion adjacent to other text. - -Predefined Macros ------------------ - -The following macros are defined as the values they reference are -specified in the spec file: - -PACKAGE_VERSION -PACKAGE_RELEASE +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. |