/proc/self/root/usr/share/doc/rpm
This explorer reads the filesystem of the server it runs on, so /workspace/user isn't present here. Browsing and the terminal still work against this server's own disk from /.
/*! \page macros Macro syntax RPM has fully recursive spec file macros. Simple macros do straight textsubstitution. Parameterized macros include an options field, and performargc/argv processing on white space separated tokens to the next newline.During macro expansion, both flags and arguments are available as macroswhich are deleted at the end of macro expansion. Macros can be used(almost) anywhere in a spec file, and, in particular, in "included filelists" (i.e. those read in using %files -f \<file\>). In addition, macroscan be nested, hiding the previous definition for the duration of theexpansion of the macro which contains nested macros. \section macros_defining Defining a Macro To define a macro use: \verbatim %define <name>[(opts)] <body>\endverbatim All whitespace surrounding \<body\> is removed. Name may be composedof alphanumeric characters, and the character `_' and must be at least3 characters in length. A macro without an (opts) field is "simple" in thatonly recursive macro expansion is performed. A parameterized macro containsan (opts) field. The opts (i.e. string between parentheses) is passedexactly as is to getopt(3) for argc/argv processing at the beginning ofa macro invocation. While a parameterized macro is being expanded, thefollowing shell-like macros are available: \verbatim %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)\endverbatim At the end of invocation of a parameterized macro, the above macros are(at the moment, silently) discarded. \section macros_writing Writing a Macro Within the body of a macro, there are several constructs that permittesting for the presence of optional parameters. The simplest constructis "%{-f}" which expands (literally) to "-f" if -f was mentioned when themacro was invoked. There are also provisions for including text if flagwas present using "%{-f:X}". This macro expands to (the expansion of) Xif the flag was present. The negative form, "%{!-f:Y}", expanding to (theexpansion of) Y if -f was *not* present, is also supported. In addition to the "%{...}" form, shell expansion can be performedusing "%(shell command)". \section macros_builtin Builtin Macros There are several builtin macros (with reserved names) that are neededto perform useful operations. The current list is \verbatim %trace toggle print of debugging information before/after expansion %dump print the active (i.e. non-covered) macro table %getncpus return the number of CPUs %getconfdir expand to rpm "home" directory (typically /usr/lib/rpm) %dnl discard to next line (without expanding) %{echo:...} print ... to stdout %{warn:...} print warning: ... to stderr %{error:...} print error: ... to stderr and return an error %define ... define a macro %undefine ... undefine a macro %global ... define a macro whose body is available in global context %{macrobody:...} literal body of a macro %{basename:...} basename(1) macro analogue %{dirname:...} dirname(1) macro analogue %{suffix:...} expand to suffix part of a file name %{url2path:...} convert url to a local path %{getenv:...} getenv(3) macro analogue %{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 %{load:...} load a macro file %{lua:...} expand using the embedded Lua interpreter %{expand:...} like eval, expand ... to <body> and (re-)expand <body> %{expr:...} evaluate an expression %{shrink:...} trim leading and trailing whitespace, reduce intermediate whitespace to a single space %{quote:...} quote a parametric macro argument, needed to pass empty strings or strings with whitespace %{verbose:...} expand ... if rpm is in verbose mode (%{!verbose:...} works for non-verbose mode) %{S:...} expand ... to <source> file name %{P:...} expand ... to <patch> file name\endverbatim Macros may also be automatically included from /usr/lib/rpm/macros.In addition, rpm itself defines numerous macros. To display the currentset, add "%dump" to the beginning of any spec file, process with rpm, andexamine the output from stderr. \section conditionally_expanded_macros Conditionally Expanded Macros Sometimes it is useful to test whether a macro is defined or not. Syntax\verbatim%{?macro_name:value}%{?!macro_name:value}\endverbatimcan be used for this purpose. %{?macro_name:value} is expanded to "value"if "macro_name" is defined, otherwise it is expanded to the empty string.%{?!macro_name:value} is the negative variant. It is expanded to "value" if"macro_name" not is defined. Otherwise it is expanded to the empty string. Frequently used conditionally expanded macros are e.g.Define a macro if it is not defined:\verbatim%{?!with_python3: %global with_python3 1}\endverbatimA macro that is expanded to 1 if "with_python3" is defined and 0 otherwise:\verbatim%{?with_python3:1}%{!?with_python3:0}\endverbatimor shortly\verbatim0%{!?with_python3:1}\endverbatim %"{?macro_name}" is a shortcut for "%{?macro_name:%macro_name}". For "macro_name" that is builtin macro conditionally expanded macrosbehave differently. In such a case both macro "%{?builtin_macro:value}" andits negative version "%{?!builtin_macro:value}" are expanded exactly likethe macro without exclamation mark and question mark "%{builtin_macro:value}".There is a special case among builtin macros:/verbatim%{?load:file}/verbatimit works like "%{load:file}" with the difference that the expansion does notemit an error if the file fails to load. For more complex tests it is possible to use conditionals like %if, %ifarch or%ifos. But the conditionals are not macros thus they are not described here.For more information please refer to spec manual. \section macros_example Example of a Macro Here is an example %patch definition from /usr/lib/rpm/macros: \verbatim %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} \ ...\endverbatim The first line defines %patch with its options. The body of %patch is \verbatim %{uncompress:%patch_file} | patch %{-p:-p%{-p*}} %patch_suffix %{-R} %{-E}\endverbatim The body contains 7 macros, which expand as follows \verbatim %{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\endverbatim There are two "private" helper macros: \verbatim %patch_file the gory details of generating the patch file name %patch_suffix the gory details of overriding the (default) ".orig"\endverbatim \section macros_using Using a Macro To use a macro, write: \verbatim %<name> ...\endverbatim or \verbatim %{<name>}\endverbatim The %{...} form allows you to place the expansion adjacent to other text.The %\<name\> form, if a parameterized macro, will do argc/argv processingof the rest of the line as described above. Normally you will likely wantto invoke a parameterized macro by using the %\<name\> form so thatparameters are expanded properly. Example:\verbatim %define mymacro() (echo -n "My arg is %1" ; sleep %1 ; echo done.)\endverbatim Usage: \verbatim %mymacro 5\endverbatim This expands to: \verbatim (echo -n "My arg is 5" ; sleep 5 ; echo done.)\endverbatim This will cause all occurrences of %1 in the macro definition to bereplaced by the first argument to the macro, but only if the macrois invoked as "%mymacro 5". Invoking as "%{mymacro} 5" will not workas desired in this case. \section macros_shell_expansion Shell Expansion Shell expansion can be performed using "%(shell command)". The expansionof "%(...)" is the output of (the expansion of) ... fed to /bin/sh.For example, "%(date +%%y%%m%%d)" expands to the string "YYMMDD" (finalnewline is deleted). Note the 2nd % needed to escape the arguments to/bin/date. \section macros_expression_expansion Expression Expansion Expression expansion can be performed using "%[expression]". Anexpression consists of terms that can be combined usingoperators. Rpm supports three kinds of terms, numbers made upfrom digits, strings enclosed in double quotes (eg "somestring") andversions enclosed in double quotes preceded by v (eg v"3:1.2-1").Rpm will expand macros when evaluating terms. You can use the standard operators to combine terms: logicaloperators &&, ||, !, relational operators !=, ==, <, > , <=, >=,arithmetic operators +, -, /, *, the ternary operator ? :, andparentheses. For example, "%[ 3 + 4 * (1 + %two) ]" will expandto "15" if "%two" expands to "2". Version terms are compared usingrpm version ([epoch:]version[-release]) comparison algorithm,rather than regular string comparison. Note that the "%[expression]" expansion is different to the"%{expr:expression}" macro. With the latter, the macros in theexpression are expanded first and then the expression isevaluated (without re-expanding the terms). Thus\verbatim rpm --define 'foo 1 + 2' --eval '%{expr:%foo}'\endverbatimwill print "3". Using '%[%foo]' instead will result in theerror that "1 + 2" is not a number. Doing the macro expansion when evaluating the terms has twoadvantages. First, it allows rpm to do correct short-circuit processing when evaluation logical operators. Second, theexpansion result does not influence the expression parsing,e.g. '%["%file"] will even work if the "%file" macro expandsto a string that contains a double quote. \section macros_commandline Command Line Options When the command line option "--define 'macroname value'" allows theuser to specify the value that a macro should have during the build.Note lack of leading % for the macro name. We will try to supportusers who accidentally type the leading % but this should not berelied upon. Evaluating a macro can be difficult outside of an rpm execution context. Ifyou wish to see the expanded value of a macro, you may use the option\verbatim --eval '<macro expression>'\endverbatimthat will read rpm config files and print the macro expansion on stdout. Note: This works only macros defined in rpm configuration files, not formacros defined in specfiles. You can use %{echo: %{your_macro_here}} ifyou wish to see the expansion of a macro defined in a spec file. \section macros_configuration Configuration using Macros Starting in rpm 3.0, macros rather than rpmrc lines are used to configure rpm.In general, all the rpmrc configuration lines documented in "Maximum RPM"have been converted to macros, usually with a leading underscore, and thesame name that was used in rpmrc files. In some cases, there is no leadingunderscore. Those macros existed in rpm-2.5.x and the underscore is omittedin order to preserve the meaning and usage of macros that are defined duringspec file parsing. Here's an example to illustrate configuration using macros: \verbatim Old way: In /etc/rpmrc and/or ~/.rpmrc you put something: some_value New way: In /etc/rpm/macros and/or ~/.rpmmacros %_something some_value\endverbatim Here are 2 common FAQ for experienced users of rpm: \verbatim 1) --rcfile works differently. Old way: rpm --rcfile whatever New way: rpm --rcfile /usr/lib/rpm/rpmrc:whatever 2) topdir (and other rpmrc configurables) work differently. Old way: ~/.rpmrc contains topdir: whatever New way: /usr/lib/rpm/rpmrc contains macrofiles: /usr/lib/rpm/macros: ... :~/.rpmmacros ~/.rpmmacros contains %_topdir whatever\endverbatim \section macros_autoconf Macro Analogues of Autoconf Variables Several macro definitions provided by the default rpm macro set have uses inpackaging similar to the autoconf variables that are used in building packages: \verbatim %_prefix /usr %_exec_prefix %{_prefix} %_bindir %{_exec_prefix}/bin %_sbindir %{_exec_prefix}/sbin %_libexecdir %{_exec_prefix}/libexec %_datadir %{_prefix}/share %_sysconfdir /etc %_sharedstatedir %{_prefix}/com %_localstatedir %{_prefix}/var %_libdir %{_exec_prefix}/lib %_includedir %{_prefix}/include %_oldincludedir /usr/include %_infodir %{_datadir}/info %_mandir %{_datadir}/man\endverbatim */