openSUSE:Package naming guidelines
Common Character Set for Package Naming
RPM limits package names to ASCII plus a few punctuation characters. Of those, '{}%' are also not usable due to bugs in rpm-4.18 and obs-build-20230502. Ultimately, the set of acceptable characters for package names in openSUSE is:
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. Two exceptions regarding the principal name are currently known:
- gcc/gcc33/gcc8: The unversioned package name is a meta package and selects another package of a specific version for the default install.
- ffmpeg-4: All instances of ffmpeg have a number, there is no unversioned name. This was deemed useful for synchronization with Leap updates (for packages where security issues are frequent and patch backports will generally not be attempted)
Because some package names may have a digit as part of the upstream name (think clanbomber2), the Shared Library Packaging Guidelines's recommendations should be applied, that is, a dash as a delimiter and replacing other delimiters by underscores (e.g. the love-0_7_2 package).
There exist a number of historic package names which, due to lack of delimieters, are ambiguous, e.g. gcc33, celt051.
Example naming choices:
- when development packages need to be present in multiple versions: wxWidgets-3_0-devel
- when a program needs to be present in multiple versions: love-0_7_2, love, ffmpeg-3, ffmpeg-4
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.
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)