Packaging Guidelines

It is the reviewer's responsibility to point out specific problems with a package and a packager's responsibility to deal with those issues. The reviewer and packager work together to determine the severity of the issues (whether they block a package or can be worked on after the package is in the repository.) The Packaging Guidelines are a collection of common issues and the severity that should be placed on them. While these guidelines should not be ignored, they should also not be blindly followed. If you think that your package should be exempt from part of the Guidelines, please bring the issue to the Fedora Packaging Committee.

Please remember that any package that you submit must also conform to the Review Guidelines .

Author: Tom 'spot' Callaway (based on many other documents)
Revision: 0.91
Initial Draft: Wednesday Feb 23, 2005
Last Revised: Wednesday May 21, 2008

Naming

You should go through the ["Packaging/NamingGuidelines"] to ensure that your package is named appropriately.

Legal

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

Licensing

You should review Licensing and the Packaging/LicensingGuidelines to ensure that your package is licensed appropriately.

No inclusion of pre-built binaries or libraries

All binaries or libraries included with Fedora packages must have been built from sourcecode included in the source package. This is a requirement for the following reasons:

Security: Pre-packaged binaries and libraries not built from source could include anything, malicious, dangerous, or just broken. Also, these are functionally impossible to patch.
Compiler Flags: Pre-packaged binaries and libraries not built from source probably don't have the standard Fedora compiler flags for security and optimization.

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

Is it executable? If so, it is probably a binary.
Does it contain a .so, ,so.#, or .so.#.#.# extension? If so, it is probably a 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).

Exceptions

Some software (usually related to compilers or cross-compiler environments) cannot be build without the use of a previous toolchain or development environment (open source). If you have a package which meets this criteria, contact the Fedora Packaging Committee for approval.
An exception is made for binary firmware, as long as it meets the requirements documented here: [wiki:Self:Packaging/LicensingGuidelines#BinaryFirmware BinaryFirmware]

Writing a package from scratch

When writing a package from scratch, you should base your spec file on the Fedora spec file template (see ["rpmdevtools"] ). Please put your preferences about spec file formatting and organization aside, and try to conform to this template as much as possible. This is not because we believe this is the only right way to write a spec file, but because it often makes it easier for QA to spot mistakes and quickly understand what you are trying to do.

Modifying an existing package

If you base a package on an existing non-Fedora package, be careful to verify its correctness and to understand exactly what goes on. Do not submit a package without knowing what those strange, but innocent-looking commands do.

In particular, you should

verify any sources and patches.
verify that the license stated in the spec file matches the actual license of the software (see Tags ),
skim the summary and description for typos and oddities (see Summary and description ),
make sure that the correct build root is used,
ensure that macro usage is consistent (see Macros ).

Keep old changelog entries to credit the original authors. Entries that are several years old or refer to ancient versions of the software may be erased. If you end up doing radical changes and re-write most of the spec file anyway, feel free to start the changelog from scratch. In other words, use your best judgement.

Filesystem Layout

Fedora follows the Filesystem Hierarchy Standard with regards to filesystem layout. The FHS defines where files should be placed on the system. Fedora packages should follow the FHS whenever possible. Any deviation from the FHS should be rationalized when the package is reviewed.

There is one notable exception, libexecdir.

Libexecdir

The Filesystem Hierarchy Standard does not include any provision for libexecdir, but Fedora packages can store appropriate files there. Libexecdir (aka, /usr/libexec on Fedora systems) should be used as the directory for executable programs that are designed primarily to be run by other programs rather than by users. Fedora's rpm includes a macro for libexecdir, %{_libexecdir}. Packagers are highly encouraged to store libexecdir files in a package-specific subdirectory of %{_libexecdir}, such as %{_libexecdir}/%{name}.

Use rpmlint

Run rpmlint on the 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. The rpmlint package is available in the Fedora repositories.

Rpmlint Errors

Rpmlint has the ability to make a lot of noise when it is run, even on perfectly valid packages. This section exists to help you decipher the messages, so that you can make fixes as necessary.

E: foo-package no-packager-tag: This error occurs because no Packager: value is defined in the spec file. In Fedora, we do not use the Packager tag, so you can ignore this error.
E: foo-package no-signature: This error occurs because your package is not signed. Since Fedora doesn't store SRPMS in CVS (only the files inside them), you do not need to sign your package, and you can ignore this error.
W: foo-package summary-ended-with-dot Summary of my package.: This error occurs because the entry in your spec for Summary: ended with a period. Just get rid of the period at the end of the line.
E: foo-package wrong-script-end-of-line-encoding /path/to/somefile: This error occurs because of DOS line breaks in a file. Fix it with sed in the %prep section: %{__sed} -i 's/\r//' src/somefile -- DONT use dos2unix, that can cause build fail on FC3.
E: foo-package invalid-lc-messages-dir /usr/share/locale/xx_XX/LC_MESSAGES/foo.mo: This error is a common false positive and usually should be ignored.

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 packages, 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.

BuildRoot tag

The !BuildRoot value MUST be below %{_tmppath}/ and MUST contain at least %{name}, %{version} and %{release}. It may invoke mktemp since this is guaranteed to exist on every system. From there, packagers are expected to use a sane !BuildRoot.

The recommended values for the !BuildRoot tag are (in descending order of preference) :

%(mktemp -ud %{_tmppath}/%{name}-%{version}-%{release}-XXXXXX)
%{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
%{_tmppath}/%{name}-%{version}-%{release}-root

At one point, the second was a mandatory value, but it is now left to the packager to decide. If unsure, simply pick the first.

Prepping BuildRoot For %install

It is important to properly prepare the !BuildRoot in the %install section of your package before it is used. Every Fedora package MUST have an %install section that begins with either:

%install
rm -rf %{buildroot}

or

%install
rm -rf $RPM_BUILD_ROOT

This is to ensure that the !BuildRoot will be created fresh during the %install section.

Requires

RPM has very good capabilities of automatically finding dependencies for libraries and eg. Perl modules. In short, don't reinvent the wheel, but just let rpm do its job. There is usually no need to explicitly list eg. Requires: libX11 when the dependency has already been picked up by rpm in the form of depending on libraries in the libX11 package.

Build requirements are different. There's no automatic dependency find procedure for them, which means that you must explicitly list stuff that the package requires to build successfully. Typically, some -devel packages are listed there. Refer to the BuildRequires section .

Sometimes we know that a package requires eg. gtk+-devel 1.2 or newer to build (and thus gtk+ 1.2 or newer to run, but that's handled automatically). There are two things to consider here:

First, if the lowest possible requirement is so old that nobody has a version older than that installed on any target distribution release, there's no need to include the version in the dependency at all. In that case we know the available software is new enough. For example, the version in gtk+-devel 1.2 dependency above is unnecessary for all Red Hat Linux distributions since (at least) release 6.2. As a rule of thumb, if the version is not required, don't add it just for fun.

Second, the Epoch must be listed when adding a versioned dependency to achieve robust epoch-version-release comparison. A quick way to check the Epoch of package foo is to run:

rpm --query --qf "%{EPOCH}\n" packagename

Typically, the requirements for -devel packages need yet another look. They're not usually picked up automatically by rpm. If the foo-devel package has a foo-config script, you can try doing a foo-config --libs and foo-config --cflags to get strong hints what packages should be marked as foo's requirements. For example:

$ 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

This means that gtk+-devel should contain

Requires: glib-devel libXi-devel libXext-devel libX11-devel

PreReq

Packages should not use the PreReq tag. Once upon a time, in dependency loops PreReq used to "win" over the conventional Requires when RPM determined the installation order in a transaction. This is no longer the case.

File Dependencies

Rpm gives you the ability to depend on files instead of packages. Whenever possible you should avoid file dependencies outside of /etc, /bin, /sbin, /usr/bin, or /usr/sbin. Using file dependencies outside of those directories requires yum (and other depsolvers using the repomd format) to download and parse a large xml file looking for the dependency. Helping the depsolvers avoid this processing by depending on the package instead of the file saves our end users a lot of time. There are times when other technical considerations outweigh these considerations. One specific example is packages installing into %{_libdir}/mozilla/plugins. In this case, mandating a specific browser in your package just to own this directory could drag in a large amount of needless packages. Requiring the directory to resolve the dependency is the better choice.

BuildRequires

In package development and testing, please verify that your package is not missing any necessary build dependencies. Having proper build requirements saves the time of all developers and testers as well as autobuild systems because they will not need to search for missing build requirements manually. It is also a safety feature that prevents builds with that would not otherwise fail, but would be missing crucial features. For example, a graphical application may exclude PNG support after its configure script detects that libpng is not installed.

Before adding BuildRequires to any package, please be comfortable with Requires .

There are two suggested ways of detecting missing BuildRequires. rpmdev-rmdevelrpms and mock. The first one is designed to remove all developer-related packages from your system. If the build fails or is missing certain features due to missing build dependencies, then the missing dependency needs to be found and added. Check the rpmdev-rmdevelrpms section to find out more.
mock is another good way to check build dependencies. Rather than remove all developer packages, it tries to build your package in a chroot. It makes no changes to your normal, daily environment and ensures that your package will build fine. However, mock may need a good internet connection to download all required packages. MockTricks page contains more information. Another mock-like tool, mach is also available in the Fedora repository.

rpmdev-rmdevelrpms

rpmdev-rmdevelrpms script within the rpmdevtools toolkit is a script written by Ville Skyttä that helps RPM packagers in finding missing BuildRequires. Simply run it and allow it to remove all *-devel packages and build tools like this example.

[root@build-fc1 /] # rpmdev-rmdevelrpms
Found 52 devel packages:
guile-devel-1.6.4-8.2
bison-1.875-5
m4-1.4.1-14
flex-2.5.4a-30
openssl-devel-0.9.7a-23
automake-1.7.8-1
fontconfig-devel-2.2.1-6.1
XFree86-devel-4.3.0-42
tcl-devel-8.3.5-93
SDL_image-devel-1.2.3-3
SDL_ttf-devel-2.0.6-0.fdr.3.1
pth-devel-2.0.0-0.fdr.1.1
libIDL-devel-0.8.2-1
atk-devel-1.4.0-1
gtk2-devel-2.2.4-5.1
libmng-devel-1.0.4-4
glib-devel-1.2.10-11
gtk+-devel-1.2.10-28.1
audiofile-devel-0.2.3-7
compface-1.4-0.fdr.3.1
esound-devel-0.2.31-1
libungif-devel-4.1.0-16
gnome-libs-devel-1.4.1.2.90-35
openldap-devel-2.1.22-8
aspell-devel-0.50.3-16
gpgme03-devel-0.3.16-0.fdr.2.1
freeglut-devel-1.3-1.20020125.3
e2fsprogs-devel-1.34-1
db4-devel-4.1.25-14
krb5-devel-1.3.1-6
autoconf-2.57-3
libtool-1.5-8
gdbm-devel-1.8.0-21
freetype-devel-2.1.4-5
pkgconfig-0.14.0-6
ncurses-devel-5.3-9
tk-devel-8.3.5-93
SDL-devel-1.2.5-9
SDL_mixer-devel-1.2.4-9
zlib-devel-1.2.0.7-2
libgpg-error-devel-0.6-0.fr.3.1
glib2-devel-2.2.3-1.1
pango-devel-1.2.5-1.1
libjpeg-devel-6b-29
libpng-devel-1.2.2-17
ORBit-devel-0.5.17-10.3
clamav-devel-0.65-0.fdr.4.1
cyrus-sasl-devel-2.1.15-6
libtiff-devel-3.5.7-14
imlib-devel-1.9.13-14
gdk-pixbuf-devel-0.22.0-3.0
pilot-link-devel-0.11.8-1
Remove them? [y/N]  y[
]Removing.................................................................................................
................................................................Done.

Then attempt to build your RPM package. Use yum to reinstall any packages that are already in BuildRequires. If your build fails after this point, then you need to read through the build process and ascertain the missing BuildRequires from the error messages within.

Be very careful to watch especially the configure part of the build process for missing optional libraries or tools that are desirable for the package.

By default, the script may attempt to remove some packages that your system needs to operate correctly. Usually, this will fail due to an unsatisfied dependency (and this, BTW is why the script is using rpm -e instead of yum remove...)

An example of this are the gettext and libgcj packages. gettext is usually a development-only package, but for example redhat-lsb depends on it. Also, it seems that RH9 Konqueror needs openssl-devel for SSL. If you wish to mark some packages so that they will be ignored by rpmdev-rmdevelrpms, do it in /etc/rpmdevtools/rmdevelrpms.conf or your personal /.rmdevelrpmsrc and pay special attention to the packages you treated this way when building.

Exceptions

There is no need to include the following packages or their dependencies as BuildRequires because they would occur too often. These packages are considered the minimum build environment. The derived list of all deps pulled in by this list is on Packaging/FullExceptionList .

bash
bzip2
coreutils
cpio
diffutils
fedora-release
findutils
gawk
gcc
gcc-c++
grep
gzip
info
make
patch
redhat-rpm-config
rpm-build
sed
shadow-utils
tar
unzip
util-linux-ng
which

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. Anything else belongs in localized versions.

Encoding

Unless you need to use characters outside the ASCII repertoire , you will not need to be concerned about the encoding of the spec file. If you do need non-ASCII characters, save your spec files as UTF-8. If you're in doubt as to what characters are ASCII, please refer to this chart .

Non-ASCII Filenames

Similarly, filenames that contain non-ASCII characters must be encoded as UTF-8. Since there's no way to note which encoding the filename is in, using the same encoding for all filenames is the best way to ensure users can read the filenames properly. If upstream ships filenames that are not encoded in UTF-8 you can use a utility like convmv (from the convmv package) to convert the filename in your %install section.

Documentation

Any relevant documentation included in the source distribution should be included in the package. Irrelevant documentation include build instructions, the omnipresent INSTALL file containing generic build instructions, for example, and documentation for non-Linux systems, e.g. README.MSDOS. Pay also 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, and Documentation as the value of the Group tag.

Compiler flags

Compilers used to build packages should honor the applicable compiler flags set in the system rpm configuration. As of Aug 2006, this means in practice $RPM_OPT_FLAGS/%{optflags} for C, C++, and Fortran compilers. 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. 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 should be reviewed and documented in the specfile especially in the override and filter cases.

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"] .

Exclusion of Static Libraries

Packages including libraries should exclude static libs as far as possible (eg by configuring with --disable-static). Static libraries should only be included in exceptional circumstances. Applications linking against libraries should as far as possible 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 and should not be undertaken lightly.

Packaging Static Libraries

In general, packagers are strongly encouraged not to ship static libs unless a compelling reason exists.

We want to be able to track which packages are using static libraries (so we can find which packages need to be rebuilt if a security flaw in a static library is fixed, for instance). There are two scenarios in which static libraries are packaged:

1. Static libraries and shared libraries.' In this case, the static libraries must be placed in a *-static subpackage. Separating the static libraries from the other development files in *-devel allow us to track this usage by checking which packages Build'Require the *-static package. The intent is that whenever possible, packages will move away from using these static libraries, to the shared libraries. 2. Static libraries only. When a package only provides static libraries you can place all the static library files in the *-devel subpackage. When doing this you also must have a virtual Provide for the *-static package:

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

Packages which explicitly need to link against the static version must BuildRequire: foo-static, so that the usage can be tracked.

If (and only if) a package has shared libraries which require static libraries to be functional, the static libraries can be included in the *-devel subpackage. The devel subpackage must have a virtual Provide for the *-static package, and packages dependent on it must Build'Require the *-static package.

Staticly Linking Executables

Static linkage is a special exception and should be decided on a case-by-case basis. The packager must provide rationale for linking statically, including precedences where available, to FESCO for approval.
If you link statically against a library, add yourself to the initialcc list for the library so you can watch for any security issues or bug fixes for which you'd want to rebuild your package against a new version of the library. Here are instructions for making that request.

Programs which don't need to notify FESCo

Programs written in OCaml do not normally link dynamically to OCaml libraries. Because of that this requirement is waived. (OCaml code that calls out to libraries written in C should still link dynamically to the C libraries, however.)

If a library you depend on only' provides a static version your package can link against it provided that you Build'Require the *-static subpackage. Packagers in such a situation should be aware that if a shared library becomes available, that you should adjust your package to use the shared library.

Duplication of system libraries

For several reasons, a package should not include or build against a local copy of a library that exists on a system. The package should be patched to use the system libraries.

This prevents old bugs and security holes from living on after the core system libraries have been fixed.

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, and in Fedora it is forbidden. 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 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]

Often, rpath is used because a binary is looking for libraries in a non-standard location (standard locations are /lib, /usr/lib, /lib64, /usr/lib64). If you are storing a library in a non-standard location (e.g. /usr/lib/foo/), you should include a custom config file in /etc/ld.so.conf.d/. For example, if I was putting 32 bit libraries of libfoo in /usr/lib/foo, I would want to make a file called "foo32.conf" in /etc/ld.so.conf.d/, which contained the following:

/usr/lib/foo

Make sure that you also make a 64bit version of this file (e.g. foo64.conf) as well (unless the package is disabled for 64bit architectures, of course).

Removing Rpath

There are several different ways to fix the rpath issue:

If the application uses configure, try passing the --disable-rpath flag to configure.
If the application uses a local copy of libtool, add the following lines to the spec after %configure:

%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

Sometimes, the code/Makefiles can be patched to remove the -rpath or -R flag from being called. This is not always easy or sane to do, however.
As a last resort, Fedora has a package called chrpath. When this package is installed, you can run chrpath --delete on the files which contain rpaths. So, in our earlier example, we'd run:

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

Make sure that you remember to add a BuildRequires: chrpath if you end up using this method.

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.

Initscripts

Currently, only SystemV-style initscripts are supported in Fedora. There are detailed guidelines for SysV-style initscripts here: ["Packaging/SysVInitScript"]

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.

Icon tag in Desktop Files

The icon tag can be specified in two ways:

Full path to specific icon file:

Icon=/usr/share/pixmaps/comical.png

Short name without file extension:

Icon=comical

The short name without file extension is preferred, because it allows for icon theming (it assumes .png by default, then tries .svg and finally .xpm), but either method is acceptable.

.desktop file creation

If the package doesn't already include and install its own .desktop file, you need to make your own, and include it as a Source: (e.g. Source3: %{name}.desktop). Here are the contents of a sample .desktop file (comical.desktop):

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

desktop-file-install usage

It is not simply enough to just include the .desktop file in the package, one MUST run desktop-file-install in %install (and have BuildRequires: desktop-file-utils), to help ensure .desktop file safety and spec-compliance. Here are some examples of desktop-file-install usage:

desktop-file-install --vendor="<vendor_id>"               \
--dir=${RPM_BUILD_ROOT}%{_datadir}/applications         \
%{SOURCE3}

desktop-file-install --vendor="<vendor_id>"                \
--add-category="Multimedia"                              \
--delete-original                                        \
--dir=%{buildroot}%{_datadir}/applications               \
%{buildroot}/%{_datadir}/applnk/Multimedia/foo.desktop

desktop-file-install --vendor=""                           \
--remove-category="Science"                              \
--dir=%{buildroot}%{_datadir}/applications/<vendor_id>   \
%{buildroot}/%{_datadir}/applications/<vendor_id>/foo.desktop

If upstream uses <vendor_id>, leave it intact, otherwise use fedora as <vendor_id>.
It is important that vendor_id stay constant for the life of a package.

This is mostly for the sake of menu-editing (which bases off of .desktop file/path names).

Macros

Use macros instead of hard-coded directory names (see ["Packaging/RPMMacros"] ).

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"

Using %{buildroot} and %{optflags} vs $RPM_BUILD_ROOT and $RPM_OPT_FLAGS

There are two styles of defining the rpm Build Root and Optimization Flags in a spec file.

macro style   variable style
Build Root  %{buildroot}  $RPM_BUILD_ROOT
Opt. Flags  %{optflags}   $RPM_OPT_FLAGS

There is very little value in choosing one style over the other, since they will resolve to the same values in all scenarios. You should pick a style and use it consistently throughout your packaging.

Mixing the two styles, while valid, is bad from a QA and usability point of view, and should not be done in Fedora packages.

Why the %makeinstall macro should not be used

Fedora's RPM includes a %makeinstall macro but it must NOT be used when make install DESTDIR=%{buildroot} works. %makeinstall is a kludge that can work with Makefiles that don't make use of the DESTDIR variable but it has the following potential issues:

%makeinstall overrides a set of Make variables during "make install" and prepends the %{buildroot} path. I.e. it performs make prefix="%{buildroot}%{_prefix}" libdir="%{buildroot}%{_libdir} ...".
It is error-prone and can have unexpected effects when run against less than perfect Makefiles, e.g. the buildroot path may be included in installed files where variables are substituted at install-time.
It can trigger unnecessary and wrong rebuilds when executing "make install", since the Make variables have different values compared with the %build section.
If a package contains libtool archives, it can cause broken *.la files to be installed.

Instead, Fedora packages should use: make DESTDIR=%{buildroot} install or make DESTDIR=$RPM_BUILD_ROOT install

Handling Locale Files

If the package includes translations, add

BuildRequires: gettext

If you don't, your package could fail to generate translation files in the buildroot.

Fedora includes an rpm macro called %find_lang. This macro will locate all of the locale files that belong 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
%defattr(-,root,root,-)
%{_bindir}/foobar
...

If you are already using the -f parameter for the %files section where the locales should live, just append the contents of %{name}.lang to the end of the file that you are already using with -f. (Note that only one file may be used with %files -f.)

Here is an example of proper usage of %find_lang, in foo.spec:

...
%prep
%setup -q

%build
%configure --with-cheese

%install
make DESTDIR=$RPM_BUILD_ROOT install
%find_lang %{name}

%clean
rm -rf $RPM_BUILD_ROOT

%files -f %{name}.lang
%defattr(-,root,root,-)
%doc LICENSE README
%{_bindir}/foobar

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

Why do we need to use %find_lang?

Using %find_lang helps keep the spec file simple, and helps avoid several other packaging mistakes.

Packages that use %{_datadir}/* to grab all the locale files in one line also grab ownership of the locale directories, which is not permitted.
Most packages that have locales have lots of locales. Using %find_lang is much easier in the spec file than having to do:

%{_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
...

As new locale files appear in later package revisions, %find_lang will automatically include them when it is run, preventing you from having to update the spec any more than is necessary.

Keep in mind that usage of %find_lang in packages containing locales is a MUST.

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

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 requirements

Do not use the Requires(pre,post) style notation for scriptlet dependencies, because of two bugs in RPM. Instead, they should be split like this:

Requires(pre): ...
Requires(post): ...

For more information, see www.redhat.com .

Running scriptlets only in certain situations

When the rpm command executes the scriptlets in a package it indicates if the action preformed is an install, erase, upgrade or reinstall by passing an integer argument to the script in question according to the following:

install   erase   upgrade  reinstall
%pre         1        -         2         2
%post        1        -         2         2
%preun       -        0         1         -
%postun      -        0         1         -

This means that for example a package that installs an init script with the chkconfig command should uninstall it only on erase and not upgrade with the following snippet:

%preun
if [ $1 -eq 0 ] ; then
/sbin/chkconfig --del %{name}
fi

See also /usr/share/doc/rpm-*/triggers, which gives a more formal, generalized definition about the integer value(s) passed to various scripts.

Scriplets are only allowed to write in certain directories

Build scripts of packages (%prep, %build, %install, %check and %clean) may only alter files (create, modify, delete) under %{buildroot}, %{_builddir} and valid temporary locations like /tmp, /var/tmp (or $TMPDIR or %{_tmppath} as set by the rpmbuild process) according to the following matrix

	/tmp, /var/tmp, $TMPDIR, %{_tmppath}	%{_builddir}	%{buildroot}
%prep	yes	yes	no
%build	yes	yes	no
%install	yes	yes	yes
%check	yes	yes	no
%clean	yes	yes	yes

Further clarification: That should hold true irrespective of the builder's uid.

Conditional 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.

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.

Code Vs Content

It is important to make distinction between computer executable code and content. While code is permitted (assuming, of course, that it has an open source compatible license, is not legally questionable, etc.), only some kinds of content are permissable.

The rule is this:

If the content enhances the OS user experience, then the content is OK to be packaged in Fedora. This means, for example, that things like: fonts, themes, clipart, and wallpaper are OK.

Content still has to be reviewed for inclusion. It must have an open source compatible license, must not be legally questionable. In addition, there are several additional restrictions for content:

Content must not be pornographic, or contain nudity, whether animated, simulated, or photographed. There are better places on the Internet to get porn.
Content should not be offensive, discriminatory, or derogatory. If you're not sure if a piece of content is one of these things, it probably is.
All content is subject to review by FESCo, who has the final say on whether or not it can be included.

Some examples of content which is permissable:

Package documentation or help files
Clipart for use in office suites
Background images (non-offensive, discriminatory, with permission to freely redistribute)
Fonts (under an open source license, with no ownership/legal concerns)
Game levels are not considered content, since games without levels would be non functional.
Sound or graphics included with the source tarball that the program or theme uses (or the documentation uses) are acceptable.
Game music or audio content is permissible, as long as the content is freely distributable without restriction, and the format is not patent encumbered.
Example files included with the source tarball are not considered content.

Some examples of content which are not permissable:

Comic book art files
Religious texts
mp3 files (patent encumbered)

If you are unsure if something is considered approved content, ask on fedora-devel-list.

File and Directory Ownership

Your package should own all of the files that are installed as part of the %install process. Packages must not own files already owned by other packages. The rule of thumb here is that the first package to be installed should own the files that other packages may rely upon. This means, for example, that no package in Fedora should ever share ownership with any of the files owned by the filesystem or man package. If you feel that you have a good reason to own a file or that another package owns, then please present that at package review time.

Directory ownership is a little more complex than file ownership. Although the rule of thumb is the same: own all the directories you create but none of the directories of packages you depend on, there are several instances where it's desirable for multiple packages to own a directory. Examples of this are:

1) The package you depend on to provide a directory may choose to own a different directory in a later version and your package will run unmodified with that later version.

One common example of this is a Perl module. Assume perl-A-B depends on perl-A and installs files into /usr/lib/perl5/vendor_perl/5.8.8/i386-linux-thread-multi/A/B. The base Perl package guarantees that it will own /usr/lib/perl5/vendor_perl/5.8.8/i386-linux-thread-multi for as long as it remains compatible with version 5.8.8, but a future upgrade of the perl-A package may install into (and thus own) /usr/lib/perl5/vendor_perl/5.9.0/i386-linux-thread-multi/A. So the perl-A-B package needs to own /usr/lib/perl5/vendor_perl/5.8.8/i386-linux-thread-multi/A as well as /usr/lib/perl5/vendor_perl/5.8.8/i386-linux-thread-multi/A/B in order to maintain proper ownership.

2) Multiple packages have files in a common directory but none of them requires others.

An example:

Foo-Animal-Emu puts files into /usr/share/Foo/Animal/Emu
Foo-Animal-Llama puts files into /usr/share/Foo/Animal/Llama

Neither package depends on the other one. Neither package depends on any other package which owns the /usr/share/Foo/Animal/ directory. In this case, each package must own the /usr/share/Foo/Animal/ directory.

In all cases we are guarding against unowned directories being present on a system. Unowned directories are affected by the umask of the user installing the package and thus can be a security risk or lead to packages which won't run.

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.

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"] .

No External Kernel Modules

The Packaging:KernelModules page used to be transcluded into the main guidelines page. Instead its contents have been pasted there.

If you're seeing this page, you really should be looking here instead.

No Files or Directories under /srv

The FHS says :

"...no program should rely on a specific subdirectory structure of /srv existing
or data necessarily being stored in /srv. However /srv should always exist on FHS
compliant systems and should be used as the default location for such data.

Distributions must take care not to remove locally placed files in these
directories without administrator permission."

/srv is a poorly implemented section of the FHS, and its intended use case is unclear. At this time, no Fedora package can have any directories or files under /srv.

It is important to note that a Fedora package, once installed, and run by a user, can use /srv as a default location for data. The package simply must not own any directories or files in /srv.

Packages already in Fedora owning files or directories in /srv

Any packages currently in Fedora that own files or directories in /srv must be fixed before Fedora 10.

Application Specific Guidelines

Some applications have specific guidelines written for them, located on their own pages in the Packaging/ hierarchy.

Eclipse

Guidelines for Eclipse plugin packages: Packaging/EclipsePlugins

Emacs

Guidelines for Emacs/X-Emacs packages: Packaging/Emacs

Fonts

Guidelines for font packages: Packaging/FontsPolicy

Java

Guidelines for java packages: Packaging/Java

Mono

Guidelines for Mono packages: Packaging/Mono

OCaml

Guidelines for OCaml packages: Packaging/OCaml

OpenOffice.org

Guidelines for OpenOffice.org extension packages: Packaging/OpenOffice.orgExtensions

Perl

Guidelines for Perl packages: Packaging/Perl

PHP

Guidelines for PHP packages: Packaging/PHP

Python

Guidelines for Python addon modules: Packaging/Python

R

Guidelines for R module packages: Packaging/R

Ruby

Guidelines for Ruby packages: Packaging/Ruby

Sugar

Guidelines for Sugar Activity packages: Packaging/SugarActivityGuidelines

Tcl/Tk

Guidelines for Tcl/Tk extension packages: Packaging/Tcl

Search

Packaging:Guidelines

Packaging Guidelines

Naming

Legal

Licensing

No inclusion of pre-built binaries or libraries

Exceptions

Writing a package from scratch

Modifying an existing package

Filesystem Layout

Libexecdir

Use rpmlint

Rpmlint Errors

Changelogs

Tags

BuildRoot tag

Prepping BuildRoot For %install

Requires

PreReq

File Dependencies

BuildRequires

rpmdev-rmdevelrpms

Exceptions

Summary and description

Encoding

Non-ASCII Filenames

Documentation

Compiler flags

Debuginfo packages

Exclusion of Static Libraries

Packaging Static Libraries

Staticly Linking Executables

Programs which don't need to notify FESCo

Duplication of system libraries

Beware of Rpath

Removing Rpath

Configuration files

Initscripts

Desktop files

Icon tag in Desktop Files

.desktop file creation

desktop-file-install usage

Macros

Using %{buildroot} and %{optflags} vs $RPM_BUILD_ROOT and $RPM_OPT_FLAGS

Why the %makeinstall macro should not be used

Handling Locale Files

Why do we need to use %find_lang?

Timestamps

Parallel make

Scriptlets requirements

Running scriptlets only in certain situations

Scriplets are only allowed to write in certain directories

Conditional dependencies

Build packages with separate user accounts

Relocatable packages

Code Vs Content

File and Directory Ownership

Users and Groups

Web Applications

Conflicts

No External Kernel Modules

No Files or Directories under /srv

Packages already in Fedora owning files or directories in /srv

Application Specific Guidelines

Eclipse

Emacs

Fonts

Java

Mono

OCaml

OpenOffice.org

Perl

PHP

Python

R

Ruby

Sugar

Tcl/Tk