Copyright © 2004, 2005 SUSE LINUX AG, Nuernberg, Germany
The document is distributed under the terms of the GNU Free Documentation License.
| Revision History | |
|---|---|
| Revision 1.0 | 7th January, 2005, 16:26 |
Table of Contents
This document defines the style of SUSE's packages and describes SUSE-specific extensions that can and should be used in packages for SUSE products. The purpose of this document is not to teach anyone how to create a RPM package; the object is to describe SUSE-specific things. It also defines the method to use where multiple options exist and consistency is preferred. The assumption is that the reader is experienced in creating RPM packages. He should then be able to create packages that conform to SUSE specifications with help of this document.
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.
The SUSE spec files start with some standardized initial comments:
# # spec file for package PackageName (Version PackageVersion) # # Copyright (c) 2003 SuSE Linux AG, Nuernberg, Germany. # This file and all modifications and additions to the pristine # package are under the same license as the package itself. # # Please submit bug fixes or comments via http://www.suse.de/feedback/ #
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 starting with:
# neededforbuild
defines extra build dependencies for the package. It determines what extra packages must be installed in addition to a default set of packages to be able to build it. The BuildRequires tag is updated from it when the package is built inside SUSE. The line has no effect when building outside. It is used by SUSE package maintainers to simply define build dependencies.
Next to the real names of packages, there could be some predefined names of meta packages, like kde3-devel-packages. The meta package either represents a universal name of a package whose name could differ on various products or it represents a group of real packages. The list of packages finally used for build are mentioned in the BuildRequires tag.
This tag defines packages that must be installed to build the package. It is automatically generated from the line neededforbuild when the package is built inside SUSE. It has been used instead of the line usedforbuild since SL 9.1.
The line starting with:
# usedforbuild
mentions all packages used to build the package. It has been made obsolete by the BuildRequires tag since SL 9.1.
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:
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, so is defined only by a text, the standardized text "Other License(s), see package" is used.
Examples:
License: GPL License: Public domain, Freeware License: Other License(s), see package License: LGPL, Other License(s), see package
The full list of available RPM groups and their descriptions can be found in Section 2, “RPM Groups”.
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 must use the option --force.
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:
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.
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.
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.
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.
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
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.
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.patchThis feature should always be used. The preferred path is %{_tmppath}/%{name}-%{version}-build.
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.
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.
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