The package name should preferably match the name of the upstream tarball or the name of the project. In some cases the choice of name is more complicated: When the software has already been packaged by other distributions or by other packagers, it may be a good idea to use the same package name for consistency. Packagers should use their best judgment and consult other developers if necessary.

If the version of a particular software distribution consists of numbers only, these can be put into the Version tag unmodified. If, however, it contains any non-numeric character, RPM will not always be able to handle version comparison correctly if these are put verbatim into the Version field.

As an illustration of what might happen, assume that you have the two packages foobar-1.2.3beta1 and foobar-1.2.3. While foobar-1.2.3 is actually newer than foobar-1.2.3beta1, RPM will assume that the opposite is the case if the version tags are set to 1.2.3beta1 and 1.2.3.

There is also a problem with version comparison in all RPM versions prior to 4.2-0.55: The result of the comparison of the two Version tags 1.0a and 1.0b is entirely a matter of the order of comparison.

fedora.us solves these problems by moving the non-numeric part of version numbers — whatever its intended function is — to the Release tag. The version number 1.2.3beta1, for example, should result in the Version tag 1.2.3, and beta1 would integrated into the Release tag. See Section 2.4.3, “The Release tag” for further details on the composition of the Release tag.

TODO

TODO: pristine sources only, ways to assure that sources are pristine (verifying GPG signatures, asking upstream developers to confirm integrity, looking inside other distros' packages).

TODO

When downloading sources and patches, you should consider using a client that preserves the upstream timestamps. Such clients include wget and curl with the -N and -R options respectively.

To make the change permanent for wget, add

timestamping = on

to your ~/.wgetrc file.

See Section 2.11.1, “Installing files” for information about how to preserve timestamps when installing files.

Unless you need to use characters outside the US-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.

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 file if you feel this is necessary.

Please put personal preferences aside and use American English spelling in the summary and description. Anything else belongs in localized versions.

Every time you make changes, that is, whenever you increment the epoch-version-release-number of a package, add an entry to the change log. 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.

Each entry should contain the date, the name and e-mail address of the person doing the update, and the complete epoch-version-release-number. Try this format:

* Wed May 14 2003 Joe Packager <joe at fedora.us> - 0:1.0-0.fdr.2
- Improved description.

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

* Wed May 17 2003 Joe Packager <joe at fedora.us> - 0:1.0-0.fdr.3
- Added README file (bug 42).

Within Emacs you can easily add change log entries by pressing Ctrl+C followed by e in rpm-spec mode. Make sure that you have the fedora-rpmdevtools-emacs package installed to have the entries appear in the expected format.

RPM sometimes offers multiple ways to express exactly the same thing. This is the case for the macro %{buildroot} and the variable $RPM_BUILD_ROOT which both expand to the path of the build root. The macro %{optflags} and the variable $RPM_OPT_FLAGS make up another pair of equivalents.

Whichever notation is used, it should be used consistently, and mixing the macro and variable notation is considered bad style.

Also note that the notation using variables, i.e. the $RPM_BUILD_ROOT notation, is considered the more official of the two (see Original posting).

The Packager tag should not be used in fedora.us packages. The identity of the packager will still be evident from the entries in the change log. By not using the Packager tag, packagers will also avoid seeing bad binaries rebuilt by someone else with their name in the header.

The Vendor and Distribution tags should not be used in fedora.us packages. These are set automatically by the build system.

The Copyright tag is deprecated. Use the License tag instead.

The License tag should indicate what license the software in the package is covered by. You should inspect the documentation and sources carefully to establish this. If there is any doubt about what license the software is distributed under, the upstream author should be contacted.

Make a table of the more common licenses and their abbreviations. Try to use established abbreviations and names, e.g. GPL, LGPL, BSD, Artistic.

The value of the Group tag should be one of the group names mentioned in the GROUPS file distributed with the rpm package. Table 1, “Valid values for the Group tag.” lists the group names found in rpm-4.3.1-0.

The preferred value for the BuildRoot tag is

BuildRoot:      %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)

TODO: can be optionally defined "0" or omitted entirely. Exception: Never add Epoch to Red Hat updated packages.

The build system builds packages in an environment with only a minimal set of installed packages. If the package to be built requires the presence of some package not in this set, e.g. by including a header file from a -devel package, the build will fail. Somehow the build system has to be informed of which packages are expected to be present, and this is accomplished by using a list of build requires in the .spec file specified using

Packages should therefore specify the build requires necessary to build the package using one or more BuildRequires tags. Packages should, however, only specify the minimal set of packages necessary to build the package. The minimal set of build requires does not include the packages that are in the list of base packages nor packages that are pulled in by any of the other build requires.

TODO: Finish this section!

Whenever you use the Requires, BuildRequires, Provides, Obsoletes, Conflicts, or BuildConflicts tags and specify a particular version requirement, you should also specify the epoch.

TODO: Check discussion http://www.fedora.us/pipermail/fedora-devel/2003-March/000651.html for more details.

TODO: Include an example.

The notation Requires(pre,post) for installation scriptlet dependencies should not be used. Such dependencies should instead be split into separate requirements, e.g.

Requires(post):  GConf2
Requires(preun): GConf2

This notation should not be used as it may trigger rpm bugs. Splitting the requirement is a simple work-around for these bug. (See original posting, first bug report, and second bug report.)

TODO

Whenever possible, invocations of make should be done as

make %{?_smp_mflags}

This generally speeds up builds -- especially on SMP machines.

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

%_smp_mflags -j3

to your ~/.rpmmacros file -- even if you have a UP machine -- to enable parallel builds, as this will expose the majority of such build failures.

TODO

TODO: If it has info files, is there a %post script that installs them, and a %postun one which removes them (and only on erase, not upgrade)? Crossref to info file, scrollkeeper, ldconfig, GConf sections

TODO

Requires(post): /sbin/install-info
Requires(preun): /sbin/install-info

%install
rm -f $RPM_BUILD_ROOT%{_infodir}/dir

%post
/sbin/install-info %{_infodir}/%{name}.info %{_infodir}/dir 2>/dev/null || :

%preun
if [ $1 = 0 ]; then
  /sbin/install-info --delete %{_infodir}/%{name}.info \
    %{_infodir}/dir 2>/dev/null || :
fi

%files
%{_infodir}/*

TODO

Registering documentation with scrollkeeper can be done like this:

Requires(post): scrollkeeper
Requires(postun): scrollkeeper

%install
rm -rf $RPM_BUILD_ROOT/var/scrollkeeper

%post
scrollkeeper-update -q || :

%postun
scrollkeeper-update -q || :

%files
%{_datadir}/omf/*

GConf is used by GNOME applications to store configuration data. It is similar to Windows' registry in functionality, and in the same as Windows applications register new key-value pairs when installed, GConf-enabled GNOME applications ship schema files that should be installed at package installation time.

Schema files have the extension .schema and are installed using the gconftool-2 utility shipped in the GConf2 package. The same utility is used to remove schema files when the package is uninstalled. The spec file fragment below will take care of this task in most cases:

Requires(post): GConf2
Requires(preun): GConf2

%install
export GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL=1
make install DESTDIR=$RPM_BUILD_ROOT
unset GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL

%post
GCONF_CONFIG_SOURCE=`gconftool-2 --get-default-source` \
  gconftool-2 --makefile-install-rule %{_sysconfdir}/gconf/schemas/%{name}.schemas &>/dev/null || :

%preun
if [ "$1" = "0" ] ; then
  GCONF_CONFIG_SOURCE=`gconftool-2 --get-default-source` \
    gconftool-2 --makefile-uninstall-rule %{_sysconfdir}/gconf/schemas/%{name}.schemas &>/dev/null || :
fi

%files
%{_sysconfdir}/gconf/schemas/*

Makefiles usually call gconf-install-tool as part of the install target. This behavior has to be disabled so that schemas are not installed when the package is built. This is the reason for the setting and unsetting of the GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL variable in the %install section. In some cases schema installation is also performed as part of the default makefile target, so that the GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL must be set and unset in the %build section too.

Removing the schemas when the package is uninstalled is important to avoid compatibility problems. Unfortunately the --makefile-uninstall-rule option to gconftool-2 does not exist in the versions shipped with RedHat Linux 8.0 and 9. To avoid failing %preun scriptlets and error message noise on these distributions, the shell magic shown in the spec file fragment above should be added to the uninstallation command.

TODO

TODO: If it installs files named *.so.* into %{_libdir}, is there a %post -p /sbin/ldconfig and %postun -p /sbin/ldconfig?

When using copy commands or file installation commands in the spec file, consider using a command that preserves timestamps.

With both cp and install this is accomplished by using the -p switch, e.g.

install -p -m 0644 foobar.xml %{_datadir}/%{name}/foobar.xml

To take advantage of timestamp preservation, timestamps have to be correct in the first place. See Section 2.5.3, “Downloading sources” for more information about this.

Use macros instead of hard-coded path names. This is particularly important when the source code accepts custom install paths via some sort of configure script.

Verify this table. Values were taken from RHL 9 (rpm-4.2-0.69). Changes/variants should be noted.

Summarize http://www.fedora.us/pipermail/fedora-devel/2003-June/001458.html

TODO: Check ownership of files and directories included within every binary RPM package, e.g. with "rpm -qlv packagename". Check use of %defattr and %attr macros in %files sections.

TODO: Check permissions of files and directories included within every binary RPM package, e.g. with "rpm -qlv packagename". Check use of %defattr and %attr macros in %files sections.

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

The .desktop file format was standardized by freedesktop.org in the Desktop Entry Standard and the list of legal values for the Category key in .desktop files is specified in Appendix A of the Desktop Menu Specification.

The utility desktop-file-validate found in the desktop-file-utils package can be used to validate .desktop files. On pre-FC1 systems you should be aware of a bug which prevents it from handling .desktop files with the Encoding key set (see Original bug report).

In addition to a proper selection of categories from the standard set, .desktop files in fedora.us packages are expected to include the category Application for everything that is supposed to show up in the menus. This is for backwards compatibility. For packages that already exist in Red Hat Linux or Fedora Core, the categories must match the ones in the official packages.

Additionally, all fedora.us packages must use the X-Fedora category. This is usually added when the .desktop file is installed (see Section 2.12.2, “Installing .desktop files” for details).

In particular, make sure that startup-notification (defined in the Startup notification protocol) is enabled. Add

StartupNotify=true

for GNOME 2.2 or later, and

X-KDE-StartupNotify=true

for KDE applications. For other applications compatibility mode should be enabled. This is accomplished by adding

StartupWMClass=string

to the .desktop file where string is a window manager class string for the application. This string can be determined by running

xprop | grep WM_CLASS

and clicking in the application window. For Emacs the following is reported by xprop, for example:

WM_CLASS(STRING) = "emacs", "Emacs"

This means that either of the strings emacs or Emacs would be a valid window manager class string.

Add an example of a "model" .desktop file.

Add a note on boolean notation vs. 0/1?

.desktop files should be installed using the utility desktop-file-install which is found in the desktop-file-utils package.

The files should be installed in the %{_datadir}/applications directory, and when being installed, the vendor prefix should be set to fedora. A typical installation procedure would look like this:

BuildRequires:  desktop-file-utils

%install
desktop-file-install                                       \
  --vendor fedora                                          \
  --dir $RPM_BUILD_ROOT%{_datadir}/applications            \
  --add-category X-Fedora                                  \
  --add-category Application
  %{name}.desktop

%files
%{_datadir}/applications/*%{name}.desktop

Note that this adds the two categories X-Fedora and Application required for fedora.us packages (see Section 2.12.1, “.desktop file format” for details), and is thus suitable for installing valid .desktop files shipped in software distributions.

Some makefiles install .desktop files along with the rest of the files that should be installed. Such .desktop files have to be "re-installed" so that the correct categories and the vendor prefix can be added. This can be done using the following procedure:

BuildRequires:  desktop-file-utils

%install
desktop-file-install                                       \
  --delete-original                                        \
  --vendor fedora                                          \
  --dir $RPM_BUILD_ROOT%{_datadir}/applications            \
  --add-category X-Fedora                                  \
  --add-category Application                               \
  $RPM_BUILD_ROOT%{_datadir}/applications/%{name}.desktop

%files
%{_datadir}/applications/*%{name}.desktop

Even when a particular software distribution includes development files, it might not always be appropriate to put these in a separate sub-package. If there is only a single include file, for example, and it is unlikely that the number of such files will increase in the near future, it will probably not be worth the trouble creating a separate development sub-package. You should instead consider packaging it in the main package and using the Provide mechanism to emulate the existence of the development sub-package:

Provides:       %{name}-devel = %{epoch}:%{version}-%{release}

This mechanism ensures that a development sub-package may be split out from the main package at a later time, should the need arise. For this to work packages depending on the development files in question must have build dependencies on the emulated -devel package, not the main package.

pkgconfig files are provided by many software distributions to simplify the configuration and build process. These files are only useful for software developers and belong in a development sub-package.

Whenever pkgconfig files are included, the package should explicitly require the pkgconfig package. In a typical development sub-package with pkgconfig files, this would look like this:

%package        devel
Requires:       pkgconfig

Packaging the .la files generated by libtool is generally not necessary, and may, in fact, cause problems. In general packages should therefore not include these files.

If you package software which generates such files, you should delete them in the %install section:

%install
find $RPM_BUILD_ROOT -type f -name "*.la" -exec rm -f {} ';'

This is preferred to using the %exclude mechanism in the %files section.

Perl module packages typically require Perl to build. Even though Perl is currently already pulled in by the general build toolchain, it should be listed as a build dependency because support for vendor install directories is available in Perl 5.6.1 and later. Thus, all Perl modules packages should contain:

BuildRequires: perl >= 1:5.6.1

Build and runtime dependencies on other Perl modules should in general use the perl(Some::Module) syntax instead of the package names for flexibility. New modules are regularly folded into upstream Perl between releases; requiring the actual modules minimizes maintenance when package names change. Note that usually rpm figures out the runtime module dependencies correctly automatically, so explicitly including them is seldom necessary.

Since we assume Perl 5.6.1 or newer, there is no need to include explicit dependencies to modules which are already part of it. However, build dependencies on modules which are not part of 5.6.1 must be explicitly included.

In order to depend on a correct version of Perl at runtime, the virtual package perl(:MODULE_COMPAT_X.Y.Z) provided by recent versions of Perl in Fedora Core should be used. For earlier distribution versions, the package perl-forward-compat from fedora.us provides this. :MODULE_COMPAT_X.Y.Z means that the package to be built requires a Perl which is compatible with regards to it's modules and their installation locations to the one that built the module package. Example:

Requires: perl(:MODULE_COMPAT_%(eval "`%{__perl} -V:version`"; echo $version))

Perl provides different base locations for installing modules. We consider fedora.us a vendor, so packages should use the vendor installation directories, and leave site install directories for local administrators. This is accomplished by appending INSTALLDIRS=vendor to the Makefile.PL line for packages that use ExtUtils::MakeMaker, and installdirs=vendor to the Build.PL line for packages that use Module::Build. Vendor install directories are available in Perl 5.6.1 and later.

As of rpm version 4.3-0.9 and later (roughly equals Fedora Core 2 and later), two useful rpm macros are available: %{perl_vendorlib} and %{perl_vendorarch}. The former points to the base vendor install directory where Perl installs architecture independent pure Perl modules, and the latter is the same for architecture dependent ones. It is strongly recommended to use these macros in the %files section of Perl module packages; doing so hides the complexity and potential fragility of homebrew solutions of finding the directories where modules are installed. If support for rpm versions where these macros are not available is needed, they can be conditionally defined in specfiles like:

%{!?perl_vendorlib: %define perl_vendorlib %(eval "`%{__perl} -V:installvendorlib`"; echo $installvendorlib)}
%{!?perl_vendorarch: %define perl_vendorarch %(eval "`%{__perl} -V:installvendorarch`"; echo $installvendorarch)}

Note that only one of these macros is needed in the vast majority of Perl module specfiles; as a rule of thumb, %{perl_vendorlib} is for pure Perl noarch packages, and %{perl_vendorarch} for others.

TODO: check whether both CFLAGS and OPTIMIZE are needed with ExtUtils::MakeMaker packages. Check also if Module::Build uses CFLAGS, and if it's The Right Thing To Do to use optimize=foo and/or CFLAGS.

Like with all non-noarch packages, architecture dependent Perl module packages should honor rpm's optimization flags. To accomplish this in modules using ExtUtils::MakeMaker, set CFLAGS="$RPM_OPT_FLAGS" in the environment before running Makefile.PL, and add the OPTIMIZE="$RPM_OPT_FLAGS" make variable to the main compilation step for backwards compatibility. For module packages using Module::Build, use optimize="$RPM_OPT_FLAGS" in the main compilation step.

The ExtUtils::MakeMaker included in distributions before Fedora Core 2 has a habit of creating spurious RPATHs containing build root dirs in Perl module *.so's. Due to another bug, this cannot be robustly avoided by (un)setting LD_RUN_PATH during the build. The following hack can (and is recommended to) be used instead, in the %build section after the Makefile has been created but before the actual make has been run:

%{__perl} -pi -e 's/^\tLD_RUN_PATH=[^\s]+\s*/\t/' Makefile

It should be safe to include this hack also in specfiles targeted for Fedora Core 2 and newer, although it is most likely unnecessary there. Note also that this hack will get rid of all RPATHs, including legitimate ones, so for the (rare) cases where an RPATH is actually needed, a more fine-grained solution needs to be applied.

TODO: cleaning up in %install

More and more CPAN module packages contain digital signatures of the packages' contents inside the distribution tarball. These signatures are usually in a file called SIGNATURE in the distribution, and can be used to verify the integrity of the tarball contents using the cpansign utility available in the perl-Module-Signature package. Additionally, many module distributions verify this signature in their test suite when running make test. That's nice.

However, this built-in integrity checking has a few features that interfere with building rpms: it makes patching of the package practically impossible or at least unnecessarily hard, it may choke on extra files in the build root (such as debug*.list automatically generated for -debuginfo packages), it may need a network connection for fetching keys, and it may silently import those keys in keyrings where we don't want them.

Because of the issues above, and since the shipped source and binary rpms are signed anyway, it is strongly recommended to ensure that this built-in verification is not done when building the rpm (whether perl-Module-Signature is installed in the build system or not), usually by patching the module's test suite one way or another. On the other hand, packagers are encouraged to verify the CPAN signatures manually using cpansign when packaging these modules.

Summarize http://www.fedora.us/pipermail/fedora-devel/2003-August/001847.html

TODO: Does the package ship daemons or similar programs which support execution as non-root? It is a packaging-error when the daemon runs as root, or as a standard user like nobody. Instead a special user should be used. Discussion at http://www.fedora.us/pipermail/fedora-devel/2003-June/001492.html.