Packaging/SUSE Package Conventions/RPM Style

From openSUSE

1. RPM Package Style

This section defines the style of SUSE RPM packages. Most of the information is sorted into sections named by the related lines or tags used in the spec file. The only exception is the last section describing subpackages.

1.1. Initial Comments

The SUSE spec files start with some standardized initial comments:

 #
 # spec file for package PackageName (Version PackageVersion)
 #
 # Copyright 2008 SUSE LINUX Products GmbH, Nuernberg, Germany.
 # Copyright Dirk Mueller <dmueller@suse.de>
 #
 # All modifications and additions to the file contributed by third parties
 # remain the property of their copyright owners, unless otherwise agreed
 # upon. The license for this file, and modifications and additions to the
 # file, is the same license as for the pristine package itself (unless the
 # license for the pristine package is not an Open Source License, in which
 # case the license is the MIT License). An "Open Source License" is a
 # license that conforms to the Open Source Definition (Version 1.9)
 # published by the Open Source Initiative.

Comments that start with "# Copyright" will be preserved during updates of the licensing header, which is performed during package submission.

1.2. norootforbuild

The line starting with:

# norootforbuild

defines that the package is built by a normal user instead of root with the build script. This means that the build of the package is more secure because when built without root access rights, it has only a small opportunity to break the installed system.

The line is of course only recognized by SUSE tools like build, lbuild or the build system. The bare rpmbuild just treats it as a comment since it starts with #.

1.3. BuildRequires Tag

This tag defines packages that must be installed to build the package, it solves dependencies automatically. Before SL 10.1, this tag was automatically generated from the line neededforbuild when the package was built inside SUSE. It has been used instead of the line usedforbuild since SL 9.1.

See also Prereq Tag, Requires Tag.

1.4. usedforbuild

The line starting with:

# usedforbuild

mentions all packages used to build the package. It has been made obsolete by the BuildRequires tag since SUSE Linux 9.1.

1.5. Name Tag

The package name and the name of the source tarball should be the same if it does not break some of the following rules:

• The package name can consist of alphanumeric characters, hyphen, and underline (a-z, A-Z, 0-9, -, _).
• There are special conventions for some specific types of packages:

1.6. License Tag

This tag defines a comma-separated list of license names related to the package. It is automatically generated using a database when the package is built inside SUSE. If a license does not have a well-known name, use a classification starting with 'Any ...' and a few words describing obligations. Use "Any permissive" if there are no apparent obligations.

If the named license exists in multiple version, you should specify the version number. If you cannot find out the license, the standardized text "Other License(s), see package" can be used, although such a package may not be accepted into distributions. Contact legal-devel@suse.de if in doubt.

Examples:

License:      GPLv2
License:      Public domain, Freeware
License:      Other License(s), see package
License:      LGPLv2.1, Any permissive nomod

1.7. Group Tag

The full list of available RPM groups and their descriptions can be found in RPM Groups.

1.8. Version Tag

The package version and the version of the source tarball should be the same if it does not create problems for the package update.

RPM uses the package version and the release number to decide which package is newer and allows only update from a lower to a higher version. RPM splits the package version by dots into major version number, minor version number, etc., and compares the related version numbers alphabetically. If a user wants to downgrade a package version, he should use the option --oldpackage.

The following table shows some typical and correct version sequences:

The following table shows some typical but incorrect version sequences. The third column shows a possible solution:

This is due to the ordering of version numbers as mentioned above, i.e. 1.0 < 1.0b1 < 1.0p0 < 1.0rc1 < 1.0.0. Since 1.0.0 may be undesired as a version number, one can seek a number below 1.0, e.g. 0.99rc1, or in case of 0.45, 0.46-rc1, 0.46, use, for example, 0.45.99-rc1 to represent 0.46-rc1.

1.9. Release Tag

The release number is set to zero with any version update. It is increased by one with any change in the package.

A mechanism has been added to differentiate packages that are distinct from the common code base. It may happen if multiple products are based on the same code base and a package needs a special adjustment for a product. The solution is that the release number is versioned. For example, the latest common build of a package has release number 14 and the package sources are modified for a particular product. Then the package for the product has the release numbers 14.0, 14.1, 14.2, etc., and the same package in the common base continues with the usual release numbers 15, 16, 17, etc.

In the past, the value was increased by one each time the package was rebuilt. The idea was to differentiate two builds of the same package in case the packages used for build were modified. It brought more problems than advantages, so the release number is increased only when the package itself changes now.

1.10. Autoreqprov Tag

This tag should always be enabled because all dependencies that can be automatically detected should be used. It can be disabled only in really rare cases. One example would be a package that contains a plug-in creating a deep dependency but that is not load by default and is used only by a small group of users. In this case, it might make sense to disable the automatic detection, avoid the deep dependency, and describe the problem in a README. However, even in this case a more correct solution exists and the automatic detection can be enabled. The problematic plug-in can be put into a separate package, which has the deep dependency but can be installed optionally.

1.11. PreReq Tag

This tag defines dependencies that need to be satisfied for the package to be installed correctly. The field must mention all packages or absolute path to the tools that are used in the %pre, %post, and %triggerin scripts.

The absolute path is usually used for basic tools, like /bin/touch, /bin/rm. It is because such paths are stable and common even for all UN*Xes. Also they are resistant to various package renames and splits. For less common stuff, the name of the package should be used. It depends on which is most likely to change in the future.

This example comes from the package deb:

PreReq:       /bin/touch
[...]
%post
cd /var/lib/dpkg
for f in diversions statoverride status ; do
        if [ ! -f "$f" ] ; then
                touch "$f"
        fi
done

This example is taken from the package cups-drivers:

PreReq:       sysvinit, sh-utils
 [...]
 %post
 test -x /etc/init.d/cups && \
         /etc/init.d/cups status >/dev/null && \
         /etc/init.d/cups reload >/dev/null
 # exit 0 needed here to ignore test return code
 exit 0
 

SUSE provides some macros that can be used in the PreReq tag. They define the necessary dependences for the related macros that are used in the %post script. See %install_info for an example.

See also Requires Tag, BuildRequires Tag.

1.12. Requires Tag

This tag defines packages that need to be installed need for the package to work correctly. This field must at least mention all the packages that are not detected automatically but are necessary for the function of the package.

It is preferable to require only package names. However, if the interface between a main and a subpackage will change between different versions, the subpackage should require the exact version of the main package but not the release number. This is the typical case of devel subpackages, for example, glibc-devel-<version> requires glibc-<version>. An exact requirement including the release number is necessary only extremely rarely.

See also PreReq Tag and BuildRequires Tag.

1.13. Summary Tag

The summary is a single line string describing the package. The maximum length is 80 characters. It should fit all standard situations and not assume any special context. It should be helpful alone, in alphabetically sorted or unsorted lists of some selected packages, and in alphabetically sorted or unsorted lists of all packages.

It should describe the package's main function and point out any special properties of the package to support the user comparing similar packages. For example, the two words "Web Browser" summarize any web browser, but using additional adjectives (like minimalistic, complex, GNOME, KDE, text-based, fast, or author's) helps characterize a specific package.

The RPM spec file contains only the English version to keep the RPM database small. The localizations are managed by YaST.

1.13.1. Style Guideline

• Use title-style capitalization. This means most words are capitalized except prepositions and articles.
• Do not use an article at the beginning of the line.
• Do not enter a period at the end of the line.
• Try to avoid complete sentences. For example, use “Meta Package with SUSE Contributors as Authors” instead of “This is a meta package. It contains SUSE contributors as authors.”

Examples:

Summary:    High Quality Asteroids Clone
Summary:    Enhanced Interactive Python Shell
Summary:    Tool to Verify 3D Configuration
Summary:    Graphics Library for Framebuffer Devices
Summary:    Converter for Several 3-Dimensional Object File Formats

1.14. Source Tag

The source tarball should be compressed by bzip2. Do not hesitate to repack the source tarball if it does not break the license. Each separate source should be compressed with bzip2 if its size is greater than 100kB. Use the macros %name and %version whenever possible.

LZMA-compressed tarballs also work in at least openSUSE 11.0 and up, but currently require a "BuildRequires: lzma" for decompression via the %setup macro to fully work.

Examples:

Source:    %name-%version.tar.bz2
Source:    bugz-tarball-(3.0.0).tar.bz2

Elements in the source tag must be a relative URI to the content in the RPM from the dir level of the spec file. However, you can also use SourceN tags for documentation purposes. Example:

Source0:   http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-3.2rc1.tar.gz

1.15. Patch Tag

Each problem should be solved in a separate patch. To allow easy maintenance of patches, every patch should have a header providing the following information:

• Authors' names
• Detailed description of the fixed problem
• URL of the original source of the patch if any

The name of a patch file consists of:

• The name and version of the source tarball from which the patched file is derived
• Some words that characterize the patch content
• The filename suffix .patch

Patches are in the unified format (diff -u) and should be applied with the zero indent level in the spec file (%patch -p0). The only exceptions are the patches obtained from an another primary source site. The original name, suffix, and format is preserved in this case.

Each patch should be compressed with bzip2 if its size is greater than 100kB. The macros %name and %version should be used whenever possible.

Example:

Source:   %{name}-%{version}.tar.bz2
Patch0:   %{name}-%{version}-autoconf.patch
Patch1:   %{name}-%{version}-gcc31.patch

1.16. BuildRoot Tag

This feature should always be used. The preferred path is %{_tmppath}/%{name}-%{version}-build.

1.17. Description Tag

The package description should help the user decide on the right package for the intended purpose without needing to test other similar packages first. This is the right place to inform the user more precisely about a package's functionality. It should contain further information about features and differences from other, comparable packages. If a package could harm a user's installation, the description should contain clear notes on its potential risks or side effects.

The description can contain information about where certain documentation for the package can be found or how an application is best launched, but it should not duplicate any already included package documentation. An exception from this can be made if it helps the user better decide between two similar packages.

The package description should not contain unnecessary information that does not help the user to select the right package, because users tend to ignore long texts. For example, highly detailed information and package history should remain in the package documentation.

The RPM spec file contains only the English version to keep the RPM database small. The localizations are managed by YaST.

1.17.1. Style Guideline

• When referring to the user, use the pronoun "you."
• Avoid contractions, such as "can't" and "isn't."
• Clarity is crucial. Use shorter sentences and simplify the structure to maintain a clear, professional style. Instead of using semicolons, split the sentence in two. If sentences are long or awkward, try rephrasing.
• Avoid use of emotions and "please."
• If-Then is not a grammatical structure. Phrases beginning with if need not be followed by phrases beginning with then.
• Do not capitalize after a colon unless the phrase preceding the colon refers to multiple sentences.
• Avoid use of "etc." It tends to break up the sentence flow. If it is used, it should be followed by a comma except at the end of the sentence. When giving examples, it is not necessary to use "etc." or a replacing structure, because the reader does not expect an example to include all possible items.
• Semicolons (;) are mainly used to join two independent but related sentences. They can also be used in places of commas in a complicated series. It is preferable to avoid them when possible and instead break the text into smaller pieces.
• Avoid "e.g." and "i.e." where possible. Many people do not understand the correct meanings of these abbreviations, so it is best to avoid them. Replace with phrases like "for example" or "such as". If you need to use them, use commas around "e.g.," "i.e.," and "for example" (unless they begin or end the statement. In these cases, use a comma only after or before). For example, this is an example.
• The symbols "/" and "\" are not, under any circumstances, to be used as punctuation.
• Use "so-called" only when the term to which it refers is a nickname or misnomer, not in reference to the correct term. Do not replace with "what is known as" or similar constructions.
• Word List: address book, applet, back-end, Bash (according to GNU Bash manual), boot loader, check box, check mark, command line, deactivate, deselect (verb), dialog, dial-up (not dial-in), double-click, e-mail, filename, file system, formulas, framebuffer, front-end, The GIMP (current project standard), GNOME (current project standard), graphical user interface, graphics card, hard disk.
• Jokes do not travel. Do not use jokes or funny statements, because they are usually only recognized in certain locations and probably confuse others who are not familiar with these local usages.
• "commandline command" is repetitive. "command" is usually a command line–specific term.

1.18. Subpackages

Subpackages are created because:

• Some files are not needed for the base function (optional files) and they are large compared to the size of the main package
• Some files are shared with other packages (shared files)

The name of a subpackage typically consists of:

• The name of the main package
• Some words that characterize the subpackage content

A hyphen (-) is the preferred delimiter between the main package name and the additional words.

For example:

apache.rpm
apache-contrib.rpm
apache-devel.rpm
apache-doc.rpm
apache-example-pages.rpm
apache-testsuite.rpm

At least the following tags for each subpackage must be defined:

• Group
• Summary
• Description

1.19. Provides and Obsoletes Tags

These tags are used when we are renaming, splitting or merging packages. For more information see Package Dependencies.