4.2. More on macros

This section covers selected built-in RPM Macros. For an exhaustive list of such macros, see RPM Documentation.

4.2.1. Defining your own macros

The following section describes how to create a custom macro.


  • Include the following line in the RPM SPEC file:

    %global <name>[(opts)] <body>

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. Inclusion of the (opts) field is optional:

  • Simple macros do not contain the (opts) field. In this case, only recursive macro expansion is performed.
  • Parametrized macros contain the (opts) field. The opts string between parentheses is passed to getopt(3) for argc/argv processing at the beginning of a macro invocation.

Older RPM SPEC files use the %define <name> <body> macro pattern instead. The differences between %define and %global macros are as follows:

  • %define has local scope. It applies to a specific part of a SPEC file. The body of a %define macro is expanded when used.
  • %global has global scope. It applies to an entire SPEC file. The body of a %global macro is expanded at definition time.

Macros are evaluated even if they are commented out or the name of the macro is given into the %changelog section of the SPEC file. To comment out a macro, use %%. For example: %%global.

Ressources supplémentaires

4.2.2. Using the %setup macro

This section describes how to build packages with source code tarballs using different variants of the %setup macro. Note that the macro variants can be combined. The rpmbuild output illustrates standard behavior of the %setup macro. At the beginning of each phase, the macro outputs Executing(%…​), as shown in the below example.

Exemple 4.1. Example %setup macro output

Executing(%prep): /bin/sh -e /var/tmp/rpm-tmp.DhddsG

The shell output is set with set -x enabled. To see the content of /var/tmp/rpm-tmp.DhddsG, use the --debug option because rpmbuild deletes temporary files after a successful build. This displays the setup of environment variables followed by for example:

cd '/builddir/build/BUILD'
rm -rf 'cello-1.0'
/usr/bin/gzip -dc '/builddir/build/SOURCES/cello-1.0.tar.gz' | /usr/bin/tar -xof -
if [ $STATUS -ne 0 ]; then
  exit $STATUS
cd 'cello-1.0'
/usr/bin/chmod -Rf a+rX,u+w,g-w,o-w .

The %setup macro:

  • Ensures that we are working in the correct directory.
  • Removes residues of previous builds.
  • Unpacks the source tarball.
  • Sets up some default privileges. Using the %setup -q macro

The -q option limits the verbosity of the %setup macro. Only tar -xof is executed instead of tar -xvvof. Use this option as the first option. Using the %setup -n macro

The -n option is used to specify the name of the directory from expanded tarball.

This is used in cases when the directory from expanded tarball has a different name from what is expected (%{name}-%{version}), which can lead to an error of the %setup macro.

For example, if the package name is cello, but the source code is archived in hello-1.0.tgz and contains the hello/ directory, the SPEC file content needs to be as follows:

Name: cello
Source0: https://example.com/%{name}/release/hello-%{version}.tar.gz
%setup -n hello Using the %setup -c macro

The -c option is used if the source code tarball does not contain any subdirectories and after unpacking, files from an archive fills the current directory.

The -c option then creates the directory and steps into the archive expansion as shown below:

/usr/bin/mkdir -p cello-1.0
cd 'cello-1.0'

The directory is not changed after archive expansion. Using the %setup -D and %setup -T macros

The -D option disables deleting of source code directory, and is particularly useful if the %setup macro is used several times. With the -D option, the following lines are not used:

rm -rf 'cello-1.0'

The -T option disables expansion of the source code tarball by removing the following line from the script:

/usr/bin/gzip -dc '/builddir/build/SOURCES/cello-1.0.tar.gz' | /usr/bin/tar -xvvof - Using the %setup -a and %setup -b macros

The -a and -b options expand specific sources:

The -b option stands for before, and it expands specific sources before entering the working directory. The -a option stands for after, and it expands those sources after entering. Their arguments are source numbers from the SPEC file preamble.

In the following example, the cello-1.0.tar.gz archive contains an empty examples directory. The examples are shipped in a separate examples.tar.gz tarball and they expand into the directory of the same name. In this case, use -a 1, if you want to expand Source1 after entering the working directory:

Source0: https://example.com/%{name}/release/%{name}-%{version}.tar.gz
Source1: examples.tar.gz
%setup -a 1

In the following example, examples are provided in a separate cello-1.0-examples.tar.gz tarball, which expands into cello-1.0/examples. In this case, use -b 1, to expand Source1 before entering the working directory:

Source0: https://example.com/%{name}/release/%{name}-%{version}.tar.gz
Source1: %{name}-%{version}-examples.tar.gz
%setup -b 1

4.2.3. Common RPM macros in the %files section

The following table lists advanced RPM Macros that are needed in the %files section of a SPEC file.

Tableau 4.1. Advanced RPM Macros in the %files section



The macro identifies the file listed as a LICENSE file and it will be installed and labeled as such by RPM. Example: %license LICENSE


The macro identifies a file listed as documentation and it will be installed and labeled as such by RPM. The macro is used for documentation about the packaged software and also for code examples and various accompanying items. In the event code examples are included, care should be taken to remove executable mode from the file. Example: %doc README


The macro ensures that the path is a directory owned by this RPM. This is important so that the RPM file manifest accurately knows what directories to clean up on uninstall. Example: %dir %{_libdir}/%{name}


The macro ensures that the following file is a configuration file and therefore should not be overwritten (or replaced) on a package install or update if the file has been modified from the original installation checksum. If there is a change, the file will be created with .rpmnew appended to the end of the filename upon upgrade or install so that the pre-existing or modified file on the target system is not modified. Example: %config(noreplace) %{_sysconfdir}/%{name}/%{name}.conf

4.2.4. Displaying the built-in macros

Red Hat Enterprise Linux provides multiple built-in RPM macros.


  1. To display all built-in RPM macros, run:

    rpm --showrc

    The output is quite sizeable. To narrow the result, use the command above with the grep command.

  2. To find information about the RPMs macros for your system’s version of RPM, run:

    rpm -ql rpm

    RPM macros are the files titled macros in the output directory structure.

4.2.5. RPM distribution macros

Different distributions provide different sets of recommended RPM macros based on the language implementation of the software being packaged or the specific guidelines of the distribution.

The sets of recommended RPM macros are often provided as RPM packages, ready to be installed with the dnf package manager.

Once installed, the macro files can be found in the /usr/lib/rpm/macros.d/ directory.


  • To display the raw RPM macro definitions, run:

    rpm --showrc

The above output displays the raw RPM macro definitions.

  • To determine what a macro does and how it can be helpful when packaging RPMs, run the rpm --eval command with the name of the macro used as its argument:

    rpm --eval %{_MACRO}

Ressources supplémentaires

  • rpm man page

4.2.6. Creating custom macros

You can override the distribution macros in the ~/.rpmmacros file with your custom macros. Any changes that you make affect every build on your machine.


Defining any new macros in the ~/.rpmmacros file is not recommended. Such macros would not be present on other machines, where users may want to try to rebuild your package.


  • To override a macro, run:

    %_topdir /opt/some/working/directory/rpmbuild

You can create the directory from the example above, including all subdirectories through the rpmdev-setuptree utility. The value of this macro is by default ~/rpmbuild.

%_smp_mflags -l3

The macro above is often used to pass to Makefile, for example make %{?_smp_mflags}, and to set a number of concurrent processes during the build phase. By default, it is set to -jX, where X is a number of cores. If you alter the number of cores, you can speed up or slow down a build of packages.