#846 guidelines/RPMMacros: update for the 21st century
Merged 5 months ago by decathorpe. Opened 6 months ago by decathorpe.

@@ -1,65 +1,138 @@

- == Valid RPM Macros

+ :last-reviewed: 2019-02-14

+ :build-flags: link:https://src.fedoraproject.org/rpms/redhat-rpm-config/blob/master/f/buildflags.md[build flags documentation]

  

- Here are the definitions for some common specfile macros as they are defined on Fedora 13 (rpm-4.8.0-14.fc13). For definitions of more macros, examine the output of "`+rpm --showrc+`". To see the expanded definition of a macro use the command `+rpm --eval "%{macro}"+`. Note that neither command will take into account macros defined inside specfiles, but both will take into account macros defined in your `+~/.rpmmacros+` file and macros defined on the command line.

+ RPM provides a rich set of macros

+ to make package maintenance simpler and consistent across packages.

+ For example, it includes a list of default path definitions

+ which are used by the build system macros,

+ and definitions for RPM package build specific directories.

+ They usually should be used instead of hard-coded directories.

+ It also provides the default set of compiler flags as macros,

+ which should be used when compiling manually and not relying on a build system.

  

- Keep in mind that some of these macros may evaluate differently on older Fedora or EPEL releases.

  

- === Macros mimicking autoconf variables

+ == Getting and setting Macros on the command line

+ 

+ It's possible to let RPM evaluate arbitrary strings containing macros

+ on the command line by running `rpm --eval` on the command line:

  

  ....

- %{_sysconfdir}        /etc

- %{_prefix}            /usr

- %{_exec_prefix}       %{_prefix}

- %{_bindir}            %{_exec_prefix}/bin

- %{_libdir}            %{_exec_prefix}/%{_lib}

- %{_libexecdir}        %{_exec_prefix}/libexec

- %{_sbindir}           %{_exec_prefix}/sbin

- %{_sharedstatedir}    /var/lib

- %{_datarootdir}       %{_prefix}/share

- %{_datadir}           %{_datarootdir}

- %{_includedir}        %{_prefix}/include

- %{_infodir}           /usr/share/info

- %{_mandir}            /usr/share/man

- %{_localstatedir}     /var

- %{_initddir}          %{_sysconfdir}/rc.d/init.d

+ $ rpm --eval "some text printed on %{_arch}"

+ some text printed on x86_64

  ....

  

- === Other macros and variables for paths

- 

- These macros should be used for paths that are not covered by the macros mimicking autoconf variables. The `+%{buildroot}+` macro or the `+$RPM_BUILD_ROOT+` variable is the directory that should be assumed to be the root file system when installing files. It is used as the value for the `+DESTDIR+` variable.

+ Additionally, values for macros can be temporarily provided (and overridden)

+ by providing command line options to `rpm` and `rpmbuild`:

  

  ....

- %{_var}               /var

- %{_tmppath}           %{_var}/tmp

- %{_usr}               /usr

- %{_usrsrc}            %{_usr}/src

- %{_lib}               lib (lib64 on 64bit multilib systems)

- %{_docdir}            %{_datadir}/doc

- %{buildroot}          %{_buildrootdir}/%{name}-%{version}-%{release}.%{_arch}

- $RPM_BUILD_ROOT       %{buildroot}

+ $ rpm --define "test Hello, World!" --eval "%{test}"

+ Hello, World!

  ....

  

- [#build-flags-macros-and-variables]

- === Build flags macros and variables

  

- These macros should be used as flags for the compiler or linker. Note that the values for the macros below reflect the settings on Fedora 13 (i686) with redhat-rpm-config installed.

+ == Macros for paths set and used by build systems

+ 

+ The macros for build system invocations

+ (for example, `%configure`, `%cmake`, or `%meson`)

+ use the values defined by RPM to set installation paths for packages.

+ So, it's usually preferable to not hard-code these paths in spec files either,

+ but use the same macros for consistency.

+ 

+ The values for these macros can be inspected

+ by looking at `/usr/lib/rpm/platform/*/macros` for the respective platform.

+ 

+ The following table lists macros which are widely used in fedora `.spec` files.

+ 

+ [cols="20%m,30%m,50%",options="header"]

+ |=================================

+ | macro                | definition                  | comment

+ | +%{_sysconfdir}+     | /etc                        |

+ | +%{_prefix}+         | /usr                        | can be defined to `/app` for flatpak builds

+ | +%{_exec_prefix}+    | +%{_prefix}+                | default: `/usr`

+ | +%{_includedir}+     | +%{_prefix}+/include        | default: `/usr/include`

+ | +%{_bindir}+         | +%{_exec_prefix}+/bin       | default: `/usr/bin`

+ | +%{_libdir}+         | +%{_exec_prefix}/%{_lib}+   | default: `+/usr/%{_lib}+`

+ | +%{_libexecdir}+     | +%{_exec_prefix}+/libexec   | default: `/usr/libexec`

+ | +%{_sbindir}+        | +%{_exec_prefix}+/sbin      | default: `/usr/sbin`

+ | +%{_datadir}+        | +%{_datarootdir}+           | default: `/usr/share`

+ | +%{_infodir}+        | +%{_datarootdir}+/info      | default: `/usr/share/info`

+ | +%{_mandir}+         | +%{_datarootdir}+/man       | default: `/usr/share/man`

+ | +%{_docdir}+         | +%{_datadir}+/doc           | default: `/usr/share/doc`

+ | +%{_rundir}+         | /run                        |

+ | +%{_localstatedir}+  | /var                        |

+ | +%{_sharedstatedir}+ | /var/lib                    |

+ | +%{_lib}+            | lib64                       | `lib` on 32bit platforms

+ |=================================

+ 

+ Some seldomly used macros are listed below for completeness.

+ Old `.spec` files might still use them,

+ and there might be cases where they are still needed.

+ 

+ [cols="20%m,30%m,50%",options="header"]

+ |=================================

+ | macro                | definition                   | comment

+ | +%{_datarootdir}+    | +%{_prefix}/share+           | default: `/usr/share`

+ | +%{_var}+            | /var                         |

+ | +%{_tmppath}+        | +%{_var}/tmp+                | default: `/var/tmp`

+ | +%{_usr}+            | /usr                         |

+ | +%{_usrsrc}+         | +%{_usr}/src+                | default: `/usr/src`

+ | +%{_initddir}+       | +%{_sysconfdir}/rc.d/init.d+ | default: `/etc/rc.d/init.d`

+ | +%{_initrddir}+      | +%{_initddir}+               | old misspelling, provided for compatiblity

+ |=================================

+ 

+ 

+ == Macros set for the RPM (and SRPM) build process

+ 

+ RPM also exposes the locations of several directories

+ that are relevant to the package build process via macros.

+ 

+ The only macro that's widely used in `.spec` files is `+%{buildroot}+`,

+ which points to the root of the installation target directory.

+ It is used for setting `DESTDIR` in the package's `%install` step.

+ 

+ The other macros are usually only used outside `.spec` files.

+ For example, they are set by `fedpkg` to override the default directories.

+ 

+ [cols="20%m,60%m,20%",options="header"]

+ |=================================

+ | macro                | definition                   | comment

+ | +%{buildroot}+       | +%{_buildrootdir}/%{name}-%{version}-%{release}.%{_arch}+ | same as `$BUILDROOT`

+ | +%{_topdir}+         | +%{getenv:HOME}/rpmbuild+    |

+ | +%{_builddir}+       | +%{_topdir}/BUILD+           |

+ | +%{_rpmdir}+         | +%{_topdir}/RPMS+            |

+ | +%{_sourcedir}+      | +%{_topdir}/SOURCES+         |

+ | +%{_specdir}+        | +%{_topdir}/SPECS+           |

+ | +%{_srcrpmdir}+      | +%{_topdir}/SRPMS+           |

+ | +%{_buildrootdir}+   | +%{_topdir}/BUILDROOT+       |

+ |=================================

+ 

+ 

+ == Macros providing compiler and linker flags

+ 

+ The default build flags for binaries on fedora are also available via macros.

+ They are used by the build system macros to setup the build environment,

+ so it is usually not necessary to use them directly --

+ except, for example, when doing bare bones compilation with `gcc` directly.

+ 

+ The set of flags listed below reflects the current state of fedora 28

+ on a `x86_64` machine, as defined in the file `/usr/lib/rpm/redhat/macros`.

+ 

+ The `+%{optflags}+` macro contains flags that determine `CFLAGS`, `CXXFLAGS`,

+ `FFLAGS`, etc. -- the `+%{__global_cflags}+` macro evaluates to the same string.

+ 

+ The current definitions of these values

+ can be found in the `redhat-rpm-macros` package, in the {build-flags}.

  

  ....

- %{__global_cflags}   -O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions -fstack-protector --param=ssp-buffer-size=4

- %{optflags}          %{__global_cflags} -m32 -march=i686 -mtune=atom -fasynchronous-unwind-tables

- $RPM_OPT_FLAGS       %{optflags}

+ $ rpm --eval "%{optflags}"

+ -O2 -g -pipe -Wall -Werror=format-security -Wp,-D_FORTIFY_SOURCE=2 -Wp,-D_GLIBCXX_ASSERTIONS -fexceptions -fstack-protector-strong -grecord-gcc-switches -specs=/usr/lib/rpm/redhat/redhat-hardened-cc1 -specs=/usr/lib/rpm/redhat/redhat-annobin-cc1 -m64 -mtune=generic -fasynchronous-unwind-tables -fstack-clash-protection -fcf-protection

  ....

  

- === RPM directory macros

- 

- The macros are usually used with `+rpmbuild --define+` to specify which directories rpmbuild should use, it is unusual to use them within SPEC files.

+ The value of the `LDFLAGS` environment variable set by build systems

+ is determined by the `+%{build_flags}+` macro:

  

  ....

- %{_topdir}            %{getenv:HOME}/rpmbuild

- %{_builddir}          %{_topdir}/BUILD

- %{_rpmdir}            %{_topdir}/RPMS

- %{_sourcedir}         %{_topdir}/SOURCES

- %{_specdir}           %{_topdir}/SPECS

- %{_srcrpmdir}         %{_topdir}/SRPMS

- %{_buildrootdir}      %{_topdir}/BUILDROOT

+ $ rpm -E "%{build_ldflags}"

+ -Wl,-z,relro  -Wl,-z,now -specs=/usr/lib/rpm/redhat/redhat-hardened-ld

  ....

+ 

This PR contains a rewrite of the RPMMacros page with more useful information, and updates the macro definitions to the values as they are defined on fedora 28.

See: https://pagure.io/packaging-committee/issue/693

This is actually awesome. I already use this PR as a reference and would like to see it merged.

The Macros providing compiler and linker flags section might want to link to the documentation at https://src.fedoraproject.org/rpms/redhat-rpm-config/blob/master/f/buildflags.md

To be honest, we should probably just pull that buildflags document into the guidelines.

This is actually awesome. I already use this PR as a reference and would like to see it merged.
The Macros providing compiler and linker flags section might want to link to the documentation at https://src.fedoraproject.org/rpms/redhat-rpm-config/blob/master/f/buildflags.md

Weird, I thought I mentioned this link, I must've forgotten, after all. I'll add it.

1 new commit added

  • RPMMacros: add link to build flags documentation from redhat-rpm-macros
6 months ago

1 new commit added

  • RPMMacros: add :last-reviewed: attribute
5 months ago

Commit d15673e fixes this pull-request

Pull-Request has been merged by decathorpe

5 months ago

Pull-Request has been merged by decathorpe

5 months ago
Metadata