Packaging/NamingGuidelines/ja

From FedoraProject

Jump to: navigation, search

Contents

パッケージ名ガイドライン

Author: Tom 'spot' Callaway
Revision: 0.52
Initial Draft: Wednesday Feb 23, 2005
Last Revised: Tuesday, Apr 14, 2009


パッケージ名のための共通文字セット

Fedora は国際的なコミュニティではあるものの、一貫性とユーザビリティのためにパッケージ名に共通文字セットを使用する必要があります。

仕様として、全ての Fedora パッケージは次の ASCII 文字のみを使用して名前を付けなければなりません。使用できる文字セットを表示します。

abcdefghijklmnopqrstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ
0123456789-._+

名前全般

パッケージに名前を付けるとき、その名前はこのソフトウェアを開発しているアップストリームの tarball 又はプロジェクト名と一致させるべきです。場合によっては、この名前の選択はちょっと複雑になります。もしこのパッケージが過去に他のディストリビューション/パッケージャによってパッケージングされているなら、一貫性のために同じ名前を付けるように取り組むべきです。どのような状況でも、あなたが最善の判断を行うようにして、最終的な決定は他の開発者が助けてくれます。

さらにアップストリームの名前は共通文字セットに該当しない可能性もあります。そういった場合はアップストリームの名前が指定文字セット以外の文字を使用しているときを参照してください。

セパレータ

Fedora のパッケージ名を考えるとき、メンテナは名前の区切り文字としてダッシュ '-' を使用しなければなりません。メンテナは区切り文字としてアンダースコア '_'、プラス '+'、ピリオド '.' を使用してはいけません。

アンダースコア '_' に関しては少し例外ルールがあります。

  • アップストリームの名前に自然にアンダースコアが含まれるパッケージは除外されます。例えば、次のようなパッケージ名です。
arptables_jf
dhcpv6_client
java_cup
knm_new
libart_lgpl
lm_sensors
microcode_ctl
nss_db
nss_ldap
sg3_utils
tcp_wrappers

もし疑問に感じたら fedora-devel-list で尋ねてください。

アップストリームの名前が指定文字セット以外の文字を使用しているとき

Fedora は指定された ASCII 文字セット(書き直しとも呼ばれる)へテキストを変換する作業が難しいことを認識しています。それに応じて、アップストリームの名前が指定文字セット以外を使用しているとき、Fedora パッケージメンテナは先ずアップストリームへ連絡して Fedora で使用できる名前へ書き直してもらうようにお願いしてください。

もしアップストリームで名前を書き直すことが不可能なら、不本意ではあるものの、書き直された名前で提供することができません。Fedora パッケージャは自分で名前を書き直すか、そのパッケージを Fedora へ含めることを辞退するかを選択しなければなりません。

パッケージ名の書き直し方法を決定するときは Fedora パッケージャは他のディストリビューションがそのパッケージ名をどうしているかを調べるべきです。そして、その名前を候補として考慮に入れてください。

追加の Provides

書き直されたパッケージは "Provide: オリジナルの書き直していない名前" を行う方が良いかもしれませんが、義務付けされているわけではありません。

パッケージ名の競合

Conflicting package names, even if they differ by case alone, are not allowed. Please see Packaging:Conflicts#Conflicting Package Names for more details.

同じベース名を持つ複数のパッケージ

For many reasons, it is sometimes advantageous to keep multiple versions of a package in Fedora 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.

Example:
openssl occasionally has multiple versions in Fedora for backwards compatibility.
The most current version of openssl has Name: openssl
The previous version of openssl has Name: openssl096b
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.

組み込み OS バージョンのドキュメントパッケージ

Documentation packages (as approved by the Fedora Documentation Project) can be named with the OS version number in the package name to allow parallel installation of multiple versions, in cases where the documentation is specific to a release of Fedora and there is value in having multiple versions simultaneously installed.

spec ファイル名

The spec file should be named using the %{name}.spec scheme. This is to make it easier for people to find the appropriate spec when they install a src.rpm.

Example:

If your package is named foo-1.0.0-1.src.rpm, then the spec file should be named foo.spec.

There is normally no need to include the %{version} in the spec file name. If you are packaging multiple versions of a package for simultaneous use, they should already reflect the version in the %{name}.spec scheme (refer to Multiple Packages with the same base name for details). In normal cases adding the version can cause the spec file's history to be lost when a package's version is upgraded.

As a special exception, there are a few packages which are allowed to have a version in their spec filename. This is because they had the version in their name when they were merged from Fedora Core's cvs and removing the version at that time would have *lost* history:

  • gcc
  • [Please ask the packaging committee to add your package if you think it should also fall under this exception.]

This exception will go away when any of the following criteria are met: 1. We move the packages to a revision control system which is able to preserve history across a file rename. 1. The package spec file is going to be renamed anyway (for example, gcc41.spec is currently in cvs. When gcc is upgraded to gcc-4.2, the new spec will be created as gcc.spec not gcc42.spec)


パッケージバージョン

The Version field in the spec is where the maintainer should put the current version of the software being packaged. If the version is non-numeric (contains tags that are not numbers), you may need to include the additional non-numeric characters in the release field.

There are four cases where the version contains non-numeric characters:

  • Pre-release packages: Packages released as "pre-release" versions, prior to a "final" version. Example tags include "alpha", "beta", "rc", "cvs". Unfortunately, we cannot simply put these letters into the version tag, so we use the Release field for this. Details can be found here: Non-Numeric Version in Release
  • Post-release packages: Packages released after a "final" version. These packages contain the same numeric version as the "final" version, but have an additional non-numeric identifier. Details can be found here: Non-Numeric Version in Release
  • Snapshot packages: Packages built from cvs or subversion snapshots. These packages could be either "pre" or "post" release packages. Details can be found here: Non-Numeric Version in Release
  • JPackage derived Fedora packages: Packages which derive from JPackage RPMS follow a special policy. Details can be found here: JPackagePolicy

パッケージリリース

In the past, Fedora.us used 0.fdr as a release prefix to identify Fedora.us packages. In Fedora, this repository "tagging" is unnecessary, and should not be used. The release number (referred to in some older documentation as a "vepoch") is how the maintainer marks build revisions, starting from 1. When a minor change (spec file changed, patch added/removed) occurs, or a package is rebuilt to use newer headers or libraries, the release number should be incremented. If a major change (new version of the software being packaged) occurs, the version number should be changed to reflect the new software version, and the release number should be reset to 1.

リリース番号の数字以外のバージョン

There are three cases in which non-numeric versions occur in the Release field:

  • Pre-release packages
  • Snapshot packages
  • Post-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".

Example (pre-release):

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)
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)

Example (pre-release):

alsa-lib-0.9.2beta1.tar.gz (this is a beta release of alsa-lib, version 0.9.2beta1)
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.)

Example (pre-release svn checkout):

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)

Upgrade Path Example (mozilla):

mozilla-1.4-0.1.a (add a new patch on top of 1.4a)
mozilla-1.4-0.2.a (add another new patch on top of 1.4a)
mozilla-1.4-0.3.a (upgrade to 1.4b)
mozilla-1.4-0.4.b (add a new patch on top of 1.4b)
mozilla-1.4-0.5.b (move to 1.4 "final" version, and to a normal version)
mozilla-1.4-1 (add a new patch on top of 1.4 "final")
mozilla-1.4-2

Upgrade Path Example (alsa-lib):

alsa-lib-0.9.2-0.1.beta1 (add a new patch on top of 0.9.2beta1)
alsa-lib-0.9.2-0.2.beta1 (upgrade to 0.9.2beta2)
alsa-lib-0.9.2-0.3.beta2 (upgrade to 0.9.2beta3)
alsa-lib-0.9.2-0.4.beta3 (add a new patch on top of 0.9.2beta3)
alsa-lib-0.9.2-0.5.beta3 (upgrade to 0.9.2rc1)
alsa-lib-0.9.2-0.6.rc1 (upgrade to 0.9.2rc2)
alsa-lib-0.9.2-0.7.rc2 (upgrade to 0.9.2 "final", version becomes normal)
alsa-lib-0.9.2-1 (add a new patch on top of 0.9.2 "final")
alsa-lib-0.9.2-2

スナップショットパッケージ

If a snapshot package is considered a "pre-release package", you should follow the guidelines listed in Pre-Release Packages , and use an %{alphatag} beginning with the date in YYYYMMDD format and followed by up to 16 (ASCII) alphanumeric characters of your choosing. The date should reference the date the checkout was taken; the rest can be as simple as "cvs" or "snap", or a subversion change number like "svn12345" or an abbreviated git hash like "git5aef11739b".

If a snapshot package is considered a "post-release package", the following applies:

Release Tag for Post-Release Snapshot Packages: %{X}.%{alphatag}

Where %{X} is the build number from any previous "stable" package build, incremented by one (if no previous stable package build, use 1), and %{alphatag} is the checkout string, as described 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})

ポストリリースパッケージ

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.

 %{?dist} タグを使用する

If you wish to use a single spec file to build for multiple distributions, you can use the %{?dist} tag in the Release field. Please refer to the Packaging:DistTag documentation for the details on the appropriate way to do this.

古いブランチのためのマイナーリリース

Sometimes, you may find yourself in a situation where an older branch needs a fix, but the newer branches are fine. For example, if foo = 1.0-1%{?dist} in FC-4 and FC-5, and only FC-4 needs a fix. Normally, you would need to bump the release in each of the branches to ensure that FC-4 < FC-5, but that is a waste of time and energy for the newer branches which do not need to be touched.

In this case, you can add an extra digit (prefixed by a period) to the very end of the release tag in the FC-4 branch, instead of bumping it the usual way. Example:


Release: 1%{?dist}

Release: 1%{?dist}.1

This will make a foo-1.0-1.fc4.1 package, which is still less than the foo-1.0-1.fc5 package in the FC-5 branch.

As necessary, the last digit (the minor release bump) can be incremented on a per-branch basis as needed.
This is ONLY permitted if you are using disttags in your Release field.

BE CAREFUL WITH THIS! You always want to make sure that packages in branches can be upgraded to packages in more recent branches. Or to put it simply, FC-4 < FC-5 < FC-6. There is a tool in the rpmdevtools package called rpmdev-vercmp. This tool will prompt you for two sets of Epoch, Version, and Release, then tell you which is considered newer by rpm.


大文字と小文字の区別

In Fedora 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.)

既存パッケージのリネーム/置き換え

Note.png
FESCo Policy
FESCo has a package renaming policy that should be followed when renaming an existing package.

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 = $provEVR
Obsoletes: oldpackagename < $obsEVR

$provEVR refers to an (Epoch-)Version-Release tuple the original unchanged package would have had if it had been version or release bumped, using macros. $obsEVR is an (Epoch-)Version-Release tuple arranged so that there is a clean upgrade path, but without gratuitously polluting the version space upwards, usually not using macros.

If a package supersedes/replaces an existing package without being a compatible enough replacement as defined in above, use only the Obsoletes from above.

If the provided package had an Epoch set, it must be preserved in both the Provides and Obsoletes. It may and should be removed from the actual new package.

Example: foo being renamed to bar, bar is compatible with foo, and the last foo package release being foo-1.0-3%{?dist} with Epoch: 2; add to bar (and similarly for all subpackages as applicable):

Version: 1.0
Release: 4%{?dist}
Provides: foo = 2:%{version}-%{release}
Obsoletes: foo < 2:1.0-4

If there is no standard naming for a package or other long term naming compatibility requirements involved with the rename, the Provides should be assumed to be deprecated and short lived and removed in the distro release after the next one (ie. if introduced in FC-X, keep in all subsequent package revisions for distros FC-X and FC-(X+1), drop in FC-(X+2)), and the distro version where it is planned to be dropped documented in a comment in the specfile. Maintainers of affected packages should be notified and encouraged to switch to use the new name. Forward compatibility Provides: in older distro branches can be considered in order to make it possible for package maintainers to keep same simple specfiles between branches but still switch to the newer name.

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. Note however that the -devel subpackages of lib packages are pulled in as build dependencies using the package name, so adding the Provides is often appropriate there.

ドキュメントサブパッケージ

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.

フォントパッケージ

Packages containing fonts must be named [foundryname-]projectname[-fontfamilyname]-fonts, in lowercase. For a full explanation, see Packaging/FontsPolicy#Naming.

アドオンパッケージ (一般)

If a new package is considered an "addon" package that enhances or adds a new functionality to an existing Fedora 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)

There are some exceptions to this general addon package naming policy, and they are noted below.

アドオンパッケージ (httpd, pam や SDL)

Packages that rely on Apache httpd, pam, or SDL as a parent use a slightly different naming scheme. pam and SDL addons use the format: %{parent}_%{child}, with an underscore "_" as a delimiter. Apache httpd addons use the format: mod_%{child}, with an underscore "_" as a delimiter. This naming scheme is usually the same as used for the source tarball name.

Examples:

mod_perl (perl components for Apache httpd, relies on httpd)
pam_krb5 (krb5 components for pam, relies on pam)
SDL_gfx (Additional graphics components for SDL, relies on SDL)
SDL_ttf (TrueType font rendering support for SDL, relies on SDL)

アドオンパッケージ (Eclipse プラグイン)

Eclipse plugin packages MUST be named eclipse-<projectname>. For example, a package of the anyedit plugin for Eclipse would by named eclipse-anyedit.

アドオンパッケージ (emacs コンポーネント)

Packages of emacs add-on components (code that adds additional functionality to emacs compatible editors) have their own naming scheme. It is often the case that a component will add functionality to several different compatible editors, such as GNU Emacs and XEmacs (and possibly development versions of these editors). The package name should take into account the upstream name of the emacs component.

Where a component adds functionality to more than one emacs compatible editor, the package name should be of the form emacs-common-$NAME. In this case, the main package should contain only files common to all emacs compatible editors, and the code specific to each should be placed in a subpackage reflecting the specific editor $EDITOR-$NAME eg. xemacs-$NAME, emacs-$NAME (the latter being the package specific to GNU Emacs). An example of this scheme can be found in the package emacs-common-muse.

Where a component is designed to add functionality to only a single emacs compatible editor, the main package name should reflect this by being called $EDITOR-$NAME. An example of this situation can be found in the package emacs-auctex, which is built only for GNU Emacs.


Examples:

emacs-common-muse (muse component for all emacs compatible editors)
xemacs-muse (muse component subpackage that provides XEmacs specific files)
emacs-autex (autex component only for GNU Emacs)

アドオンパッケージ (erlang モジュール)

Packages of erlang modules (thus they rely on erlang as a parent) have their own naming scheme. They should take into account the upstream name of the erlang module. This makes a package name format of erlang-$NAME. When in doubt, use the name of the module that you use when importing it into a script.

Example:

erlang-esdl (erlang module named esdl)

アドオンパッケージ (OCaml モジュール)

OCaml modules, libraries and syntax extensions should be named ocaml-foo. Examples include: ocaml-extlib, ocaml-ssl.

This naming does not apply to applications written in OCaml, which can be given their normal name. Examples include: mldonkey, virt-top, cduce.

アドオンパッケージ (OpenOffice.org 拡張)

Packages of OpenOffice.org extensions (thus they rely on OpenOffice.org as a parent) have their own naming scheme. They must take into account the upstream name of the OpenOffice.org extension. This makes a package name format of openoffice.org-$NAME.

アドオンパッケージ (perl モジュール)

Packages of perl modules (thus they rely on perl as a parent) use a slightly different naming scheme. They should be named perl-CPANDIST where CPANDIST is the name of the packaged CPAN module distribution (which is almost always also the unit of perl module packaging). In the rare cases when a CPAN module distribution needs to be split into smaller subpackages eg. due to dependencies, the extra subpackages should be named perl-CPANDIST-Something.

Examples:

perl-Archive-Zip (Archive-Zip is the CPAN distribution name)
perl-Cache-Cache (Cache-Cache is the CPAN distribution name)

アドオンパッケージ (php モジュール)

For details on the PHP naming scheme, see Packaging/PHP#NamingScheme .

アドオンパッケージ (python モジュール)

Packages of python modules (thus they rely on python as a parent) use a slightly different naming scheme. They should take into account the upstream name of the python module. This makes a package name format of python-$NAME. When in doubt, use the name of the module that you type to import it in a script.

Examples:

python-psycopg  (python module named psycopg)
python-simpletal (python module named simpletal)
python-tpg (python module named tpg)

There is an exception to this rule. If the upstream source has "py" (or "Py") in its name, you can use that name for the package. So, for example, pygtk is acceptable.

アドオンパッケージ (python3 モジュール)

An rpm with a python prefix or suffix means a python2 rpm so we need a different prefix to denote python3 packages. For this, we use python3. We have two constraints that the python2 packages don't operate under:

  1. We need to be clear about these modules being for python3 so we don't have an exception for packages that already have "py" in their names like python2 modules.
  2. Consumers of the packages need to be able to find them even if they don't know whether they're using the python2 or python3 version.

So all python3 modules MUST have python3 in their name. Other than that, the module must be in the same format as the python2 package. Some examples:

Fedora python 2 package Upstream name Fedora Python 3 package name
python-lxml lxml python3-lxml
pygtk2 pygtk python3-pygtk
gstreamer-python gst-python gstreamer-python3
gnome-python2 gnome-python gnome-python3
rpm-python (part of rpm) rpm-python3


アドオンパッケージ (R モジュール)

Packages of R modules (thus they rely on R as a parent) have their own naming scheme. They should take into account the upstream name of the R module. This makes a package name format of R-$NAME. When in doubt, use the name of the module that you type to import it in R.

Examples:

R-mAr (R module named mAr)
R-RScaLAPACK (R module named RScaLAPACK)
R-waveslim (R module named waveslim)

アドオンパッケージ (Sugar Activities)

The name for all packaged Sugar activities must be prefixed with sugar-. For more details, see Packaging/SugarActivityGuidelines .

アドオンパッケージ (Tcl/Tk 拡張)

The name for all packaged Tcl/Tk extensions must be prefixed with tcl-. This rule applies even for Tcl/Tk packages that are already prefixed with tcl in the name. For more details, see Packaging/Tcl#NamingConventions.

アドオンパッケージ (ロケール)

If a package adds a locale to an existing parent package, then it can use an underscore in the locale.

Examples:

ttfonts-zh_TW (adds zh_TW locale fonts in ttfonts family)
ttfonts-zh_CN (adds zh_CN locale fonts in ttfonts family)

アドオンパッケージ (TeX)

As Fedora has switched TeX environments in the past, TeX packages should not be named after the TeX environment (TeX Live or teTeX) but instead should carry the prefix "tex-".