General Exception Policy¶

As these guidelines can never cover all possible contingencies, there will always be packages which need exceptions. It is the packager’s responsibility to follow these guidelines as closely as is feasible and to clearly document, as comments in the package specfile, instances where they cannot be followed.

If, in a guideline, the language “should” or “is suggested” is used and it is not feasible for the package to conform to that guideline, the packager may deviate from the it. The nature of the deviation and the reasoning behind it MUST be documented in the specfile.

Where the language “must”, “is required to” or “needs to” is used, the packager may deviate from the guideline only with approval from the packaging committee. Please follow the procedure at ​the Packaging Committee page for making these requests.

Naming¶

You should go through the Packaging:NamingGuidelines to ensure that your package is named appropriately.

Version and Release¶

Documentation covering the proper way to use the Version and Release fields can be found here: Packaging:Versioning

Legal¶

There are various legal concerns to consider when packaging for Fedora.

No External Kernel Modules¶

At one point (pre Fedora 8), packages containing “addon” kernel modules were permitted. This is no longer the case. Fedora strongly encourages kernel module packagers to submit their code into the upstream kernel tree.

The reference documentation on how to package kernel modules in the “kmod” style has been preserved here .

No inclusion of pre-built binaries or libraries¶

All program binaries and program libraries included in Fedora packages must be built from the source code that is included in the source package. This is a requirement for the following reasons:

• Security: Pre-packaged program binaries and program libraries not built from the source code could contain parts that are malicious, dangerous, or just broken. Also, these are functionally impossible to patch.
• Compiler Flags: Pre-packaged program binaries and program libraries not built from the source code were probably not compiled with standard Fedora compiler flags for security and optimization.

Content binaries (such as .pdf, .png, .ps files) are not required to be rebuilt from the source code.

If you are in doubt as to whether something is considered a program binary or a program library, here is some helpful criteria:

• Is it executable? If so, it is probably a program binary.
• Does it contain a .so, ,so.#, or .so.#.#.# extension? If so, it is probably a program library.
• If in doubt, ask your reviewer. If the reviewer is not sure, they should ask the Fedora Packaging Committee.

Packages which require non-open source components to build are also not permitted (e.g. proprietary compiler required).

When you encounter prebuilt binaries in a package you MUST:

• Remove all pre-built program binaries and program libraries in %prep prior to the building of the package. Examples include, but are not limited to, *.class, *.dll, *.DS_Store, *.exe, *.jar, *.o, *.pyc, *.pyo, *.egg, *.so, *.swf files.
• Ask upstream to remove the binaries in their next release.

Use of pregenerated code¶

Often a package will contain code which was itself generated by other code. This often takes the form of configure files or parsing code generated by bison/yacc or lex/flex.

It is required that the original source files from which the code was generated be included in the srpm. Generally these files are part of the source archive supplied by upstream, but it may be necessary to fetch those files from an upstream source repository and include them in the srpm as separate Source: entries.

It is preferred, but not required, that the tools used to generate such code be free software and included in Fedora.

It is suggested, but not required, that such code be regenerated as part of the build process. The means for doing this are entirely specific to the individual package being built, but it may happen automatically if the necessary dependencies are present at build time.

Libraries and Applications¶

Many language- or domain-specific guidelines refer to “libraries”, “modules”, “plug-ins” or other terms specific to the language or domain. This is specifically important to package naming. Some applications may include libraries, and some libraries may include applications, so the distinction is not always clear.

Spec Files¶

The spec file (“spec”) is a fundamental element in the packaging workflow. Any change that is made to the package will include a change to the spec. Because packages in Fedora are maintained by a community of packagers as well as automated tooling, it is important for the specs to follow certain conventions. The bulk of these packaging guidelines involves what goes into a spec, but here are a few general items.

Architecture Support¶

All Fedora packages must successfully compile and build into binary rpms on at least one supported primary architecture, except where the package is useful only on a secondary architecture (such as an architecture-specific boot utility, microcode loader, or hardware configuration tool). Fedora packagers should make every effort to support all primary architectures.

Content, code which does not need to compile or build, and architecture independent code (noarch) are notable exceptions.

BuildArch: noarch
# List the arches that the dependent package builds on below
ExclusiveArch: %{ix86} %{arm} x86_64 noarch

# Cannot build as noarch until foo-lang is ported to arm.
# Comment out BuildArch: noarch for now.
# BuildArch: noarch
ExclusiveArch: %{ix86} x86_64

# Incorrect
%ifarch ppc64
Patch0: build-fix-for-ppc64.patch
%endif

%prep
[...]
%ifarch ppc64
%patch0 -p1
%endif

Filesystem Layout¶

Fedora follows the Filesystem Hierarchy Standard with regards to filesystem layout, with exceptions noted below. The FHS defines where files should be placed on the system.

%files
/bin/sh

Provides: %{_sbindir}/ifconfig
[...]
%files
/sbin/ifconfig

$ rpm -ql $(rpm -qf /usr/sbin/ifconfig)|grep sbin/ifconfig
/sbin/ifconfig

Use rpmlint¶

Run rpmlint on binary and source rpms to examine them for common errors, and fix them (unless rpmlint is wrong, which can happen, too). If you find rpmlint’s output cryptic, the -i switch to it can be used to get more verbose descriptions of most errors and warnings. Note that rpmlint will perform additional checks if given the name of an installed package. For example, dnf install foo-1.0-1.f20.x86_64.rpm; rpmlint foo will perform a set of tests on the foo package that rpmlint foo-1.0-1.f20.x86_64.rpm cannot. A community-maintained page on rpmlint issues can be found here.

Tags and Sections¶

• The Copyright:, Packager:, Vendor: and PreReq: tags MUST NOT be used.
• The BuildRoot: tag, Group: tag, and %clean section SHOULD NOT be used.
• The contents of the buildroot SHOULD NOT be removed in the first line of %install.
• The Summary: tag value SHOULD NOT end in a period.
• The Source: tags document where to find the upstream sources for the package. In most cases this SHOULD be a complete URL to the upstream tarball. For special cases, please see the SourceURL Guidelines.

Package Dependencies¶

All package dependencies (build-time or runtime, regular, weak or otherwise) MUST ALWAYS be satisfiable within the official Fedora repositories.

RPM can automatically determine dependencies for most compiled libraries and for some scripting languages such as Perl. Automatically determined dependencies MUST NOT be duplicated by manual dependencies.

Build dependencies, however, cannot be automatically determined and MUST be explicitly listed. Refer to the BuildRequires section.

Versioned dependencies (build-time or runtime) SHOULD ONLY be used when actually necessary to guarantee that the proper version of a package is present. If a versioned dependency would be satisfied by a version present in three previous Fedora releases then the then a versioned dependency is not needed and a regular unversioned dependency SHOULD be used instead.

A versioned dependency on a package with a defined Epoch MUST be included in that dependency. Otherwise the dependency will not function as expected.

Requires: foo

Requires: foo%{?_isa}

$ gtk-config --cflags
-I/usr/include/gtk-1.2 -I/usr/include/glib-1.2 -I/usr/lib/glib/include -I/usr/X11R6/include
$ gtk-config --libs
-L/usr/lib -L/usr/X11R6/lib -lgtk -lgdk -rdynamic -lgmodule -lglib -ldl -lXi -lXext -lX11 -lm

# The automatic dependency on libfubar.so.1 is insufficient,
# as we strictly need at least the release that fixes two segfaults.
Requires: libfubar%{?_isa} >= 0:1.2.3-7

Build-Time Dependencies (BuildRequires)¶

It is important that your package list all necessary build dependencies using the BuildRequires: tag. You may assume that enough of an environment exists for RPM to function, to build packages and execute basic shell scripts, but you should not assume any other packages are present as RPM dependencies and anything brought into the buildroot by the build system may change over time.

# Example of what *not* to do
BuildRequires:  python%{?_isa} >= 2.7

python(x86-32) >= 2.7
# or
python(x86-64) >= 2.7

Conditional build-time dependencies¶

If the spec file contains conditional dependencies selected based on presence of optional --with(out) foo arguments to rpmbuild, build the source RPM to be submitted with the default options, ie. so that none of these arguments are present in the rpmbuild command line. The reason is that those requirements get “serialized” into the resulting source RPM, ie. the conditionals no longer apply.

Summary and description¶

The summary should be a short and concise description of the package. The description expands upon this. Do not include installation instructions in the description; it is not a manual. If the package requires some manual configuration or there are other important instructions to the user, refer the user to the documentation in the package. Add a README.Fedora, or similar, if you feel this is necessary. Also, please make sure that there are no lines in the description longer than 80 characters.

Please put personal preferences aside and use American English spelling in the summary and description. Packages can contain additional translated summary/description for supported Non-English languages, if available.

Documentation¶

Any relevant documentation included in the source distribution should be included in the package in the proper documentation directory. Irrelevant documentation includes build instructions, the omnipresent INSTALL file containing generic build instructions, for example, and documentation for non-Linux systems, e.g. README.MSDOS. Also pay attention about which subpackage you include documentation in. For example API documentation belongs in the -devel subpackage, not the main one. Or if there’s a lot of documentation, consider putting it into a subpackage. In this case, it is recommended to use *-doc as the subpackage name.

Marking a relative path with %doc in the %files section will cause RPM to copy the referenced file or directory from %_builddir to the proper location for documentation. Files can also be placed in %_pkgdocdir, and the build scripts of the software being packaged may do this automatically when called in %install. However, mixing these methods is problematic and may result in duplicated or conflicting files, so use of %doc with relative paths and installation of files directly into %_pkgdocdir in the same source package is forbidden.

Files marked as documentation must not cause the package to pull in more dependencies than it would without the documentation. One simple way to ensure this in most cases is to remove all executable permissions from files in %_pkgdocdir.

Files located in %_pkgdocdir must not affect the runtime of the packaged software. The software must function properly and with unchanged functionality if those files are modified, removed or not installed at all.

Although license files are documentation, they are treated specially (including using a different tag. Please see Packaging:LicensingGuidelines for how to handle them.

Changelogs¶

Every time you make changes, that is, whenever you increment the E-V-R of a package, add a changelog entry. This is important not only to have an idea about the history of a package, but also to enable users, fellow packagers, and QA people to easily spot the changes that you make.

If a particular change is related to a Bugzilla bug, include the bug ID in the changelog entry for easy reference, e.g.

* Wed Jun 14 2003 Joe Packager <joe at gmail.com> - 1.0-2
- Added README file (#42).

You must use one of the following formats:

* Fri Jun 23 2006 Jesse Keating <jkeating@redhat.com> - 0.6-4
- And fix the link syntax.

* Fri Jun 23 2006 Jesse Keating <jkeating@redhat.com> 0.6-4
- And fix the link syntax.

* Fri Jun 23 2006 Jesse Keating <jkeating@redhat.com>
- 0.6-4
- And fix the link syntax.

Changelog entries should provide a brief summary of the changes done to the package between releases, including noting updating to a new version, adding a patch, fixing other spec sections, note bugs fixed, and CVE’s if any. They must never simply contain an entire copy of the source CHANGELOG entries. The intent is to give the user a hint as to what changed in a package update without overwhelming them with the technical details. Links to upstream changelogs can be entered for those who want additional information. If you wish to “scramble” or “obfuscate” your email address in the changelog, you may do so, provided that it is still understandable by humans.

* Nov 12 2010 Toshio Kuratomi <toshio_fedoraproject.org> - 1.0-1
- Fix spelling errors in package description

* Nov 13 2010 Toshio Kuratomi <toshio_fedoraproject.org> - 1.0-1
- Fix spelling errors in package description
- Add a patch to fix compilation problems on F15

* Nov 12 2010 Toshio Kuratomi <toshio_fedoraproject.org> - 1.0-1
- Fix spelling errors in package description

* Nov 13 2010 Toshio Kuratomi <toshio_fedoraproject.org> - 1.0-1
- Add a patch to fix compilation problems on F15

* Nov 12 2010 Toshio Kuratomi <toshio_fedoraproject.org> - 1.0-1
- Fix spelling errors in package description

Manpages¶

As man pages are the traditional method of getting help on a Unix system, packages should contain them for all executables. If some man pages are absent, packagers should work with upstream to add them. It is also occasionally possible to find pages created by other distributions, or to use the output of the help2man program; those are often useful as a starting point. When installing man pages, note that they should be installed uncompressed as the build system will compress them as needed. The compression method may change, so it is important to reference the pages in the %files section with a pattern that takes this into account:

%files
%{_mandir}/man1/foo.1*

Compiler¶

Fedora uses gcc as the compiler (for all languages that gcc supports). Packages may only build with an alternative compiler to gcc if upstream does not support gcc.

Compiler flags¶

Compilers used to build packages must honor the applicable compiler flags set in the system rpm configuration. Honoring means that the contents of that variable is used as the basis of the flags actually used by the compiler during the package build.

For C, C++, and Fortran code, the %{optflags} macro contains these flags. Overriding these flags for performance optimizations (for instance, -O3 instead of -O2) is generally discouraged. If you can present benchmarks that show a significant speedup for this particular code, this could be revisited on a case-by-case basis. Adding to and overriding or filtering parts of these flags is permitted if there’s a good reason to do so; the rationale for doing so must be documented in the specfile.

There are certain, security related flags that are commonly allowed. These flags may degrade performance slightly but the increased security can be worthwhile for some programs.

%global _hardened_build 1

Debuginfo packages¶

Packages should produce useful -debuginfo packages, or explicitly disable them when it is not possible to generate a useful one but rpmbuild would do it anyway. Whenever a -debuginfo package is explicitly disabled, an explanation why it was done is required in the specfile. Debuginfo packages are discussed in more detail in a separate document, Packaging:Debuginfo .

Devel Packages¶

Fedora packages must be designed with a logical separation of files. Specifically, -devel packages must be used to contain files which are intended solely for development or needed only at build-time. This is done to minimize the install footprint for users. There are some types of files which almost always belong in a -devel package:

• Header files (foo.h), usually found in /usr/include
• Static library files when the package does not provide any matching shared library files. See Packaging:Guidelines#Packaging_Static_Libraries for more information about this scenario.
• Unversioned shared system library files, when a matching versioned shared system library file is also present. For example, if your package contains:

/usr/lib/libfoo.so.3.0.0
/usr/lib/libfoo.so.3
/usr/lib/libfoo.so

The versioned shared library files (/usr/lib/libfoo.so.3.2.0 and /usr/lib/libfoo.so.3) are necessary for users to run programs linked against libfoo, so they belong in the base package. The other, unversioned, shared library file (/usr/lib/libfoo.so) is only used to actually link libfoo to code being compiled, and is not necessary to be installed on a users system. This means that it belongs in a -devel package. Please note that in most cases, only the fully versioned shared library file (/usr/lib/libfoo.so.3.2.0) is an actual file, all of the other files are symbolic links to it. When a shared library file is only provided in an unversioned format, the packager should ask upstream to consider providing a properly versioned library file. However, in such cases, if the shared library file is necessary for users to run programs linked against it, it must go into the base package. If upstream versions the shared library file at a future point, packagers must be careful to move to the versioned layout described above.

As an additional complication, some software generates unversioned shared objects which are not intended to be used as system libraries. These files are usually plugins or modular functionality specific to an application, and are not located in the ld library paths or cache. This means that they are not located directly in /usr/lib or /usr/lib64, or in a directory listed as a library path in /etc/ld.so.conf (or an /etc/ld.so.conf.d/config file). Usually, these unversioned shared objects can be found in a dedicated subdirectory under /usr/lib or /usr/lib64 (e.g. /usr/lib/purple-2/ is the plugin directory used for libpurple applications). In these cases, the unversioned shared objects do not need to be placed in a -devel package.

There are some notable exceptions to this packaging model, specifically:

• compilers often include development files in the main package because compilers are themselves only used for software development, thus, a split package model does not make any sense.

When in doubt as to whether a file belongs in the base package or in -devel, packagers should consider whether the file is necessary to be present for a user to use or execute the functionality in the base package properly, or if it is only necessary for development. If it is only necessary for development, it must go into a -devel package.

As with all Fedora Packaging Guidelines, it is recognized that there are unique situations that fall outside of the boundaries of this model. Should you come across such a case, please open a ticket with the Fedora Packaging Committee and explain it to us so that we can extend the Guidelines to address it.

Requiring Base Package¶

Subpackages are often extensions for their base package and in that case they should require their base package. It is almost always better to over specify the version, so it is best practice to just use a fully versioned dependency: Requires: %{name}%{?_isa} = %{version}-%{release}. Devel packages are an example of a package that must require their base packages using a fully versioned dependency. -libs subpackages which only contain shared libraries do not normally need to explicitly depend on %{name}%{?_isa} = %{version}-%{release}, as they usually do not need the base package to be functional libraries.

If you end up in a situation where the main package depends on the subpackage and the subpackage on the main package you should think carefully about why you don’t have everything in the main package.

When a subpackage requires the base package, it must do so using a fully versioned arch-specific (for non-noarch packages) dependency:

Requires: %{name}%{?_isa} = %{version}-%{release}

Shared Libraries¶

Whenever possible (and feasible), Fedora Packages containing libraries should build them as shared libraries. In addition, every binary RPM package which contains shared library files (not just symlinks) in any of the dynamic linker’s default paths, must call ldconfig in %post and %postun. If the package has multiple subpackages with libraries, each subpackage should also have a %post/%postun section that calls /sbin/ldconfig. An example of the correct syntax for this is:

%post -p /sbin/ldconfig

%postun -p /sbin/ldconfig

Note that this specific syntax only works if /sbin/ldconfig is the only call in %post and %postun. If you have additional commands to run during the scriptlet, call /sbin/ldconfig at the beginning of the scriptlet, like this:

%post
/sbin/ldconfig
/usr/bin/foo --add

%postun
/sbin/ldconfig
/usr/bin/foo --remove

libfoobar.so.0.n

$ gcc $CFLAGS -Wl,-soname,libfoo.so.0.n -o libfoo.so.0.n

$ objdump -p /path/to/libfoo.so.0.n | grep 'SONAME'

Packaging Static Libraries¶

Packages including libraries SHOULD exclude static libs as far as possible (eg by configuring with –disable-static). Applications linking against libraries SHOULD link against shared libraries not static versions.

Libtool archives, foo.la files, SHOULD NOT be included. Packages using libtool will install these by default even if you configure with –disable-static, so they may need to be removed before packaging. Due to bugs in older versions of libtool or bugs in programs that use it, there are times when it is not always possible to remove *.la files without modifying the program. In most cases it is fairly easy to work with upstream to fix these issues. Note that if you are updating a library in a stable release (not devel) and the package already contains *.la files, removing the *.la files SHOULD be treated as an API/ABI change – ie: Removing them changes the interface that the library gives to the rest of the world thus MUST follow Fedora policies for potentially destabilizing updates.

%package devel
Provides: foo-static = %{version}-%{release}

%package devel
Provides: foo-static = %{version}-%{release}

Bundling and Duplication of system libraries¶

Fedora packages SHOULD make every effort to avoid having multiple, separate, upstream projects bundled together in a single package.

All packages whose upstreams allow them to be built against system libraries MUST be built against system libraries.

All packages whose upstreams have no mechanism to build against system libraries MAY opt to carry bundled libraries, but if they do, they MUST include an indication of what they bundle. This provides a mechanism for locating libraries with bundled code which can, for example, assist in locating packages which may have particular security vulnerabilities.

To indicate an instance of bundling, first determine the name and version of the bundled library:

• If the bundled package also exists separately in the distribution, use the name of that package. Otherwise consult the naming guidelines to determine an appropriate name for the library as if it were entering the distribution as a separate package.
• Use the versioning guidelines to determine an appropriate version for the library, if possible. If the library has been forked from an upstream, use the upstream version that was most recently merged in or rebased onto, or the version the original library carried at the time of the fork.

Then at an appropriate place in your spec, add Provides: bundled() = ``\  where and are the name and version you determined above. If it was not possible to determine a version, use ``Provides: bundled() instead.

In addition to indicating bundling in this manner, packages whose upstreams have no mechanism to build against system libraries must be contacted publicly about a path to supporting system libraries. If upstream refuses, this must be recorded in the spec file, either in comments placed adjacent to the Provides: above, or in an additional file checked into the SCM and referenced by a comment placed adjacent to the Provides: above.

Beware of Rpath¶

Sometimes, code will hardcode specific library paths when linking binaries (using the -rpath or -R flag). This is commonly referred to as an rpath. Normally, the dynamic linker and loader (ld.so) resolve the executable’s dependencies on shared libraries and load what is required. However, when -rpath or -R is used, the location information is then hardcoded into the binary and is examined by ld.so in the beginning of the execution. Since the Linux dynamic linker is usually smarter than a hardcoded path, we usually do not permit the use of rpath in Fedora.

There is a tool called check-rpaths which is included in the rpmdevtools package. It is a good idea to add it to the ``%__arch_install_post`` macro in your ``~/.rpmmacros`` config file:

%__arch_install_post            \
/usr/lib/rpm/check-rpaths     \
/usr/lib/rpm/check-buildroot

When check-rpaths is run, you might see output like this:

ERROR   0001: file '/usr/bin/xapian-tcpsrv' contains a standard rpath '/usr/lib64' in [/usr/lib64]

Any rpath flagged by check-rpaths MUST be removed.

# Internal libraries for myapp are present in:
%{_libdir}/myapp/
%{_libdir}/myapp/libmyapp.so.0.3.4
%{_libdir}/myapp/libmyapp.so

# myapp has an rpath to %{_libdir}/myapp/
readelf -d /usr/bin/myapp | grep RPATH
 0x0000000f (RPATH)                      Library rpath: [/usr/lib/myapp]

/usr/lib/foo

%configure
sed -i 's|^hardcode_libdir_flag_spec=.*|hardcode_libdir_flag_spec=""|g' libtool
sed -i 's|^runpath_var=LD_RUN_PATH|runpath_var=DIE_RPATH_DIE|g' libtool

chrpath --delete $RPM_BUILD_ROOT%{_bindir}/xapian-tcpsrv

Configuration files¶

Configuration files must be marked as such in packages.

As a rule of thumb, use %config(noreplace) instead of plain %config unless your best, educated guess is that doing so will break things. In other words, think hard before overwriting local changes in configuration files on package upgrades. An example case when /not/ to use noreplace is when a package’s configuration file changes so that the new package revision wouldn’t work with the config file from the previous package revision. Whenever plain %config is used, add a brief comment to the specfile explaining why.

Don’t use %config or %config(noreplace) under /usr. /usr is deemed to not contain configuration files in Fedora.

Per-product Configuration¶

In the Fedora.next world, we will have a set of curated Fedora Products as well as the availability of classic Fedora. Historically, we have maintained a single set of configuration defaults for all Fedora installs but different target use-cases have different needs. Please see the Per-Product Configuration Guidelines for instructions on how to create packages that need to behave differently between Fedora.next Products.

Initscripts¶

SystemV-style initscripts are forbidden in Fedora. Systemd units must be used instead.

Systemd units¶

Detailed guidelines for packaging systemd units and systemd-managed services are here.

Desktop files¶

If a package contains a GUI application, then it needs to also include a properly installed .desktop file. For the purposes of these guidelines, a GUI application is defined as any application which draws an X window and runs from within that window. Installed .desktop files MUST follow the desktop-entry-spec , paying particular attention to validating correct usage of Name, GenericName, Categories , StartupNotify entries.

[Desktop Entry]
Name=Comical
GenericName=Comic Archive Reader
Comment=Open .cbr & .cbz files
Exec=comical
Icon=comical
Terminal=false
Type=Application
Categories=Graphics;

desktop-file-install                                    \
--dir=${RPM_BUILD_ROOT}%{_datadir}/applications         \
%{SOURCE3}

desktop-file-install                                    \
--add-category="AudioVideo"                             \
--delete-original                                       \
--dir=%{buildroot}%{_datadir}/applications              \
%{buildroot}/%{_datadir}/applications/foo.desktop

desktop-file-validate %{buildroot}/%{_datadir}/applications/foo.desktop

AppData files¶

Packages containing graphical applications should include AppData files. See Fedora Packaging Guidelines for AppData Files for the relevant guidelines.

Macros¶

Packagers are strongly encouraged to use macros instead of hard-coded directory names (see Packaging:RPMMacros ). However, in situations where the macro is longer than the path it represents, or situations where the packager feels it is cleaner to use the actual path, the packager is permitted to use the actual path instead of the macro. There are several caveats to this approach:

• The package must be consistent. For any given path, within the same spec, use either a hard-coded path or a macro, not a combination of the two.
• %{_libdir} must always be used for binary libraries due to multi-lib, you may not substitute a hard-coded path.

Macro forms of system executables SHOULD NOT be used except when there is a need to allow the location of those executables to be configurable. For example, rm should be used in preference to %{__rm}, but %{__python} is acceptable.

Having macros in a Source: or Patch: line is a matter of style. Some people enjoy the ready readability of a source line without macros. Others prefer the ease of updating for new versions when macros are used. In all cases, remember to be consistent in your spec file and verify that the URLs you list are valid. spectool (from the rpmdevtools package) can aid you in checking that whether the URL contains macros or not.

If you need to determine the actual string when it contains macros, you can use rpm. For example, to determine the actual Source: value, you can run:

rpm -q --specfile foo.spec --qf "$(grep -i ^Source foo.spec)\n"

mock --init
mock --copyin [SRPM] /
mock --shell bash
rpm -ivh [SRPM]
cd /builddir/build/SPECS
rpmbuild -bs --nodeps [SRPM]
rpm -qpiv /builddir/build/SRPMS/[SRPM]

# define macrosdir to the old location for EPEL 5 and 6.  Use the new location everywhere else
%global macrosdir %(d=%{_rpmconfigdir}/macros.d; [ -d $d ] || d=%{_sysconfdir}/rpm; echo $d)
[..]
SOURCE1: macros.perl
[..]
%install
cp %{SOURCE1} %{buildroot}%{macrosdir}
[..]
%files -n devel
%{macrosdir}/macros.perl

Scripting inside of spec files¶

Sometimes it is necessary to write a short script (perhaps a one-liner) that is executed in the %prep, %build, or %install sections of a spec file to get some information about the build environment. In order to simplify the dependency graph, spec files should only use the following languages for this purpose:

Additionally, if your package cannot build without a specific scripting language (such as Ruby, or Tcl), and therefore already has a BuildRequires on that language, it may also be called from the spec file.

Note: If you call perl or python in your spec file (and it is not already a BuildRequires for the package), you need to explicitly add a BuildRequires for perl or python.

%global preferred over %define¶

Use %global instead of %define, unless you really need only locally defined submacros within other macro definitions (a very rare case).

Rationale: The two macro defining statements behave the same when they are a the top level of rpm’s nesting level.

But when they are used in nested macro expansions (like in %{!?foo: ... } constructs, %define theoretically only lasts until the end brace (local scope), while %global definitions have global scope.

Note that %define and %global differ in more ways than just scope: the body of a %define’d macro is lazily expanded (ie when used), but the body of %global is expanded at definition time. It’s possible to use %%-escaping to force lazy expansion of %global.

Handling Locale Files¶

Translation files may be handled by different programs for different frameworks. Make sure you add BuildRequires: for the correct package or else your package could fail to generate translation files in the buildroot.

If the package uses gettext for translations, add

BuildRequires: gettext

For Qt-based packages that use the Linguist tool chain, for the localization utilities add

BuildRequires: qt-devel

If you have few enough locale files that they can all go into one package, you can use the %find_lang macro. (If you need to split your package into separate language packs, please see the langpack guidelines.) This macro will locate all of the them belonging to your package (by name), and put this list in a file. You can then use that file to include all of the locales. %find_lang should be run in the %install section of your spec file, after all of the files have been installed into the buildroot. The correct syntax for %find_lang is usually:

%find_lang %{name}

In some cases, the application may use a different “name” for its locales. You may have to look at the locale files and see what they are named. If they are named myapp.mo, then you will need to pass myapp to %find_lang instead of %{name}. After %find_lang is run, it will generate a file in the active directory (by default, the top level of the source dir). This file will be named based on what you passed as the option to the %find_lang macro. Usually, it will be named %{name}.lang. You should then use this file in the %files list to include the locales detected by %find_lang. To do this, you should include it with the -f parameter to %files.

%files -f %{name}.lang
%{_bindir}/foobar
...

Note that %find_lang by default searches for gettext locales, but it can also handle Qt translations, localised manpages and help files.

To process GNOME help files put into /usr/share/gnome/help/ use

%find_lang %{name} --with-gnome

To process KDE help files put into /usr/share/doc/HTML/ use

%find_lang %{name} --with-kde

To process Qt’s .qm binary translation files use

%find_lang %{name} --with-qt

To process localised manpages (doesn’t include the default, non-localised one), use

%find_lang %{name} --with-man

To see all the options, run /usr/lib/rpm/find-lang.sh in the terminal.

Names different from %{name} (e.g. multiple manpages) must be handled via separate calls to %find_lang.

Here is an example of proper usage of %find_lang, in foo.spec with the “foo” application localised using gettext and man pages named “bar” instead of “foo”:

Name: foo
...
%prep
%setup -q

%build
%configure --with-cheese
make %{?_smp_mflags}

%install
make DESTDIR=%{buildroot} install
%find_lang %{name}
%find_lang bar --with-man

%files -f %{name}.lang -f bar.lang
%license LICENSE
%doc README
%{_bindir}/%{name}
%{_mandir}/man1/bar.1.gz

%changelog
* Fri Jan 13 2012 Karel Volny <kvolny@redhat.com> 0.1-2
- add man pages example

* Thu May 4 2006 Tom "spot" Callaway <tcallawa@redhat.com> 0.1-1
- sample spec that uses %%find_lang

%{_datadir}/locale/ar/LC_MESSAGES/%{name}.mo
%{_datadir}/locale/be/LC_MESSAGES/%{name}.mo
%{_datadir}/locale/cs/LC_MESSAGES/%{name}.mo
%{_datadir}/locale/de/LC_MESSAGES/%{name}.mo
%{_datadir}/locale/es/LC_MESSAGES/%{name}.mo
...

Log Files¶

Packages which generate log files should write out their logfiles in a package-specific (and package owned) directory under %{_localstatedir}/log. Unless the software being packaged rotates its own logs, it must also ship a logrotate config file to rotate its log file(s).

/var/log/example/*log {
    missingok       # If the log file is missing, go on to the next one without issuing an error message
    notifempty      # Don't do any rotation if the logfile is empty
    compress        # Compress older files with gzip
    delaycompress       # Don't compress yesterdays files
}

Timestamps¶

When adding file copying commands in the spec file, consider using a command that preserves the files’ timestamps, eg. cp -p or install -p.

When downloading sources, patches etc, consider using a client that preserves the upstream timestamps. For example wget -N or curl -R. To make the change global for wget, add this to your ~/.wgetrc: timestamping = on, and for curl, add to your ~/.curlrc: -R.

Parallel make¶

Whenever possible, invocations of make should be done as

%make_build

This generally speeds up builds and especially on SMP machines.

Do make sure, however, that the package builds cleanly this way as some make files do not support parallel building. Therefore you should consider adding

%_smp_mflags -j3

to your ~/.rpmmacros file – even on UP machines – as this will expose most of these errors.

Scriptlets¶

Great care should be taken when using scriptlets in Fedora packages. If scriptlets are used, those scriptlets must be sane. Some common scriptlets are documented here: Scriptlets.

Build packages with separate user accounts¶

When building software, which you have not conducted a full security-audit on, protect sensitive data, such as your GPG private key, in a separate user account.

The same applies to reviewers/testers. Rebuild src.rpms in a separate account which does not have access to any sensitive data.

Relocatable packages¶

The use of RPM’s facility for generating relocatable packages is strongly discouraged. It is difficult to make work properly, impossible to use from the installer or from yum, and not generally necessary if other packaging guidelines are followed. However, in the unlikely event that you have a good reason to make a package relocatable, you MUST state this intent and reasoning in the request for package review.

File and Directory Ownership¶

Your package should own all of the files that are installed as part of the %install process.

In most cases, it should not be necessary for multiple packages to contain identical copies of the same file. However, if it is necessary, multiple packages may contain identical copies of the same file, as long as the following requirements are met:

• The packages sharing ownership of the identical files are built from a single SRPM.

OR

• The packages sharing ownership of the identical files are not in a dependency chain (e.g. if package A requires package B, they should not both contain identical files, either A or B must own the common files, but not both.)

In addition, identical files are defined as files which are always identical in content, checksum, permissions, and location on the filesystem in each package.

Directory ownership is a little more complex than file ownership. Packages must own all directories they put files in, except for:

• any directories owned by the filesystem, man, or other explicitly created -filesystem packages
• any directories owned by other packages in your package’s natural dependency chain

In this context, a package’s “natural dependency chain” is defined as the set of packages necessary for that package to function normally. To be specific, you do not need to require a package for the sole fact that it happens to own a directory that your package places files in. If your package already requires that package for other reasons, then your package should not also own that directory.

In all cases we are guarding against unowned directories being present on a system. Please see Packaging:UnownedDirectories for the details.

Here are examples that describe how to handle most cases of directory ownership.

Users and Groups¶

Some packages require or benefit from dedicated runtime user and/or group accounts. Guidelines for handling these cases are in a separate Packaging:UsersAndGroups document.

Note that system services packaged for Fedora MUST NOT run as the nobody user, but MUST instead allocate their own system user.

Web Applications¶

Web applications packaged in Fedora should put their content into /usr/share/%{name} and NOT into /var/www/. This is done because:

• /var is supposed to contain variable data files and logs. /usr/share is much more appropriate for this.
• Many users already have content in /var/www, and we do not want any Fedora package to step on top of that.
• /var/www is no longer specified by the Filesystem Hierarchy Standard

Conflicts¶

Whenever possible, Fedora packages should avoid conflicting with each other. Unfortunately, this is not always possible. For full details on Fedora’s Conflicts policy, see: Packaging:Conflicts .

Tools such as Alternatives and Environment Modules can also help prevent package conflicts.

Patch Guidelines¶

# http://bugzilla.gnome.org/show_bug.cgi?id=12345
Patch0: gnome-panel-fix-frobnicator.patch

# Don't crash with frobnicator applet
# http://bugzilla.gnome.org/show_bug.cgi?id=12345
Patch0: gnome-panel-fix-frobnicator.patch

# Sent upstream via email 20080407
Patch0: foobar-fix-the-bar.patch

# Upstream has applied this in SVN trunk
Patch0: foobar-fix-the-baz.patch

# This patch is temporary until we land the long term System.loadLibrary fix in OpenJDK
Patch0: jna-jni-path.patch

Use of Epochs¶

RPM supports a field called “Epoch:”, which is a numeric field, that, if set, adds another qualifier for RPM to use in doing package comparisons. Specifically, if set, the Epoch of a package trumps all other comparisons (except for a larger Epoch). If Epoch is not set in a package, RPM treats it the same as if it was set to 0.

Example:

Version: 1.2
Release: 3%{?dist}
Epoch: 1

A package with those definitions would be considered greater than a package with a higher version or a higher release. Since Epoch is confusing to humans (and can never be removed from a package once used), it should only be used in Fedora as a last resort to resolve upgrade ordering of a package, and should be avoided wherever possible.

Also, Epoch complicates normal packaging guidelines. If a package uses an Epoch, it must be referred to in any place where %{version}-%{release} is used. For example, if a package being depended upon has an Epoch, this must be listed when adding a versioned dependency:

Requires: foo = %{epoch}:%{version}-%{release}

Symlinks¶

There are two ways of making a symlink, either as a relative link or an absolute link. In Fedora, neither method is required. Packagers should use their best judgement when deciding which method of symlink creation is appropriate.

ln -s ../..%{_bindir}/foo %{buildroot}/bin/foo

ln -s %{_bindir}/foo %{buildroot}/bin/foo

Replacing a symlink to a directory or a directory to any type file¶

In some cases replacing a symlink to a directory requires special handling. Replacing a directory with any type of file always requires special handling.

See Packaging:Directory_Replacement for information about doing this.

Test Suites¶

If the source code of the package provides a test suite, it should be executed in the %check section, whenever it is practical to do so.

binfmt.d, sysctl.d and tmpfiles.d¶

If you install a sysctl configuration snippet foobar.conf into %{_sysctldir} (/usr/lib/sysctl.d/) you must invoke %sysctl_apply in your %post section:

%sysctl_apply fooar.conf

If you install a binfmt configuration snippet waldo.conf into %{_binfmtdir} (/usr/lib/binfmt.d/) you must invoke %binfmt_apply in your %post section:

%binfmt_apply waldo.conf

These have the effect of making the appropriate changes immediately upon package installation instead of requiring a reboot or manual activation.

There are specific guidelines for handling tmpfiles.d configurations and directories (in /run and /run/lock): Packaging:Tmpfiles.d

Renaming/Replacing Existing Packages¶

In the event that it becomes necessary to rename or replace an existing package, the new package should make the change transparent to end users to the extent applicable.

If a package is being renamed without any functional changes, or is a compatible enough replacement to an existing package (where “enough” means that it includes only changes of magnitude that are commonly found in version upgrade changes), provide clean upgrade paths and compatibility with:

Provides: oldpackagename = $provEVR
Obsoletes: oldpackagename < $obsEVR

$provEVR refers to an (Epoch-)Version-Release tuple the original unchanged package would have had if it had been version or release bumped. You usually use macros here because the provides EVR should continue to go up as the renamed package advances in version and release. $obsEVR is an (Epoch-)Version-Release tuple arranged so that there is a clean upgrade path but without gratuitously polluting the version space upwards. You usually do not use macros for this as you’re simply trying to advance beyond the last known release under the old name.

If a package supersedes/replaces an existing package without being a sufficiently compatible replacement as defined above, use only the Obsoletes: line from the above example.

If retired packages need to be removed from end user machines because they cause dependency issues which interfere with upgrades or are otherwise harmful, a packager MAY request that Obsoletes: be added to fedora-obsolete-packages. Simply file a bugzilla ticket here. Please include information on which packages need to be obsoleted, the exact versions which need to be obsoleted, and the reasons why they cannot be allowed to remain installed.

If the obsoleted package had an Epoch set, it must be preserved in both the Provides: and Obsoletes:. For example, assume foo being renamed to bar, bar is compatible with foo, and the last foo package release being foo-1.0-3%{?dist} with Epoch: 2. The following should be added to bar (and similarly for all subpackages as applicable):

Provides: foo = 2:%{version}-%{release}
Obsoletes: foo <= 2:1.0-4   # Important: We set the Obsoletes release to 4 to be higher than the previous Release: 3%{?dist}

Explicit Provides: need to be aware of whether the package is supplying things that can be used in an arch-independent or arch-specific fashion. For packages that are not noarch, Provides: should be made arch-specific by applying the %{?_isa} macro to the end of the text string in Provides (e.g. Provides: foo%{?_isa} = 2:%{version}-%{release}). Packages that explicitly provide things that can be used in an arch-independent way (for example, those whose dependents don’t need to be of the same arch—need not apply this macro. In some cases, a package will supply multiple elements, some of which may be consumed only by dependents of an identical arch and some which may be consumed by dependents of any arch. In such cases, both arch-specific and arch-independent Provides: are warranted.

Examples of packages that should explicitly provide only arch-specific Provides: include native code libraries or plug-ins and their associated -devel packages. Packages that should explicitly provide only arch-independent Provides: include most stand-alone programs (in addition to all noarch packages). Even though these programs may themselves be arch-specific, clients that run them should not care about their arch in most cases. A package that explicitly provides, for example, both a native code library as well as an interpreted language interface to that library should have both arch-specific (for clients of the native code library) and arch-independent (for clients of the interpreted language interface) Provides:.

If there is no standard naming for a package or other long term naming compatibility requirements involved with the rename, the Provides should be assumed to be deprecated and short lived and removed in the distro release after the next one (ie. if introduced in FC-X, keep in all subsequent package revisions for distros FC-X and FC-(X+1), drop in FC-(X+2)), and the distro version where it is planned to be dropped documented in a comment in the specfile. Maintainers of affected packages should be notified and encouraged to switch to use the new name. Forward compatibility Provides: in older distro branches can be considered in order to make it possible for package maintainers to keep same simple specfiles between branches but still switch to the newer name.

For packages that are not usually pulled in by using the package name as the dependency such as library only packages (which are pulled in through library soname depenencies), there’s usually no need to add the Provides. Note however that the -devel subpackages of lib packages are pulled in as build dependencies using the package name, so adding the Provides is often appropriate there.

Networking Support¶

If an application contains native and stable support for both IPv4 and IPv6, and support for IPv6 does not negatively affect IPv4 then both MUST be enabled in the Fedora package.

Cron Files¶

For details on how to package cron files, refer to: Packaging:CronFiles

Security Updates To Resolve Known CVE Issues¶

If an update to your package resolves a known security concern (at the time of the update) with a Common Vulnerabilities and Exposures (CVE) number assigned to it, you should mention the CVE number in the RPM changelog entry.

Build time network access¶

Packages in the Fedora buildsystem are built in a mock chroot with no access to the internet. Packages must not depend or or use any network resources that they don’t themselves create (ie, for tests). In no cases should source code be downloaded from any external sources, only from the lookaside cache and/or the Fedora git repository.

Bootstrapping¶

If your package introduces build time circular dependencies, you should use this macro to bootstrap your package:

# When we are bootstrapping, we drop some dependencies, and/or build time tests.
%{?_with_bootstrap: %global bootstrap 1}

[...]

%if ! 0%{?bootstrap}
# dependencies for %%check
BuildRequires: foo
%endif

[...]

%if ! 0%{?bootstrap}
%check
make check
%endif

If your package explicitly Provides: some functionality that is missing when bootstrapped, then that Provides: should look like:

%if ! 0%{?bootstrap}
Provides: bar(some_functionality)
%endif

Please note that usage of pre-built binaries in bootstrap still needs an exception from the Packaging Committee as stated in Packaging:Guidelines#Exceptions

System cryptographic policies¶

Applications which make use the SSL or TLS cryptographic protocols MUST follow Packaging:CryptoPolicies.

Shebang lines¶

When packaging script files, where the interpreter to be used is specified in the first line of the script (the shebang line) following #!, the following rules apply:

• env, /bin/env and /usr/bin/env MUST NOT be used. Packaged applications cannot depend upon what the user has in their personal $PATH.
• Files which are not installed as executables SHOULD NOT have shebang lines.
• Language-specific guidelines may have additional restrictions.

Packaging for EPEL¶

For the most part, these guidelines and the application-specific guidelines below cover packaging for both Fedora and EPEL. However, there are necessarily some differences. When packaging for EPEL, please also consult the EPEL packaging guidelines for additional information.

Domain Specific Guidelines¶

Some applications, languages and build systems have specific guidelines written for them, located on their own pages in the Packaging: Namespace.

• Ada
• C and C++
• Cmake
• D
• DevAssistant/DAP
• Drupal 7
• Eclipse plugins
• Emacs/XEmacs
• Fonts
• Fortran
• GAP
• Globus Toolkit
• Haskell
• Java
• JavaScript
• Language packs
• LibreOffice Extensions
• Lisp
• Meson
• Mono
• MPI
• Node.js
• OCaml
• Octave
• Perl
• PHP
• Preupgrade Assistant
• Python
• R modules
• Ruby
• Rust
• Sugar activities
• Tcl/Tk extensions
• Shared web assets
• Wordpress extensions