RPM-MACROPROC(7)

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}

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")

You can use the standard operators to combine terms:

• logical operators &&, ||, !
• relational operators !=, ==, <, >, <=, >=
• arithmetic operators +, -, /, *,
• the ternary operator ? :
• parentheses

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 interpeter, expanding to the code's print()'ed output.

See rpm-lua(7) for the details.

Automatic macros #

While a parameterized macro is being expanded, the following shell-like automatic macros are available:

If the built-in option processing was disabled with - as the OPTIONS field, only the following automatic macros are available:

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

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

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) 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) macro analogue.

Example:

%{basename:/some/dir/file.suf}

%{dirname:PATH}

dirname(1) 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 file name.

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 stdout, 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) macro analogue.

Example:

%{getenv:HOME}

%rpmversion

Expand to running RPM version.

Output #

%{echo:STRING}

Print STRING to process stdout.

Example:

%{echo:Building with foo}

%{warn:STRING}

Print STRING prefixed with "warning: " to process stderr.

Example:

%{warning:Foo is deprecated}

%{error:STRING}

Print STRING prefixed with "error: " to process stderr 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 file name of the specified Source NUMBER. %{S:n} is equivalent to %{SOURCEn}.

%{P:NUMBER}

Expand to the file name 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 file name (if parsing a file). (Added: 4.15)

%__file_lineno

Expand to current line number in current file (if parsing a file). (Added: 4.15)

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) shell utility. Note the 2nd % needed to escape the arguments to date(1):

%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]