WikiSponsors
openSUSE:Package naming guidelines
tagline: From openSUSE
- Build Service cross distribution howto
- Build Service Tips and Tricks
- Build Service Tutorial
- Creating a changes file (RPM)
- Java jpackage-utils
- Java RPM Macros
- Package group guidelines
- Package naming guidelines
- Package security guidelines
- Packaging checks
- Packaging Conventions RPM Macros
- Packaging desktop menu categories
- Packaging Fonts
- Packaging Games
- Packaging Go
- Packaging guidelines change process
- Packaging Haskell
- Packaging init scripts
- Packaging Java
- Packaging Lua
- Packaging Multiple Version guidelines
- Packaging Patches guidelines
- Packaging Perl
- Packaging PHP
- Packaging Python
- Packaging Ruby
- Packaging scriptlet snippets
- Packaging wxWidgets
- Ruby Gem Strategies
- Shared library packaging policy
- Specfile guidelines
- Systemd packaging guidelines
- Packaging guidelines
Contents |
Common Character Set for Package Naming
While openSUSE is an international community, for consistency and usability, there needs to be a common character set for package naming.
Specifically, all openSUSE packages must be named using only the following ASCII characters. These characters are displayed here:
abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ 0123456789-._+
When Upstream Naming is outside of the specified character set
openSUSE recognizes that the task of converting text to the specified ASCII character set (aka transliteration) is difficult. Accordingly, when the upstream name is outside of the specified ASCII character set, the openSUSE package maintainer should first contact the upstream for that software and ask them for a transliteration of the name for openSUSE to use.
If (and only if) the upstream is unable, unwilling, or unavailable to provide a transliterated name, the openSUSE packager must choose to either perform their own transliteration, or withdraw the package from consideration in openSUSE.
When deciding how to transliterate a package name, the openSUSE packager should look to see what (if any) other distributions have done for that package's name, and take that into account.
Transliterated packages may Provide: the original, non-transliterated name, but are not required to do so.
General Naming
When naming a package, the name should match the upstream tarball or project name from which this software came. In some cases, this naming choice may be more complicated. If this package has been packaged by other distributions/packagers in the past, then you should try to match their name for consistency. In any case, try to use your best judgement, and other developers will help in the final decision.
Additionally, it is possible that the upstream name does not fall into the Common Character Set . If this is the case, refer to: When Upstream Naming is outside of the specified character set .
Separators
When naming packages for openSUSE, the maintainer must use the dash '-' as the delimiter for name parts. The maintainer must NOT use an underscore '_', a plus '+', or a period '.' as a delimiter.
There are a few exceptions to the no underscore '_' rule.
- httpd, pam, and SDL addon packages are excluded, refer to " Addon Packages (httpd, pam and SDL) ".
- packages that are locale specific, and use the locale in the name are excluded, refer to " Addon Packages (locale) ".
- packages where the upstream name naturally contains an underscore are excluded from this.
Examples of these packages include:
java_cup libart_lgpl microcode_ctl nss_ldap sg3_utils
If in doubt, ask on opensuse-packaging mailing list list.
Multiple packages with the same base name
For many reasons, it is sometimes advantageous to keep multiple versions of a package in openSUSE to be installed simultaneously. When doing so, the package name should reflect this fact. One package should use the base name with no versions and all other addons should note their version in the name. There are some exceptions where all packages have version attached to the package name (i.e. there is no package without version in the name).
Examples:
autoconf or sqlite occasionally have multiple versions in openSUSE for backwards compatibility.
The most current version of autoconf has Name: autoconf
The older 2.1.3 version of autoconf has Name: autoconf213
The packages for 3.x series of sqlite have Name: sqlite3 and Name: sqlite3-devel
The packages for 2.x series of sqlite have Name: sqlite2 and Name: sqlite2-devel
Note that we do not use delimiters in the name in this situation, we remove the period '.' from the version number and attach it to the name.
The special case which is treated differently are shared libraries. There is a separate Shared library packaging policy describing how to handle them.
Case Sensitivity
In openSUSE packaging, the maintainer should use his/her best judgement when considering how to name the package. While case sensitivity is not a mandatory requirement, case should only be used where necessary. Keep in mind to respect the wishes of the upstream maintainers. If they refer to their application as "ORBit", you should use "ORBit" as the package name, and not "orbit". However, if they do not express any preference of case, you should default to lowercase naming.
The exception to this is for perl module packaging. The CPAN Group and Type should be capitalized in the name, as if they were proper nouns . (Refer to Addon Packages (perl modules) for details.)
Spec file name
The spec file should be named using the %{name}.spec scheme. If your package is named foo-1.0-1.src.rpm, then the spec file should be named foo.spec.
Handling special version strings
The Version should follow the upstream tarball version.
If this is not possible, please check if one of the solutions below fix your problem.
Versions containing non-digit characters
There are three cases in which non-numeric versions occur in the Version field:
- Snapshot packages
- Pre-release packages
- Post-release packages
Snapshot packages
Snapshot packages contain data about where the snapshot came from as well as ordering information for rpm. The information about the snapshot will be called %{checkout} in this section.
%{checkout} consists of the date that the snapshot is made in YYYYMMDD format, a short (2-5 characters) string identifying the type of revision control system or that this is a snapshot, and optionally, up to 13 characters (ASCII) alphanumeric characters that could be useful in finding the revision in the revision control system.
For instance, if you create a snapshot from a git repository on January 2, 2013 with git hash 9e88d7e9efb1bcd5b41a408037bb7cfd47220a64, %{checkout} string could be any of the following:
20130102snap 20130102git 20130102git9e88d7e
To indicate you're working on way-outdated-version + git changes on top, we usually propose the following in spec files:
Version: $VERSION+git.$TIMESTAMP.$COMMITSHA1
This usually breaks the "13 characters limit" - but there is currently not really a better way to handle this.
You can even auto-fetch from git with source services, check Cloud:OpenStack:Master / openstack-utils as an example. The "tar_scm" source service does just that, pull from git and dump a tarball. The version string is configurable but can also be generated from the fetched commit + latest parent tag (that's what @PARENT_TAG@ does).
The "recompress" service creates a *.tar.gz file.
Lastly, the "set_version" services patches the spec file Version: preamble tag.
If the snapshot package is considered a "pre-release package", you should follow the guidelines listed in Pre-Release Packages for snapshot packages, using the %{checkout} that you decide on above. (For instance, in kismet-0.0.3.20040204svn, 20040204svn is the %{checkout})
If the snapshot is a "post-release package", you should follow the guidelines in the Post-Release Packages section. Where the %{posttag} in that section is the %{checkout} string you decided on above.
Example (post-release cvs):
kismet-1.0-1 (this is the formal release of kismet 1.0)
kismet-1.0-2 (this is a bugfix build to the 1.0 release)
kismet-1.0-3.20050515cvs (move to a post-release cvs checkout)
kismet-1.0-4.20050515cvs (bugfix to the post-release cvs checkout)
kismet-1.0-5.20050517cvs (new cvs checkout, note the increment of %{X})
Pre-Release packages
Non-numeric versioned "pre-release" packages can be problematic so they must be treated with care. These are cases where the upstream "pre-release" version has letters rather than simple numbers in their version. Often they have tags like alpha, beta, rc, or letters like a and b denoting that it is a version before the "final" number. Unfortunately, we cannot simply put these letters into the version tag, so we'll use the Release field for this.
Release Tag for Pre-Release Packages:
0.%{X}.%{alphatag}
Where %{X} is the release number increment, and %{alphatag} is the string that came from the version.
In this case, the period '.' should be used as the delimiter between the release number increment, and the non-numeric version string. No other extra characters should appear in the Release field. This is to prevent Release values such as "3jpp_2fc.42-spotwashere".
| Source Archive | Description |
|---|---|
mozilla-1.4a.tar.gz |
(this is a pre-release, version 1.4a of mozilla) |
mozilla-1.4.tar.gz |
(this is what the 1.4 release will actually look like) |
| Release Tag | Explanation |
mozilla-1.4-0.1.a |
(so, this is the acceptable Fedora %{name}-%{version}-%{release})
|
mozilla-1.4-1 |
(and this is what the 1.4 release Fedora %{name}-%{version}-%{release} should be)
|
| Source Archive | Description |
|---|---|
alsa-lib-0.9.2beta1.tar.gz |
(this is a beta release of alsa-lib, version 0.9.2beta1) |
| Release Tag | Explanation |
alsa-lib-0.9.2-0.1.beta1 |
(this is the correct Fedora %{name}-%{version}-%{release})
|
alsa-lib-0.9.2-0.2.beta1 |
(this is an incremented Fedora %{name}-%{version}-%{release}. Note that the first 0 is not incremented.)
|
| Release Tag | Explanation |
|---|---|
kismet-0-0.1.20040110svn |
(this is a pre-release, svn checkout of kismet) |
kismet-0-0.2.20040110svn |
(this is a bugfix to the previous package) |
kismet-0-0.3.20040204svn |
(this is a new svn checkout, note the increment of %{X})
|
kismet-1.0-1 |
(this is the formal release of kismet 1.0) |
| Release Tag | Explanation |
|---|---|
mozilla-1.4-0.1.a |
(this is the Fedora package for 1.4a, as above) |
mozilla-1.4-0.2.a |
(this is the first patch on top of 1.4a) |
mozilla-1.4-0.3.a |
(this is another new patch on top of 1.4a) |
mozilla-1.4-0.4.b |
(this is the first build after upgrade to 1.4b) |
mozilla-1.4-0.5.b |
(this is a new patch on top of 1.4b) |
mozilla-1.4-1 |
(this is after moving to 1.4 "final", and to a normal version) |
mozilla-1.4-2 |
(this is a new patch on top of 1.4 "final") |
| Release Tag | Explanation |
|---|---|
alsa-lib-0.9.2-0.1.beta1 |
(this is the Fedora package for 0.9.2beta1, as above) |
alsa-lib-0.9.2-0.2.beta1 |
(this is a new patch on top of 0.9.2beta1) |
alsa-lib-0.9.2-0.3.beta2 |
(this is after upgrading to 0.9.2beta2) |
alsa-lib-0.9.2-0.4.beta3 |
(this is after upgrading to 0.9.2beta3) |
alsa-lib-0.9.2-0.5.beta3 |
(this is a new patch on top of 0.9.2beta3) |
alsa-lib-0.9.2-0.6.rc1 |
(this is after upgrading to 0.9.2rc1) |
alsa-lib-0.9.2-0.7.rc2 |
(this is after upgrading to 0.9.2rc2) |
alsa-lib-0.9.2-1 |
(this is after upgrading to 0.9.2 "final", version becomes normal) |
alsa-lib-0.9.2-2 |
(this is a new patch on top of 0.9.2 "final") |
Post-Release packages
Like pre-release packages, non-numeric versioned "post-release" packages can be problematic and also must be treated with care. These fall under two generic categories:
- Properly ordered simple versions. These are usually due to quick bugfix releases, such as openssl-0.9.6b or gkrellm-2.1.7a. As new versions come out, the non-numeric tag is properly incremented (e.g. openssl-0.9.6c) or the numeric version is increased and the non-numeric tag is dropped (openssl-0.9.7). In this case, the non-numeric characters are permitted in the Version: field.
- When upstream uses versions that attempt to have meaning to humans instead of being easy for a computer to order. For example, GA1, CR2, PR3. In this case, the non-numeric string can be put in the Release: field using the following syntax:
%{X}.%{posttag}
In this syntax, %{X} is the release number increment, and %{posttag} is the string that came from the version. Here, the period '.' should be used as the delimiter between the release number increment, and the non-numeric version string. No other extra characters should appear in the Release field.
Example (complicated post-release):
foo-1.1.0-0.1.BETA (this is a prerelease, first beta) foo-1.1.0-0.2.BETA1 (this is a prerelease, second beta) foo-1.1.0-0.3.BETA2 (this is a prerelease, third beta) foo-1.1.0-0.4.CR1 (this is a prerelease, candidate release 1) foo-1.1.0-0.5.CR2 (this is a prerelease, candidate release 2) foo-1.1.0-1 (final release) foo-1.1.0-2.GA1 (post release, GA1) foo-1.1.0-3.CP1 (post release, CP1, after GA1) foo-1.1.0-4.CP2 (post release, CP2, after CP1) foo-1.1.0-5.SP1 (post release, SP1, after CP2) foo-1.1.0-6.SP1_CP1 (post release, SP1_CP1, after SP1)
It is important to be careful with the post-release scheme, to ensure that package ordering is correct. It may be necessary to use Epoch to ensure that the current package is considered newer than the previous package. In such cases, the packager should try to convince upstream to be more reasonable with their post-release versioning.
Also, packagers using the post-release scheme should put a comment in their spec file with a brief description of the upstream conventions for naming/versioning that are being worked around.
Renaming/replacing existing packages
In the event that it becomes necessary to rename or replace an existing package, the new package should make the change transparent to end users to the extent applicable. If a package is being renamed without any functional changes, or is a compatible enough replacement to an existing package (where "enough" means that it includes only changes of magnitude that are commonly found in version upgrade changes), provide clean upgrade paths and compatibility with:
Provides: oldpackagename = %version Obsoletes: oldpackagename < 1.0
If a package supersedes/replaces an existing package without being a compatible enough replacement as defined in above, use only the Obsoletes from above.
Example
- walkman being renamed to ipod
- ipod is compatible with walkman
- the last walkman package version was walkman-1.4
This should be the content of ipod.spec
Provides: walkman = %{version}
Obsoletes: walkman < 1.4
The Provides should be assumed to be deprecated and short lived and removed in the distro release after the next one. For packages that are not usually pulled in by using the package name as the dependency such as library only packages (which are pulled in through library soname depenencies), there's usually no need to add the Provides.
Documentation SubPackages
Large documentation files should go in a subpackage. This subpackage must be named with the format: %{name}-doc .
The definition of large is left up to the packager's best judgement, but is not restricted to size. Large can refer to either size or quantity.
Addon Packages (General)
If a new package is considered an "addon" package that enhances or adds a new functionality to an existing openSUSE package without being useful on its own, its name should reflect this fact.
The new package ("child") should prepend the "parent" package in its name, in the format: %{parent}-%{child}.
Examples:
gnome-applet-netmon (netmon applet for gnome, relies on gnome) php-adodb (adodb functionality for php, relies on php) python-twisted (the twisted module for python, relies on python) xmms-cdread (direct cd read functionality for xmms, relies on xmms)