Home Wiki > openSUSE:Package naming guidelines
Sign up | Login

The english openSUSE wiki has been moved and updated recently. If you encounter any issue, please let us know by mail to admin@opensuse.org.

Revision as of 22:42, 29 July 2016 by Jengelh (talk | contribs) (Handling special version strings)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

openSUSE:Package naming guidelines

tagline: From openSUSE

The openSUSE package naming guidelines will help you to decide how to name your package and your specfile correctly.

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:

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 project 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.
  • should look what 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 the section When Upstream Naming is outside of the specified character set .

Packages enhancing others / plugins

In order for a plugin to be obvious what it serves, the convention is used to first name the package the plugin is FOR, then the literal '-plugin-', followed by the plugins function/name.

e.g: plymouth-plugin-script extends the funtionality of plymouth by means of a plugin offering scripting capabilities.

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 the opensuse-packaging mailing list.

Multiple packages for the same software

For many reasons, it is sometimes advantageous or necessary to keep multiple versions of a package in openSUSE to be installed simultaneously. The following applies both to package source names and names of binary packages, with the exception of shared library binary packages — those have their own guidelines.

When providing multiple versions of a software, the package name should reflect this fact. The package with the most recent version should use the principal name with no versions and all other addons should note their version in the name. There are some exceptions where all packages have a version attached to the package name (e.g. sqlite), i.e. there is no package without version in the name. As you can see, some package names have removed delimiters (e.g. celt051); doing so however leads to somewhat odd names when numbers go beyond an order of magnitude — think celt010 (0.10 or 0.1.0?). Applying the Shared Library Packaging Guidelines's recommendations (replacing delimiters by underscores) is therefore a possible alternative (love-0_7_2).

Examples:

  • simultaneously installable development packages: celt051-devel, libcelt-devel; sqlite2-devel, sqlite3-devel
  • simultaneously installable application software: love-0_7_2, love; autoconf213, autoconf

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 can address your case.

Unusual characters

RPM uses the dash in its expression of package versions to separate the upstream version from the distro-level commit/rebuild counter. This is a sensible choice given that an overwhelming part of all upstream source tarballs use a dot as a separator within their version number. However, a few upstream projects eschew all conventions. Anything that is not an alphanumeric character or a dot should be outright replaced by a dot. Do however consider that an upstream version containing a tilde character is using the tilde versions (prerelease version) scheme mentioned below. If so, the tilde should be retained.

SCM snapshots

When creating tarballs from an SCM repository, use the nearest applicable release version, append a delimiter (often, '+' is used, but '.' is visually pleasant too), a short tag identifying the SCM type and an SCM-specific monotonically increasing identifier. Examples for common applications of this scheme:

Git can express a commit as an offset from a tag to yield a relatively short identifier. For example, if `git describe` outputs v3.14.1-5-g9265358, the rpm version could be set to 3.14.1+git5 or, if more disambiguation is desired, 3.14.1+git5.g9265358. You may need to use `git describe --tags` if the git repository maintainer uses only simple tags rather than annotated tags. If the maintainer provides no git tags, report that shortcoming. In the meantime, an alternative monotonically increasing identifier can be obtained by using the history root as a base (`git rev-list 9265358 | wc -l`), useful for when a project is in such an early stage that there have not been any releases yet (Version: 0~git123).

Subversion has revision numbers which can directly be used. The base version however needs to be determined in other ways. Version: 3.14.1+svn592.

For CVS, a timestamp seems the shortest unambiguous (to the developer, at least) snapshot identifier because all files have their own revision tree. Version: 3.14.1+cvs20130621.

Pre-Release packages

Pre-release versions using the same version number as the final releases need some additional care. Different developers have different ideas about how to name their preleasess; "1.8b" could indicate either 1.8 beta that comes before 1.8, or it could indicate a release actually made after 1.8. As such, package utilities (correctly so) make no effort to special-case “alpha”, “beta”, “a”, “b”, or any other name for that matter, and usually sort by longest string such that "1.8" comes before "1.8b". A distro package maintainer is to tweak the Version: field in the .spec file in accordance with the sort order provided by our utilities. There are a number of ways to choose from, but pick one only. In the order of descending preference (= pick the first that is applicable), they are:

  • Some upstreams assign their prereleases sortable numbers (that no other normal release will obtain). For example, sssd-1.8.0beta2.tar.gz is defined to be “1.7.92”. Use Version: 1.7.92.
  • Use “tilde versions”. The spec's Version: field may contain a tilde as a special marker that sorts before anything else, including the end-of-string, that is, "1.8~" < "1.8". This feature is available starting from rpm-4.10 (and was backported into openSUSE 12.2's rpm 4.9.1). Use: Version: 1.8.0~beta2. Tildes can be used multiple times, should it really become necessary.
  • For the final release, choose a version string that sorts after the upstream final but before any future release. (Choices are indeed limited.) Version: 1.8.0.beta2 for the prerelease, Version: 1.8.0.0 for the final. This relies on the property that RPM sorts A–Z before 0–9. As you have noticed, rpm does not bluntly sort by ASCII value, and so, this variant may not necessarily work with non-RPM systems, should you plan to build for them too using OBS.
  • For the prerelease, choose a version that sorts before the final but after any potential future releases in the series, and use it to prefix the actual version. Version: 1.7.99_1.8.0beta2 for the prerelease, Version: 1.8.0 for the final.
  • Bumping the Epoch: field. Note that openSUSE discourages and does not use epochs, one reaosn being that zypper can actually handle downgrades (unlike yum, presumably) with `zypper dup` and `zypper in`. In fact, Epoch is considered harmful, citing the Maximum RPM book:

Solution Number 2: Just Say No! If you have the option between changing the software's version-numbering scheme, or using epoch numbers in RPM, please consider changing the version-numbering scheme. Chances are, if RPM can't figure it out, most of the people using your software can't, either.


Do not attempt to abuse the rpm Release: tag for version information either. It is the wrong field to convey this information, and the Open Build Service will by default overwrite Release: anyway with checkin and build counters.

Post-Release packages

By and large, post releases generally pose no problem because upstreams generally version them such that they follow final releases.

If upstream is using delimiters from the permitted character set, then just reuse that for the version string. Otherwise replace them by something permitted.

  • openssl-0.9.8p: Version: 0.9.8p
  • suse-11-GA1: Version: 11.GA1 # GA=General Availability

Again, letter strings that only have meaning to humans (like GA here) may need to be prefixed by something like a number that helps ordering them the way upstream intended if the natural order of A–Z is not sufficient. Assuming FUBAR comes after GA, then

  • suse-11-GA1: Version: 11+0.GA1
  • suse-11-FUBAR1: Version: 11+1.FUBAR1

would be a workable solution. You will notice '+' was chosen here by the wiki page editor instead of '.' as a delimiter here, for reason to avoid somewhat ambiguous versions (11.0.GA1 could either be interpreted as 11.0+GA1 or 11+0.GA1).

For prereleases to postreleases, simply use the tilde mechanism as described above (“openssl-0.9.6q~betaX”).

Renaming/replacing existing packages

Described in Package dependencies: Renaming a package.

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)