--- name: "rpm-macros" section: "7" platform: "linux" package: "rpm-tools" version: "6.0.1-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/rpm-macros" --- # rpm-macros(7) RPM macro processor ## NAME rpm-macros - RPM macro processor ## SYNOPSIS ### Defining **%***NAME* *BODY* **%***NAME***(**\[*OPTIONS*\]**)** *BODY* ### Expanding **%***NAME* **%***NAME* \[*OPTIONS*\] \[*ARGUMENTS*\] **%{***NAME***}** **%{***NAME* \[*OPTIONS*\] *ARGUMENTS***}** **%{***NAME***:***ARGUMENT***}** **%{?***NAME***}** **%{?***NAME***:***VALUE-IF-DEFINED***}** **%{!?***NAME***:***VALUE-IF-NOT-DEFINED***}** **%(***SHELL-COMMAND***)** **%\[***EXPRESSION***\]** **%\[***EXPRESSION* **?** *VALUE-IF-TRUE* **:** *VALUE-IF-FALSE***\]** **%{lua:***LUA-CODE***}** ## DESCRIPTION RPM has a powerful built-in macro processor. The primary uses of macros are configuration and other utility functions for RPM itself, and as a packaging aid in spec files. In addition to simple text substitution, the macro processor supports the following facilities: - • function-like **PARAMETRIC MACROS** with options and arguments processing and locally scoped automatic and user-defined macros - • **Shell expansion** - • **Expression expansion** - • **Lua expansion** for embedded Lua processing - • various **BUILT-IN MACROS** for string processing and OS interaction The syntax for defining simple macros is: *NAME* *BODY* All whitespace surrounding *BODY* is removed. *NAME* may be composed of alphanumeric characters and the underscore (**\_**), and must be at least two characters in length. The body is (re-)expanded on each macro invocation. Macro names and options are case-sensitive. See **PARAMETRIC MACROS** for the more advanced macro variant with options and arguments processing. Macros can be defined via [**rpm-macrofile**(5)](/rpm-macrofile/5.md) files, and fully managed with macro primitives **%define**, **%global** and **%undefine**, RPM command-line described in [**rpm-common**(8)](/rpm-common/8.md) and the API (C, Python, Lua). Except for those defined inside parametric macros, macros are always global in scope. RPM macros are stacked, ie. when redefining an already existing macro, it shadows the previous definition instead of replacing it, and undefining a macro only pops the topmost definition, thus activating the previous macro definition. Note that this manual only describes the macro processor engine itself. On a normal RPM based system, there are a vast number of other macros defined through [**rpm-macrofile**(5)](/rpm-macrofile/5.md) files that will not be covered here. ## EXPANSION To expand a macro, place **%** in front of it. Several forms are supported: **%***NAME* Expand the macro *NAME*. **%{***NAME***}** Expand the macro *NAME*, allowing placement adjacent to other text (similar to **${ENV}** in shell). **%***NAME* \[*OPTIONS*\] \[*ARGUMENTS*\] Expand the parametric/built-in macro *NAME*, using options and arguments parsed up to the string end or next newline. **--** can be used to separate options from arguments. **%{***NAME* \[*OPTIONS*\] \[*ARGUMENTS*\]**}** Expand the parametric/built-in macro *NAME*, using options and arguments parsed up to the closing **}**. Allows usage adjacent to other text. **%{***NAME***:***ARGUMENT***}** Expand the parametric/built-in macro *NAME*, using the string after **:** as the sole argument. Allows usage adjacent to other text. Note: The syntaxes for calling parametric and built-in macros are generally interchangeable now, but prior to 4.18, the **%{***NAME***:***ARGUMENT***}** syntax was exclusive to built-in macros. Macro expansion can be escaped by placing a second **%** in front of the macro, for example **%%{name}** would be expanded to **%{name}**. Attempting to expand an undefined macro expands to the literal invocation, e.g. **%\_undefined** expands to **%\_undefined**. If this is not desired, use conditionals. Macro expansions can recurse up to 64 levels. ### Shell expansion Shell expansion can be performed using **%(***shell command***)**. *shell\_command* is expanded before executing it with */bin/sh*, whose output becomes the expansion of the macro. The trailing newline is deleted. Example: ``` %(echo aa-bb-cc | tr '-' '.') ``` ### Conditional expansion The macro processor supports testing whether a macro is defined or not. **%{?***NAME***:***VALUE***}** Expands to the expansion of *VALUE* if *NAME* is defined, otherwise to an empty string. **%{!?***NAME***:***VALUE***}** Expands to the expansion of *VALUE* if *NAME* is *not* defined, otherwise it expands to an empty string. **%{?***NAME***}** Shorthand for **%{?***NAME***:%{***NAME***}}**. For more complex tests, use **Expression expansion** or **Lua expansion**. Note that **%if**, **%ifarch** and the like are not macros, they are spec directives and only usable in that context. Note that in RPM \>= 4.17, conditionals on built-in macros simply test for existence of that built-in, just like with any other macros. In older versions, the behavior of conditionals on built-ins is undefined. ### Expression expansion Expression expansion can be performed using **%\[***EXPRESSION***\]**. An expression consists of terms that can be combined using operators. RPM supports three kinds of terms: - • numbers made up from digits - • strings enclosed in double quotes (e.g **"somestring"**) - • versions enclosed in double quotes preceded by **v** (e.g **v"3:1.2-1"**) RPM will expand macros when evaluating terms. You can use the standard operators to combine terms: - • logical operators **&&**, **\|\|**, **!** - • relational operators **!=**, **==**, **\<**, **\>**, **\<=**, **\>=** - • arithmetic operators **+**, **-**, **/**, **\***, - • the ternary operator **? :** - • parentheses For example, **%\[ 3 + 4 \* (1 + %two) \]** will expand to **15** if **%two** expands to **2**. Version terms are compared using RPM 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 the expression are expanded first and then the expression is evaluated (without re-expanding the terms). Thus ``` rpm --define 'foo 1 + 2' --eval '%{expr:%foo}' ``` will print **3**. Using **%\[%foo\]** instead will result in the error that "1 + 2" is not a number. Doing the macro expansion when evaluating the terms has two advantages. First, it allows RPM to do correct short-circuit processing when evaluating logical operators. Second, the expansion result does not influence the expression parsing, e.g. **%\["%file"\]** will even work if the **%file** macro expands to a string that contains a double quote. Added: 4.16.0 ### Lua expansion The most powerful of the macro expansion methods is using RPM's embedded Lua interpreter: **%{lua:***LUA-CODE***}** Execute *LUA-CODE* using RPM's embedded Lua interpreter, expanding to the code's **print()**'ed output. See [**rpm-lua**(7)](/rpm-lua/7.md) for the details. ## PARAMETRIC MACROS Parametric macros are a powerful mechanism that allows building function-like utility macros with option processing and accepting a variable number of arguments, much like common shell tools. The syntax for defining parametric macros is: *NAME*(\[*OPTIONS*\]) *BODY* If present, the *OPTIONS* (i.e. the string between parentheses) are passed exactly as is to [**getopt**(3)](/getopt/3.md) for argc/argv processing at the beginning of a macro invocation. Only short options are supported. **-** as the sole *OPTIONS* field disables RPM's option processing. This allows macros to fully decide how to handle their input, e.g. if the arguments of the macro only/mostly consist of items starting with **-**, the default processing only gets in the way. ### Automatic macros While a parameterized macro is being expanded, the following shell-like automatic macros are available: | | | | --- | --- | | **Macro** | **Description** | | **%0** | the name of the macro being invoked | | **%\*** | all arguments (unlike shell, not including any processed flags) | | **%\*\*** | all arguments (including any processed flags) | | **%#** | the number of arguments | | **%{-f}** | if present at invocation, the last occurrence of flag **f** (flag and argument) | | **%{-f\*}** | if present at invocation, the argument to the last occurrence of flag **f** | | **%1**, **%2**, ... | the arguments themselves (after [**getopt**(3)](/getopt/3.md) processing) | If the built-in option processing was disabled with **-** as the *OPTIONS* field, only the following automatic macros are available: | | | | --- | --- | | **Macro** | **Description** | | **%0** | the name of the macro being invoked | | **%\***, **%\*\*** | all arguments | | **%#** | the number of arguments | | **%1**, **%2**, ... | the arguments themselves | Automatic macros are automatically defined and undefined on parametric macro entry and exit. ### Accessing options Within the body of a parametric 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 a 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. ### Scope and visibility In general, macros have a global scope, regardless of where and how they were defined. However, macros defined inside parametric macros have non-global scope as follows: - • automatic macros have local scope, ie. are only visible on the call-level of the macro itself - • user-defined local macros have nested scope, ie. are visible on the call-level of the macro itself and deeper That is, a parametric macro cannot see the options or arguments of another one, but a user-defined local macro in a calling macro can be accessed in the callee(s). To define a global macro inside a parametric macro, you *must* use **%global** instead of **%define**. Also note that because such a macro may be referring to other macros only visible in the current scope, **%global** *expands the* *macro body once at the time of definition*. ### Calling convention When a parametric macro is expanded, the following calling convention is used: - 1\. any arguments to the macro are expanded on the call-level of the callee - 2\. any options to the macro are processed - 3\. automatic macros are set up for the options and the arguments - 4\. the macro body is recursively expanded - 5\. all macros defined on this call-level are discarded ## BUILT-IN MACROS RPM supports the following built-in macros for various operations. Built-in macros cannot be undefined or overridden. Note: The **%{name:arg}** style is used here as it's the most backwards compatible and does not require quoting for whitespace, but it can generally be replaced with the other expansion forms too. Built-ins taking multiple arguments must use other styles, as indicated below. ### Macro manipulation The macro primitives are used for macro manipulation in spec files and other macros. Note that all these operate on the macro name *without* the preceding **%**-character. **%define** *NAME*\[(\[*OPTIONS*\])\] *BODY* This is the primary way to define macros. A **%define** is always fully declarative: no macro expansion takes place, and it has no side-effects. Macros defined with it are in global scope, unless the definition occurs inside a parametric macro. Example: ``` %define mypath /usr/bin/mine ``` **%global** *NAME*\[(\[*OPTIONS*\])\] *BODY* The **%global** primitive is identical in syntax to **%define**, but has two critically important behavioral differences: as it's name suggests, a macro defined with **%global** always has a global scope regardless of where it's used. The second difference is that the *BODY* is expanded once at the time of definition and the expansion becomes the actual macro body. Thus, arbitrary code execution and side-effects may occur when **%global** is used, depending on the contents and the other macros used in *BODY*. The latter can be handy for avoiding redundant, possibly expensive macro expansions if the value does not change, but be aware of the side-effects. Note that while **%global** technically accepts an *OPTIONS* field, it is ill-suited for defining parametric macros because of the *BODY* expansion behavior. Example: ``` %global snapver 0-0.48.20240616git ``` **%undefine** *NAME* Note that **%undefine** only pops a macro definition from the stack, so using it does *not* guarantee that *NAME* is undefined after calling **%undefine** on it. Automatic macros and built-in macros cannot be undefined. Example: ``` %undefine mypath ``` **%{load:***FILE***}** Load an [**rpm-macrofile**(5)](/rpm-macrofile/5.md) file. (Added: 4.12.0) Example: ``` %{load:/some/dir/macros.foo} ``` ### Macro expansion **%{expand:***BODY***}** Expand *BODY* as if it were a macro body. Useful for increased indirection, such as to expand a macro name constructed from two or more macros. Example: ``` %{expand:%{foo_prefix}%{foo_suffix}} ``` **%{expr:***EXPRESSION*} Expand *EXPRESSION*. See **Expression expansion**. (Added: 4.15.0) Example: ``` %{expr:5*1024} ``` **%{lua:***LUA-CODE***}** Expand to output of *LUA-CODE* using the embedded Lua interpreter. See **Lua expansion**. Example: ``` %{lua:for i=65,90 do print(string.char(i)) end} ``` **%{macrobody:***NAME***}** Expand to the literal body of the macro *NAME*. (Added: 4.16.0) Example: ``` %{macrobody:_libdir} ``` ### String operations **%dnl** Discard to next line (without expanding anything). **%dnl** is the recommended way to comment out things in spec files because it works everywhere and disables macro processing for that line. (Added: 4.15.0) Example: ``` %dnl This is a comment on %{mymacro} behavior ``` **%{gsub** *STRING*, *PATTERN*, *REPL* \[,*N*\]**}** Replace all (or *N* first if given) occurrences of *PATTERN* in *STRING* by *REPL*. Added: 4.19.0 Example: ``` %{gsub aabbaacc aa dd 1} ``` **%{len:***STRING***}** Expand to length of *STRING*. (Added: 4.19.0) Example: ``` %{len:9bf7da058a7c582878310e75be3d56a5a8b67f95} ``` **%{lower:***STRING***}** Expand to lowercase *STRING*. (Added: 4.19.0) Example: ``` %{lower:CamelCase}' ``` **%{quote:***STRING***}** Quote arguments for passing empty strings and strings with embedded whitespace as parametric macro arguments. (Added: 4.14.0) Example: ``` %myzip -x %{quote:empty spaces.zip} ``` **%{rep** *STRING*, *N* \[,*SEP*\]**}** Expand to a string that is the concatenation of *N* copies of *STRING*, separated by *SEP* (if specified). Added: 4.19.0 Example: ``` %{rep a 5} ``` **%{reverse:***STRING***}** Reverse a string. (Added: 4.19.0) Example: ``` %{reverse:tac} ``` **%{shescape:***STRING***}** Single quote *STRING* with escapes for use in shell. (Added: 4.18.0) Example: ``` %{shescape:foo's} ``` **%{shrink:***STRING***}** Trim leading and trailing whitespace from *STRING*, reduce intermediate whitespace to a single space. (Added: 4.14.0) Example: ``` %{shrink:aa bb ccc } ``` **%{span:***STRING***}** As-is string, handy for wrapping multiline macros. (Added: 6.0.0) Example: ``` %{span: %one thing %another thing } ``` **%{sub** *STRING*, *I*, \[,*J*\]**}** Expand to substring of *STRING* that starts at **I** and continues until **J**. **I** and **J** can be negative to index from the string's end. If **J** is absent, then it is assumed to be equal to **-1** (ie. string end). Added: 4.19.0 Example: ``` *%{sub myfile.zip 3 6}* ``` **%{upper:***STRING***}** Expand to uppercase *STRING*. (Added: 4.19.0) Example: ``` %{upper:CamelCase}' ``` ### File and path operations **%{basename:***PATH***}** [**basename**(1)](/basename/1.md) macro analogue. Example: ``` %{basename:/some/dir/file.suf} ``` **%{dirname:***PATH***}** [**dirname**(1)](/dirname/1.md) macro analogue. Example: ``` %{dirname:/some/dir/file.suf} ``` **%{exists:***PATH***}** Test file existence, expands to 1/0. (Added: 4.18.0) Example: ``` %{exists:%{builddir}/myflag.txt} ``` **%{suffix:***PATH***}** Expand to suffix part of a filename. Example: ``` %{suffix:myfile.zip} ``` **%{url2path:***URL***}** Convert url to a local path. Example: ``` %{url2path:http://rpm.org/not/there} ``` **%{uncompress:***PATH***}** Expand to a command for outputting argument *PATH* to standard output, uncompressing as needed. Example: ``` %{uncompress /my/source.tar.gz} ``` **%{xdg:***KIND***}** Expand to XDG base directory paths. Supported values for *KIND* are: - • **cache**: user-specific non-essential (cached) data - • **config**: user-specific configuration files - • **data**: user-specific data files - • **state**: user-specific state data Added: 6.0.0 Example: ``` %{xdg config} ``` ### Environment info **%getncpus** Expand to the number of available CPUs. (Added: 4.15.0) **%{getncpus:***KIND***}** Expand to the number of available CPUs, supported valued for *KIND* are - • **total**: total number of available CPUs (same as **%getncpus**) - • **proc**: number of available CPUs for processes - • **thread**: number of available CPUs for threads **proc** and **thread** account for available memory, including address space limitations for threads. Added: 4.19.0. Example: ``` %{getncpus proc} ``` **%getconfdir** Expand to RPM "home" directory (typically /usr/lib/rpm). **%{getenv:***NAME***}** [**getenv**(3)](/getenv/3.md) macro analogue. Example: ``` %{getenv:HOME} ``` **%rpmversion** Expand to running RPM version. ### Output **%{echo:***STRING***}** Print *STRING* to process standard output. Example: ``` %{echo:Building with foo} ``` **%{warn:***STRING***}** Print *STRING* prefixed with "warning: " to process standard error. Example: ``` %{warning:Foo is deprecated} ``` **%{error:***STRING***}** Print *STRING* prefixed with "error: " to process standard error and flag an error in the macro processor. Example: ``` %{error:Invalid argument} ``` **%verbose** Expand to 1/0 whether RPM is in verbose mode or not. (Added: 4.17.1) **%{verbose:***STRING***}** Expand to *STRING* if RPM is in verbose mode, the empty string if not. (Added: 4.17.1) Example: ``` %{verbose:-x} ``` ### Spec specific macros **%{S:***NUMBER***}** Expand to the filename of the specified Source *NUMBER*. **%{S:n}** is equivalent to **%{SOURCEn}**. **%{P:***NUMBER***}** Expand to the filename of the specified Patch *NUMBER*. **%{P:n}** is equivalent to **%{PATCHn}**. ### Diagnostics **%trace** Toggle print of debugging information before/after expansion. **%dump** Print the active (i.e. non-covered) macro table. **%\_\_file\_name** Expand to current filename (if parsing a file). (Added: 4.15) **%\_\_file\_lineno** Expand to current line number in current file (if parsing a file). (Added: 4.15) ## EXAMPLES ### Example 1. Define a simple macro Define macro **mylib** to a path relative to **%{\_libdir}** macro in a spec: ``` %define mylib %{_libdir}/mine ``` ### Example 2. Define a parametric macro Define parametric macro **myhelper** which executes the program specified by **%myprog** with it's first argument and always passing the option **--some-opt** to it, and additionally the **--xtra** option if it received the **-x** option itself: ``` %define myhelper(x) %{myprog} --some-opt %{?-x:--xtra} %{1} ``` ### Example 3. Define a macro utilizing shell expansion Define macro **%today** that expands to the current date in *YYMMDD* format by calling the [**date**(1)](/date/1.md) shell utility. Note the 2nd **%** needed to escape the arguments to [**date**(1)](/date/1.md): ``` %define today %(date +%%y%%m%%d) ``` ### Example 4. Define a macro conditionally Define macro **mypath** if it wasn't previously defined: ``` %{!?mypath: %define mypath /some/where} ``` ### Example 5. Conditional expansion Expands to **1** if **use\_foo** is defined and **0** otherwise: ``` %{?use_foo:1}%{!?use_foo:0} ``` ### Example 6. Expressions Calculate 5 \* 1024: ``` %[5 * 1024] ``` Expand to literal **true** or **false** depending on a condition: ``` %[1 < 2 ? "true" : "false"] ``` Compare versions, expanding to **1** or **0** on true/false: ``` %[ v"3.1.0-1" < v"1.0~alpha-2" ? 1 : 0] ``` Expands to **1** if **%aa** expands to **5**, otherwise expands to **2**: ``` %[ "%{aa}" == "5" ? 1 : 2] ``` ## DEBUGGING Some useful tools for working with and troubleshooting macros: **rpm --eval "***VALUE***"** Expand *VALUE* on the command line. **rpm --define "aa 11" --eval "%aa"** Define and evaluate a macro on the command line. **rpm --eval "%global unamer %(uname -r)" --eval "%{macrobody:unamer}"** Define and examine macro body using **%global** on the command line. **rpm --eval "%define unamer %(uname -r)" --eval "%{macrobody:unamer}"** Define and examine macro body using **%define** on the command line. **rpmlua** Run an interactive shell in the embedded Lua environment. **rpmlua -e 'print(macros.defined("\_libdir"))'** Using the embedded Lua interpreter in standalone form, print print 1/0 whether macro **\_libdir** is defined or not. **rpmspec --shell** Run an interactive shell in the macro environment. **rpmspec --shell telnet.spec** Run an interactive shell in the macro environment after parsing **telnet.spec**. ## SEE ALSO [**rpm**(8)](/rpm/8.md) [**rpm-common**(8)](/rpm-common/8.md) [**rpm-macrofile**(5)](/rpm-macrofile/5.md) [**rpm-config**(5)](/rpm-config/5.md) [**rpm-lua**(7)](/rpm-lua/7.md) [**rpmspec**(1)](/rpmspec/1.md) [**rpmlua**(1)](/rpmlua/1.md)