# 3. バイナリパッケージ

Debian ディストリビューションは `dpkg` と呼ばれる Debian パッケージ管理システムに基礎を置いています。このため、Debian ディストリビューションに含まれる全てのパッケージは `.deb` ファイル形式で提供されなければなりません。

A `.deb` package contains two sets of files: a set of files to install on the system when the package is installed, and a set of files that provide additional metadata about the package or which are executed when the package is installed or removed. This second set of files is called package metadata files. Among those files are the package maintainer scripts and `control`, the binary package control file that contains the control fields for the package. Other package metadata files include symbols or shlibs used to store shared library dependency information and the `conffiles` file that lists the package's configuration files (described in Configuration files).

There is unfortunately a collision of terminology here between control information files and files in the Debian control file format. Throughout this document, a control file refers to a file in the Debian control file format. These files are documented in Control files and their fields. Only files referred to specifically as package metadata files are the files included in the package metadata member (called `control.tar`) of the `.deb` file format used by binary packages. Most package metadata files are not in the Debian control file format.

## 3.1. パッケージ名

"全てのパッケージは Debian アーカイブ内において重複しない名前を持っていなければなりません。

パッケージ名はコントロールフィールド `Package` に含まれます。また、そのフォーマットは Package で記載されています。パッケージ名は `.deb` ファイルのファイル名の一部としても含まれています。

### 3.1.1. Packages with potentially offensive content

As a maintainer you should make a judgement about whether the contents of a package is appropriate to include, whether it needs any kind of content warning, and whether some parts should be split out into a separate package (so that users who want to avoid certain parts can do so). In making these decisions you should take into account the project's views as expressed in our Diversity Statement.

If you split out (potentially) offensive or disturbing material into a separate package, you should usually mark this in the package name by adding `-offensive`. For example, `cowsay` vs `cowsay-offensive`. In this situation the `-offensive` package can be Suggested by the core package(s), but should not be Recommended or Depended on.

## 3.2. パッケージのバージョン

各パッケージはコントロールフィールド `Version` にバージョン番号を持ちます。また、そのフォーマットは Version で記載されています。

これによってパッケージがアップグレードされるのか、あるいはダウングレードされるのかを知ることができます。さらにパッケージフロントエンドプログラムが、そしてその結果、あるパッケージがシステムにインストールされているものよりも新しいものかどうかを判断することができるようになります。バージョン番号の形式は (比較に関する限り) 重要なものが前にくる順となっています。

もし上流のパッケージが問題のあるバージョン番号形式になっているならば、`Version` フィールドではまともな形式に変換すべきです。

### 3.2.1. 日付に基づくバージョン番号

一般的に、Debian パッケージは上流ソースと同じバージョン番号を使うべきです。しかし、上流のバージョン番号が日付に基づくような場合 (例えば、開発中や "snapshot" リリースの場合) には、パッケージ管理システムはこのようなバージョン番号を正しく順序判断することができません。例えば、dpkg は "96May01" を" "96Dec24" よりも大きいと判断するでしょう。

To prevent having to use epochs for every new upstream version, the date-based portion of any upstream version number should be given in a way that sorts correctly: four-digit year first, followed by a two-digit numeric month, followed by a two-digit numeric day-of-month, possibly with punctuation between the components.

Native Debian packages (i.e., packages which have been written especially for Debian) whose version numbers include dates should also follow these rules. If punctuation is desired between the date components, remember that hyphen (`-`) cannot be used in native version numbers. Period (`.`) is normally a good choice.

### 3.2.2. Uniqueness of version numbers

The part of the version number after the epoch must not be reused for a version of the package with different contents once the package has been accepted into the archive, even if the version of the package previously using that part of the version number is no longer present in any archive suites.

This uniqueness requirement applies to the version numbers of source packages and of binary packages, even if the source package producing a given binary package changes. Thus the version numbers which a binary package must not reuse includes the version numbers of any versions of the binary package ever accepted into the archive, under any source package.

Additionally, for non-native packages, the upstream version must not be reused for different upstream source code, so that for each source package name and upstream version number there exists exactly one original source archive contents (see Files).

The reason for these restrictions is as follows. Epochs are not included in the names of the files that compose source packages, or in the filenames of binary packages, so reusing a version number, even if the epoch differs, results in identically named files with different contents. This can cause various problems.

If you find yourself wanting to reuse the part of a version number after the epoch, you can just increment the Debian revision, which doesn't need to start at 1 or be consecutive.

## 3.3. パッケージのメンテナ

全てのパッケージには、以下で記載する `orphaned` パッケージを除いて、一人または一グループの Debian メンテナを持たなければなりません。メンテナは、個人であっても、メーリングリストなどの共通の一つのメールアドレスで連絡の取れるグループであってもかまいません。メンテナは、Debian パッケージファイルの保守、すなわち報告されたバグに対して適切に判断・応答すること、新しいバージョンのアップロード (直接あるいはスポンサー経由で) を行うこと、そのパッケージが適切なアーカイブエリアに置かれていること、パッケージの安定度や有用性にしたがって適切なディストリビューションに収録されていること、有用性が失われたか保守不能になった場合パッケージを Debian ディストリビューションから削除する要求を出すことについて、責任を持ちます。

Debian パッケージのメンテナは各パッケージの `Maintainer` 制御フィールドに、正しい名前と有効な電子メールアドレスの両方により指定されていなければなりません。`Maintainer` 制御フィールド内の電子メールアドレスは、Debian でパッケージに関して自動的にメールを送るのに使われる役割のアカウントからのメールを受け取らなければいけません。これは、バグトラッキングシステムからの SPAM でないメール、Debian アーカイブ管理ソフトウェアからのすべてのメール、およびそれ以外にもプロジェクトで合意されている決まった役割のアカウントと自動送信プロセスからのメールは、受け取らなければならないということです。 [1] もしその人がいくつかのパッケージを管理している場合、個々のパッケージの `Maintainer` フィールドに同じ形式の名前と電子メールアドレスを記入すべきです。

`Maintainer` フィールドの書式は、Maintainer で記載されています。

パッケージのメンテナがメールアドレスを共有するチームである場合、`Uploaders` 制御フィールドが必ず存在し、個人の電子メールアドレスを付けてひとりの人物が指定されていなければいけません。このフィールドの書式は、Uploaders を参照ください。

orphaned パッケージとは、現在メンテナのいないパッケージのことです。orphaned パッケージでは、`Maintainer` 制御フィールドに `Debian QA Group <packages@qa.debian.org>` を設定しなければいけません。このようなパッケージは、保守の志願者が現れない限り Debian プロジェクト全体で保守されているとみなされます。 [2]

## 3.4. パッケージの説明文

全ての Debian パッケージは、パッケージの簡潔な説明文と、やや詳細な説明文を含む `Description` フィールドを持たなければなりません。`Description` フィールドの書式の技術的詳細は Description に記載されています。

説明文は、そのパッケージのことを知らないユーザ (システム管理者) が、そのパッケージ (プログラム) をインストールするかどうかを判断するにあたって十分な情報を伝えるように書かれているべきです。説明文はプログラムの説明文書をそのままコピーしただけのものとすべきではありません。

概要と、長い説明のどちらについても重要な情報を最初に書いてください。概要や説明の最初の部分だけしか表示されない場合があるためです。ただし、詳しい説明の全体を見る手段が用意されていることを仮定してもかまわないでしょう。

説明文にはパッケージ間の重要な依存関係 (dependency) や競合関係 (conflict) の情報も示されているべきです。そうでないと、ユーザにはなぜ競合関係や依存関係の不具合が起きているのかが分かりません。

また、そのパッケージを設定したり使ったりするための解説を含めるべきではありません (それはインストールスクリプト、マニュアルページ、Infoファイルなどで扱われるべきです)。著作権表示やその他管理に関係する種々のことも含まれるべきではありません。それら向けには copyright ファイルが用意されています。

### 3.4.1. 一行要約・概説

一行による要約は簡潔にすべきです。半角換算で 80 文字以下としてください。

パッケージ名を要約 (Synopsis) の行に入れないでください。入れなくても、表示ソフトウェアはパッケージ名を自動的に表示するようになっています。多くの場合、ユーザの目にふれるのはこの要約行だけなので、なるべく分かりやすい要約にするようにしてください。

### 3.4.2. 詳細の解説部分

上記の一行要約からそのまま引き続いて説明文に続ける形を取らないでください。これは説明文の全体が表示されている時にうまくいきませんし、また一行要約が表示されている場合のみでしか意味をなしません。

詳細の解説部分はそのパッケージ自体の説明 (例えば、このパッケージが Debian システム全体の中の、どの部分集合に属しているのか) について記します。

説明文は誰であっても、例えばそのパッケージが扱っている分野のことを何も知らない人でも理解できるように書かれなければなりません。 [3]

## 3.5. 依存関係

全てのパッケージには、それが正しく動作するためにまず必要となる他のパッケージについての依存情報が指定されていなければなりません。

例えば、パッケージに含まれている、動的にリンクされた実行形式バイナリが必要とする共有ライブラリは、依存関係のエントリで明示していなければなりません。

但し、`Essential` (下記参照) と指定されているパッケージに対して、それ以外のパッケージが依存関係を宣言する必要はありません。また、そのようなパッケージの特定のバージョンに依存しているのでなければ、依存関係を宣言すべきではありません。 [4]

時々、あるパッケージが、それを展開する前にもう一つのパッケージが展開され かつ 設定されていることを必要とすることがあります。この場合、そのパッケージには `Pre-Depends` エントリを指定しなければなりません。

`debian-devel` メーリングリストで議論して同意が得られる前に、パッケージに `Pre-Depends` エントリを指定するべきではありません。

パッケージ相互関係を指定するコントロールフィールドの書式は Declaring relationships between packages に記載されています。

## 3.6. 仮想パッケージ

多かれ少なかれ同じような仕事をこなすパッケージがいくつか存在するということがあります。この場合、パッケージが持つ共通の機能を説明する名前の 仮想パッケージ を定義するのが便利です (仮想パッケージは論理的に存在するだけで、物理的には存在しません。これがそれらが 仮想 と呼ばれる理由です)。特定の機能を持つこういったパッケージ群は皆仮想パッケージを 提供 します。そうしておけば、その機能を必要とする他のパッケージは単にその仮想パッケージに依存するようにすれば、可能性のある全てのパッケージをいちいち列挙しなくても良いわけです。

全てのパッケージはそうするのが適当なときには仮想パッケージ名を使うべきで、もし必要ならば新しい仮想パッケージ名を作るようにしなければなりません。但し、同意が得られ、仮想パッケージ名の一覧に掲載されるまで、新しい仮想パッケージ名を使うべきではありません (非公式に、互いに関連する一群のパッケージの間で使う場合は除く)。この項に関しては、Virtual packages - Provides を参照下さい。

正式な仮想パッケージ名の一覧の最新版は `debian-policy` パッケージに同封されています。また、Debian ウェブミラーサーバの https://www.debian.org/doc/packaging-manuals/virtual-package-names-list.yaml にあります。

このリストを更新するための手続きについてはこの一覧ファイルのはじめに記述されています。

## 3.7. Base システム

`base システム` は、新しいシステムに於いて他の全てに先だってインストールされる、Debian システムの最小のサブセットを形成します。従って、必要となるディスク使用量を非常に小さく保つため、ごく少数のパッケージのみが base システムの一部となることを認められています。

base システムはプライオリティ評価が `required` と `important` のパッケージ全体で構成されています。また、それらの大半には `essential` 指定 (下記参照) が付加されているでしょう。

## 3.8. Essential パッケージ

Essential は、パッケージ群が展開状態 (Unpacked) でも、システム上で提供され使用できなければならない最小の機能の集合として定義されています。そのようなパッケージには `Essential` コントロールフィールドで `Essential` 指定が付加されています。`Essential` コントロールフィールドの書式は Essential に記載されています。

これらのパッケージは簡単には削除できません (削除するには `dpkg` に特別な 強制 (force) オプション を指定しなければなりません)。このため、このフラグはどうしても必要な場合にのみ使うようにしなければなりません。共有ライブラリのパッケージに Essential 指定をしてはいけません。依存関係により誤った削除を阻止できますし、新しいものに入れ替える際には上書きできるようになっている必要があるからです。

Since dpkg will not prevent upgrading of other packages while an `essential` package is in an unconfigured state, all `essential` packages must supply all of their core functionality even when unconfigured after being configured at least once. If the package cannot satisfy this requirement it must not be tagged as essential, and any packages depending on this package must instead have explicit dependency fields as appropriate.

メンテナは、プログラム、インターフェース、機能を `essential` パッケージに加える際には細心の注意を払う必要があります。パッケージは `essential` パッケージの提供する機能は明示的な依存関係の宣言なしに常に提供されていることを期待してよく、逆に Essential パッケージ群から機能を削除することは非常に難しく、ほとんどできないものになります。また、`essential` パッケージに機能を加えることは、その機能を Essential 群で永久にサポートする義務を負わせることになります。

`debian-devel` メーリングリストで議論して同意が得られない限り、パッケージに `Essential` 指定を付加してはなりません。

## 3.9. メンテナスクリプト

パッケージのインストールスクリプトでは、ユーザにとって見る必要がない情報を出力することを避けるべきです。また、大量のパッケージをインストールする際にユーザが退屈するのを避けるのも、`dpkg` に任せておくべきです。中でも、`update-alternatives` に `--verbose` オプションを渡さないようにしましょう。

インストールスクリプトの実行中に起こったエラーはチェックしなければなりませんし、エラーの後インストールの実行を続けてはなりません。

Note that in general Scripts applies to package maintainer scripts, too.

You should not use `dpkg-divert` on a file belonging to another package without consulting the maintainer of that package first. When adding or removing diversions, package maintainer scripts must provide the `--package` flag to `dpkg-divert` and must not use `--local`.

All packages which supply an instance of a common command name (or, in general, filename) should generally use `update-alternatives` so that they can be installed together. If `update-alternatives` is not used, then each package must use `Conflicts` to ensure that other packages are removed. (In this case, it may be appropriate to specify a conflict against earlier versions of something that previously did not use `update-alternatives`; this is an exception to the usual rule that versioned conflicts should be avoided.)

Diversions are primarily intended as a tool for local administrators and local packages to override the behavior of Debian. While there are some circumstances where one Debian package may need to divert a file installed by another Debian package, such circumstances are rare. Maintainers should strongly prefer using other overriding mechanisms, instead of diversions, whenever those other mechanisms are sufficient to accomplish the same goal. In other words, diversions in packages should be considered a last resort. Diversion of a file in one Debian package by another Debian package should be coordinated between the maintainers of those packages.

One specific case of this rule is that configuration files used by `systemd` components, such as units, udev rules, tmpfiles.d, modules-load.d, sysusers and other such files, including those specific to systemd daemons (e.g.: /etc/systemd/system.conf). must not be diverted by any Debian package. Instead, use masking and drop-ins.

Alternatives must not be used for `systemd` configuration files. The alternatives system does not know how to apply changes to services when updating alternatives, so the resulting behavior would be confusing and unpredictable. Instead, aliases can be used to provide alternative implementations of the same named unit.

### 3.9.1. Prompting in maintainer scripts

Package maintainer scripts may prompt the user if necessary. Prompting must be done by communicating through a program, such as `debconf`, which conforms to the Debian Configuration Management Specification, version 2 or higher.

Packages which are essential, or which are dependencies of essential packages, may fall back on another prompting method if no such interface is available when they are executed.

The Debian Configuration Management Specification is included in the `debconf_specification` files in the debian-policy package. It is also available from the Debian web mirrors at https://www.debian.org/doc/packaging-manuals/debconf_specification.html.

Packages which use the Debian Configuration Management Specification may contain the additional package metadata files `config` and `templates`. `config` is an additional maintainer script used for package configuration, and `templates` contains templates used for user prompting. The `config` script might be run before the `preinst` script and before the package is unpacked or any of its dependencies or pre-dependencies are satisfied. Therefore it must work using only the tools present in essential packages. [5]

Packages which use the Debian Configuration Management Specification must allow for translation of their user-visible messages by using a gettext-based system such as the one provided by the po-debconf package.

Packages should try to minimize the amount of prompting they need to do, and they should ensure that the user will only ever be asked each question once. This means that packages should try to use appropriate shared configuration files (such as `/etc/papersize` and `/etc/news/server`), and shared debconf variables rather than each prompting for their own list of required pieces of information.

It also means that an upgrade should not ask the same questions again, unless the user has used `dpkg --purge` to remove the package's configuration. The answers to configuration questions should be stored in an appropriate place in `/etc` so that the user can modify them, and how this has been done should be documented.

If a package has a vitally important piece of information to pass to the user (such as "don't run me as I am, you must edit the following configuration files first or you risk your system emitting badly-formatted messages"), it should display this in the `config` or `postinst` script and prompt the user to hit return to acknowledge the message. Copyright messages do not count as vitally important (they belong in `/usr/share/doc/PACKAGE/copyright`); neither do instructions on how to use a program (these should be in on-line documentation, where all the users can see them).

Any necessary prompting should almost always be confined to the `config` or `postinst` script. If it is done in the `postinst`, it should be protected with a conditional so that unnecessary prompting doesn't happen if a package's installation fails and the `postinst` is called with `abort-upgrade`, `abort-remove` or `abort-deconfigure`.

[1]

A sample implementation of such a whitelist written for the Mailman mailing list management software is used for mailing lists hosted by https://alioth-lists.debian.net/.

[2]

The detailed procedure for gracefully orphaning a package can be found in the Debian Developer's Reference (see 関連文書).

[3]

The blurb that comes with a program in its announcements and/or `README` files is rarely suitable for use in a description. It is usually aimed at people who are already in the community where the package is used.

[4]

Essential is needed in part to avoid unresolvable dependency loops on upgrade. If packages add unnecessary dependencies on packages in this set, the chances that there will be an unresolvable dependency loop caused by forcing these Essential packages to be configured first before they need to be is greatly increased. It also increases the chances that frontends will be unable to calculate an upgrade path, even if one exists.

Also, functionality is rarely ever removed from the Essential set, but packages have been removed from the Essential set when the functionality moved to a different package. So depending on these packages just in case they stop being essential does way more harm than good.

[5]

Debconf or another tool that implements the Debian Configuration Management Specification will also be installed, and any versioned dependencies on it will be satisfied before preconfiguration begins.