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}

%{!?NAME:VALUE}

%{?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}

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

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

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

%define mypath /usr/bin/mine

%global NAME[([OPTIONS])] BODY

%global snapver 0-0.48.20240616git

%undefine NAME

%undefine mypath

%{load:FILE}

%{load:/some/dir/macros.foo}

Macro expansion¶

%{expand:BODY}

%{expand:%{foo_prefix}%{foo_suffix}}

%{expr:EXPRESSION}

%{expr:5*1024}

%{lua:LUA-CODE}

%{lua:for i=65,90 do print(string.char(i)) end}

%{macrobody:NAME}

%{macrobody:_libdir}

String operations¶

%dnl

%dnl This is a comment on %{mymacro} behavior

%{gsub STRING, PATTERN, REPL [,N]}

%{gsub aabbaacc aa dd 1}

%{len:STRING}

%{len:9bf7da058a7c582878310e75be3d56a5a8b67f95}

%{lower:STRING}

%{lower:CamelCase}'

%{quote:STRING}

%myzip -x %{quote:empty spaces.zip}

%{rep STRING, N [,SEP]}

%{rep a 5}

%{reverse:STRING}

%{reverse:tac}

%{shescape:STRING}

%{shescape:foo's}

%{shrink:STRING}

%{shrink:aa  bb   ccc   }

%{span:STRING}

%{span:
	%one thing
	%another thing
}

%{sub STRING, I, [,J]}

*%{sub myfile.zip 3 6}*

%{upper:STRING}

%{upper:CamelCase}'

File and path operations¶

%{basename:PATH}

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

%{dirname:PATH}

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

%{exists:PATH}

%{exists:%{builddir}/myflag.txt}

%{suffix:PATH}

%{suffix:myfile.zip}

%{url2path:URL}

%{url2path:http://rpm.org/not/there}

%{uncompress:PATH}

%{uncompress /my/source.tar.gz}

%{xdg:KIND}

%{xdg config}

Environment info¶

%getncpus

%{getncpus:KIND}

%{getncpus proc}

%getconfdir

%{getenv:NAME}

%{getenv:HOME}

%rpmversion

Output¶

%{echo:STRING}

%{echo:Building with foo}

%{warn:STRING}

%{warning:Foo is deprecated}

%{error:STRING}

%{error:Invalid argument}

%verbose

%{verbose:STRING}

%{verbose:-x}

Spec specific macros¶

%{S:NUMBER}

%{P:NUMBER}

Diagnostics¶

%trace

%dump

%__file_name

%__file_lineno

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]