第5章 debianディレクトリーにあるその他のファイル

目次

5.1. README.Debian
5.2. compat
5.3. conffiles
5.4. package.cron.*
5.5. dirs
5.6. package.doc-base
5.7. docs
5.8. emacsen-*
5.9. package.examples
5.10. package.initpackage.default
5.11. install
5.12. package.info
5.13. package.links
5.14. {package.,source/}lintian-overrides
5.15. manpage.*
5.15.1. manpage.1.ex
5.15.2. manpage.sgml.ex
5.15.3. manpage.xml.ex
5.16. package.manpages
5.17. NEWS
5.18. {pre,post}{inst,rm}
5.19. package.symbols
5.20. TODO
5.21. watch
5.22. source/format
5.23. source/local-options
5.24. source/options
5.25. patches/*

The dh_make command had major updates since this old document was written. So some parts of this document aren't applicable any more.

最新の内容とより実用的な例でこの入門書を書き換えたものが Guide for Debian Maintainers として入手できます。この新しい入門書を第一次的な入門書として使ってください。

The debmake command is used in place of the dh_make command in my new Guide for Debian Maintainers.

debhelperがパッケージのビルド中に行うことは、オプションの設定ファイルを debian ディレクトリーに置けばコントロールできます。この章では、設定ファイルの機能と書式を概説します。パッケージングのガイドラインについての詳細は Debian Policy ManualDebian Developer's Reference を参照してください。

The dh_make command will create some template configuration files under the debian directory. Take a look at all of them.

自明な場合、本章では debian ディレクトリー中のファイルは、前に付く debian/ を省略し簡明に表記しています。

dh_makeコマンドは、一部の debhelper用の設定テンプレートファイルを作らないことがあります。その場合、自分でエディターを使いそれらを作成しなければなりません。

設定ファイルを有効にしたい際は、以下を実行して下さい:

package をプリフィックスとして持たない、例えば install のようなdebhelper の設定ファイルは、最初のバイナリーパッケージへ適用されます。 バイナリーパッケージが多数ある場合、package-1.installpackage-2.install、等のように、パッケージ名を設定ファイルのプリフィックスとすることで指定できます。

パッケージに関して、何か特別にユーザーに知らせなければならない情報や、オリジナルのソフトウェアと作成したDebianパッケージとの相違点があればここに記述します。

以下はdh_makeがデフォルトとして生成するものです:

gentoo for Debian
-----------------
<possible notes regarding this package - if none, delete this file>
 -- Josip Rodin <joy-mg@debian.org>, Wed, 11 Nov 1998 21:02:14 +0100

もし、ドキュメントがなければこのファイルを削除してください。詳しくは dh_installdocs(1)を参照してください。

compat ファイルは、debhelper の互換性レベルを規定します。現段階では、以下のように debhelper v10 に設定しましょう:

$ echo 10 > debian/compat

一定の環境下では旧システムとのコンパチビリティーのためにcompat レベル v9 を使ってよろしい。しかし、v9 以下の如何なるレベルを使うことは勧められないし、新規パッケージに用いることは避けるべきです。

大変な時間と労力を費やしてプログラムをカスタマイズしても、一回のアップグレードであなたの変更をあちこち上書きされてしまうとうんざりします。このような設定ファイルを conffile と記録しておくことで、Debianはこの問題を解決しました。[54] パッケージをアップグレードする際に、あなたは古い設定ファイルをキープしたいかかどうかを尋ねられます。

dh_installdeb(1)自動的に /etc ディレクトリー以下のファイルを全て conffiles とみなすので、あなたのプログラムが他のディレクトリーに conffiles を持たない場合は特に指定する必要はありません。ほとんどのパッケージの場合、/etc 以下にのみ conffiles がある(そうあるべきです)ので、このファイルの存在は不要です。

あなたのプログラムが設定ファイルを利用する場合であっても、 その設定ファイルがプログラム自身によって頻繁に上書きされるような場合には、パッケージをアップグレードするたびに dpkg によって設定ファイルの変更について確認を求められることになるので、その設定ファイルを conffiles に登録しないほうが良いでしょう。

あなたのパッケージングするプログラムが、ユーザーに /etc ディレクトリーの中にある設定ファイルを編集することを要求する場合、dpkg を黙らせるために conffiles として登録しない良く使われる方法が 2 つあります:

  • /etc ディレクトリー中に、メンテナースクリプトによって生成された /var ディレクトリー以下のファイルにシンボリックリンクを張る。

  • /etc ディレクトリーの中にメンテナースクリプトによってファイルを生成する。

メンテナースクリプトについての詳細は、{pre,post}{inst,rm} を参照してください。

パッケージが正しく動作するために、定期的にあるタスクを実行する必要がある場合は、これらのファイルで設定します。毎時間、毎日、毎週、または指定した時間に定期的タスクを実行するように指定することができます。ファイル名は以下です:

  • cron.hourly - /etc/cron.hourly/packageとしてインストール: 1時間ごとに実行する。

  • cron.daily - /etc/cron.daily/packageとしてインストール: 1日に1度実行。

  • cron.weekly - /etc/cron.weekly/packageとしてインストール: 1週間に1度実行。

  • package.cron.monthly - /etc/cron.monthly/package:としてインストール: 1ヶ月に1度実行。

  • package.cron.d - /etc/cron.d/packageとしてインストール: どの時間でも指定可能。

上記のファイルの書式はシェルスクリプトです。package.cron.d は違い、crontab(5)の書式になります。

ログローテーションの設定には明示的な cron.* は必要ありません。これについてはdh_installlogrotate(1) および logrotate(8)を参照してください。

このファイルにはパッケージが必要としているのに、なぜか通常のインストール手順 (dh_auto_install によって呼び出される make install DESTDIR=...) では作成されないディレクトリーを指定します。通常、これは Makefile に問題があることを示唆しています。

installファイルに書かれてるファイルは最初にディレクトリーを作成する必要はありません。install を参照してください。

まずは試しにインストールしてみて、なにか問題が起きた場合にのみ使うべきでしょう。 dirs ファイル中のディレクトリー名の頭にスラッシュが付かない事に注意してください。

もしあなたのパッケージがマニュアルページや info 形式の文書以外に付属文書を含む場合、 doc-base ファイルを使ってそれらを登録し、ユーザーがそれらの付属文書を、例えばdhelp(1)dwww(1)、あるいは doccentral(1) コマンドなどで参照できるようにしましょう。

これには通常、/usr/share/doc/packagename/の中に収められるようなHTML、PS、およびPDFなどの形式の付属文書が含まれます。

例えば、gentoogentoo.doc-base ファイルは次のようになります:

Document: gentoo
Title: Gentoo Manual
Author: Emil Brink
Abstract: This manual describes what Gentoo is, and how it can be used.
Section: File Management
Format: HTML
Index: /usr/share/doc/gentoo/html/index.html
Files: /usr/share/doc/gentoo/html/*.html

このファイルの書式についてはinstall-docs(8)および doc-base パッケージが提供するローカルコピー /usr/share/doc/doc-base/doc-base.html/index.html にある doc-base のマニュアルを参照してください。

追加ドキュメントのインストールについて、詳細は「指定場所へのファイルのインストール」 を見てください。

このファイルには、dh_installdocs(1)を使ってパッケージ生成用の一時的なディレクトリーにインストールするために、パッケージに付属する資料のファイル名を指定してください。

デフォルトでは、ソースディレクトリーのトップレベルに存在する BUGSREADME*TODO などの名前を持つファイル全てを含みます。

gentoo に関していくつか他のファイルが含まれます:

BUGS
CONFIG-CHANGES
CREDITS
NEWS
README
README.gtkrc
TODO

パッケージをインストールする際にバイトコンパイル可能な Emacs ファイルがあなたのパッケージに含まれている場合、これらの emacsen-* ファイルを利用してそれを設定することができます。

これらのファイルはdh_installemacsen(1)によってパッケージ作成用の一時的なディレクトリーにインストールされます。

不要ならこのファイルを削除してください。

dh_installexamples(1)コマンドはこのディレクトリーに列挙されたファイルを例としてインストールします。

もしあなたのパッケージがデーモンであり、システムの起動時に 自動的に動作させる必要があるとしたら、私が最初に勧めたことを あなたはまるっきり無視してしまったわけですよね。そうでしょ ?:-)

Please read dh_installinit(1) dh_installsystemd(1) to provide startup script.

The package.default file will be installed as /etc/default/package. This file sets defaults that are sourced by the init script. This package.default file is most often used to set some default flags or timeouts. If your init script has certain configurable features, you can set them in the package.default file, instead of in the init script itself.

アップストリームプログラムが init スクリプト用ファイルを提供する場合、それを使用するかしないかは自由です。もしアップストリームからの init スクリプトを使わないのであれば package.init に新しいのを作成しましょう。アップストリームのinit スクリプトが問題なく正しい場所にインストールされるとしても、rc* シンボリックリンクの設定は必要です。そのためには、rules ファイルに以下を追加して、dh_installinit をオーバーライドしましょう:

override_dh_installinit:
        dh_installinit --onlyscripts

不要なら、このファイルを削除してください。

パッケージにとってインストールが必要なファイルがあるにも関わらず、 make install ではインストールされない場合、そのファイル名とファイルを置く目的地を install ファイルに記述します。そうすると、dh_install(1) によってそれらのファイルがインストールされます。[55] まずは使えそうな別のツールがないかどうかを調べましょう。例えば、ドキュメントはこのファイルではなくdocsファイルにあるべきです。

install ファイルはインストールされるファイルごとに 1 行必要とします。ファイル名(ビルドディレクトリーのトップを基点とした相対パス)、スペース、インストールするディレクトリー名(インストールディレクトリーを基点とした相対パス)という書式です。例えば、バイナリー src/bar のインストールを忘れた場合などに、 install ファイルの項目は以下のように記述します:

src/bar usr/bin

上記によって、パッケージがインストールされたときに、/usr/bin/barというバイナリーファイルが存在することになります。

また、この install ファイルは相対パスが変わらない場合、インストールディレクトリーの指定を省略することもできます。この書式はビルドした結果を、package-1.install, package-2.install などを使用し、複数のバイナリーパッケージに分割するような、大規模なパッケージで使われます。

dh_install コマンドはもし、カレントディレクトリーでファイルが見つからなかった場合は、(または、--sourcedir で探すように指示したディレクトリー内で見つからなかった場合は)フォールバックして debian/tmp内を検索します。

パッケージにinfoページがある場合、package.info にそれらを挙げて、dh_installinfo(1) を使用してインストールします。

パッケージメンテナーとしてパッケージビルドディレクトリー中に追加のシンボリックリンクを作成する必要がある場合、リンク元とリンク先の両方のフルパスを package.links ファイル中にリストすることで dh_link(1) コマンドでそれらをインストールするべきです。

ポリシーが例外を認めているにも関わらず、lintian が誤診断を報告してきた場合、package.lintian-overridessource/lintian-overrides を使って黙らせることができます。Lintian User's Manual (https://lintian.debian.org/manual/index.html) を読み、濫用は控えてください。

package.lintian-overridespackage と名づけられたパッケージのためのファイルで、dh_lintian コマンドによって usr/share/lintian/overrides/package にインストールされます。

source/lintian-overridesはソースパッケージのためのファイルです。これはインストールされません。

プログラムはマニュアルページが必ず必要です。もし無いなら作らなければなりません。dh_make コマンドはマニュアルページのテンプレートを作成します。マニュアルページがないコマンドのために、コピー、編集する必要があります。不要なテンプレートファイルを削除するのを忘れないようにしてください。

マニュアルページは通常、nroff(1)で書かれています。manpage.1.exのテンプレートもnroffで書かれています。これらのファイルをどう編集するのかについて、簡単な説明がman(7)にあります。

最終的なマニュアルページのファイル名は、解説されているプログラム名を含めなければなりません。ここでは、ファイル名を manpage から gentoo に変更しましょう。ファイル名は、.1 というサフィックスも含みます。これは、このマニュアルページはユーザーコマンドのものだ、という意味です。この部分を間違わないように気をつけてください。以下はマニュアルページのリストです:

つまり、gentoo のマニュアルページは gentoo.1 となります。オリジナルのソースファイルに gentoo.1 というマニュアルページがなければ、アップストリームのドキュメントと例を元にして、manpage.1.ex というテンプレートファイルを編集し gentoo.1 というマニュアルページを作らなければなりません。

各コマンドの --help--version 出力から help2manコマンドを用いてマニュアルページを作成することも可能です。[56]

パッケージにマニュアルページがある場合、package.manpages ファイルにそれらをリストして、dh_installman(1) を使用してインストールします。

gentoo パッケージのマニュアルページとして docs/gentoo.1 をインストールするには、以下のように gentoo.manpages ファイルを作成します:

docs/gentoo.1

dh_installchangelogs(1)コマンドでインストールします。

postinstpreinstpostrmprerm ファイルは[57]メンテナースクリプト と呼ばれています。これらのスクリプトは、パッケージを管理するエリアに置かれ、インストール、アップグレード、削除される際にdpkgによって実行されます。

新米メンテナーのうちは、問題になることが多いのでメンテナースクリプトを直接編集しないようにしましょう。詳しくは Debian Policy Manual, 6 "Package maintainer scripts and installation procedure" を参照し、dh_make によって生成されるサンプルファイルに目を通してください。

もし私の忠告を無視して、メンテナースクリプトを直接編集した場合は、 インストールアップグレードだけでなく、 削除パージのテストもしっかり行ってください。

新バージョンへのアップグレードは静かであるべきで、押し付けがましくてはいけません。(現行ユーザーは、バグが直されたことや新機能が追加されたことで気づかない限りアップグレードに気づかないのが理想です。)

アップグレードが出しゃばる必要がある場合 (例えば、構造がまったく異なる設定ファイルがホームディレクトリーに散在する場合など)、パッケージのデフォルトを(例えばサービスを停止する等の)安全側に設定したり、最後の手段としてはポリシーに要求されるきちんとしたドキュメント (README.DebianNEWS.Debian) を提供するなどの対策を考えるべきです。アップグレード際に メンテナースクリプトdebconf ノートを呼び出したりしてユーザーに迷惑を掛けないでください。

ucf パッケージは、メンテナースクリプトによって管理されているような conffiles とラベルされていないファイルに関して、ユーザーによって変更されたファイルを保存する conffileのような処理をする仕組みを提供します。この仕組みを使うとこれらに関する問題を最小化できます。

これら、メンテナースクリプトはなぜ Debian を選ぶのかという理由の 1 つでもあります。これらの仕組みで、ユーザーが迷惑がる原因とならないよう細心の注意をはらいましょう。

新米メンテナーにとってはライブラリーのパッケージは容易ではないし、避けるべき行為です。このように言いましたが、もしあなたのパッケージがライブラリーを含む場合には、debian/package.symbols ファイルを作成すべきです。debian/package.symbols の管理」 を参照下さい。

dh_installdocs(1)コマンドでインストールします。

watch ファイルの書式は uscan(1) を参照してください。watch ファイルは、uscan ( devscriptsパッケージに含まれます) を設定し、最初ソースを入手したサイトを監視します。これは Debian パッケージ トラッカー サービスによっても使用されています。

以下がその内容です:

# watch control file for uscan
version=3
http://sf.net/gentoo/gentoo-(.+)\.tar\.gz debian uupdate

通常、このwatchファイルでは、http://sf.net/gentoo の URL がダウンロードされ、<a href=...> フォームへのリンクを検索します。リンクされた URL のベースネーム(最後の / から後の部分のみ)は Perl の正規表現 (perlre(1) 参照)パターン gentoo-(.+)\.tar\.gz に照らし合わされます。一致したファイルの中から、バージョンの番号が一番大きいものがダウンロードされ、その後アップデートされたソースツリーを作成するために uupdate プログラムを実行します。

他のサイトでは上記の通りですが、http://sf.net の SourceForge のダウンロードサービスは例外です。watchファイルが Perl の正規表現 ^http://sf\.net/ に一致する URL を含む場合、uscan プログラムが代わり にhttp://qa.debian.org/watch/sf.php/ を使い、このルールを当てはめます。http://qa.debian.org/ の URL リダイレクトは http://sf.net/project/tar-name-(.+)\.tar\.gzを含むwatch ファイルを対象に安定したリダイレクトを提供するよう設計されています。これにより、そこで周期的に変化する URL に関する問題を解決しています。

ターボールの公開鍵電子署名をアップストリームが提供している際には、 uscan(1) 中に記載された pgpsigurlmangle オプションを用いてその正統性を検証することが望ましい。

debian/source/formatファイルでは、ソースパッケージのための理想の書式を示すための行があります。 (完全なリストは、dpkg-source(1)を参照してください。)squeeze以降は、以下のどちらかになっているべきです:

  • 3.0 (native): ネイティブ Debian パッケージ

  • 3.0 (quilt): それ以外の全て。

新しい3.0 (quilt)の書式はquiltパッチによる変更を debian/patchesに記録します。そして、その変更は自動的にソースパッケージを展開するときに適用されます。[58]Debianの変更は、debianディレクトリー以下のファイル全てを含め、debian.tar.gzアーカイブに保存されています。この新しい書式は、特殊な方法を用いることなく、PGNアイコンなどのパッケージメンテナーによるバイナリーファイルを含めることが可能です。[59]

dpkg-source3.0 (quilt)の書式でソースパッケージを展開する際、debian/patches/seriesに列挙されたパッチを自動的に適用します。--skip-patchesオプションで、展開時にパッチを適用しないようにできます。

Debianをパッケージングする活動をVCSで管理したい場合、アップストリームのソースをトラックするためのブランチ(例: upstream)とDebianパッケージをトラックするための別のブランチ(Gitでの典型例: master)を作成します。後者の場合、新しいアップストリームのソースとマージするのを簡単にするために、通常パッチの当てていないアップストリームのソースをdebian/*ファイルと一緒に持っておきます。

パッケージをビルドした後は、ソースのパッチは通常当てたままにされます。masterブランチにコミットする前に手動で quilt pop -a を実行してパッチを外す必要があります。debian/source/local-optionsファイルにunapply-patchesを書いておけば、自動的にパッチを外せます。このファイルは生成されたソースパッケージには含まれず、ローカルビルドでの挙動のみを変更します。このファイルはabort-on-upstream-changesも含むかもしれません (dpkg-source(1) 参照)。

unapply-patches
abort-on-upstream-changes

ソースツリーの中の自動生成されるファイルはパッケージングする際に無意味で大きなパッチファイルを生成するのでとても厄介です。rules ファイルのカスタマイズ」 で説明したようにdh_autoreconf のようなカスタムモジュールが本問題を解消するために存在します。

dpkg-source(1)--extend-diff-ignore オプション引数に Perl 正規表現を提供すると、ソースパッケージ生成時に自動生成ファイルへの変更を無視できます。

この自動生成ファイルの問題の一般的解決策としてソースパッケージの source/options ファイル中に dpkg-source オプション引数を保存する事が出来ます。以下の例では、config.subconfig.guessMakefile に関してパッチファイルの生成をスキップします。

extend-diff-ignore = "(^|/)(config\.sub|config\.guess|Makefile)$"

古い 1.0 のソースフォーマットは、debian 内にパッケージメンテナンスファイルと、パッチファイルを含む単一の大きな diff.gz ファイルを作っていました。そのようなファイルは、ソースツリーの変更を後から調べたり、理解するのが非常に厄介でした。これはあまりいただけません。

新しい 3.0 (quilt) は、quilt コマンドを使って、パッチを debian/patches/* に置きます。debian ディレクトリー以下に含まれているパッチやその他のパッケージデータは、debian.tar.gz ファイルとしてパッケージングされます。dpkg-source コマンドは、quilt 形式のパッチデータを quilt パッケージなしで 3.0 (quilt) として扱えるので、quilt パッケージを Build-Depends に記載する必要はありません。[60]

quilt コマンドについてはquilt(1) で説明されています。ソースへの変更は、debian/patches ディレクトリー内 -p1 パッチファイルのスタックとして記録され、debian ディレクトリーの外のソースツリーには触れません。それらのパッチの順番は debian/patches/series ファイルに記録されます。パッチの適用 (=push)も、外す (=pop)のも、更新(=refresh)も、簡単にできます。 [61]

3章ソースコードの変更 では、debian/patchesに 3 つのパッチを作りました。

Debian のパッチは debian/patches にあるので、quilt のセットアップ」 の説明に従い、dquilt コマンドを正しく設定してください。

誰かが(あなた自身も含みます) foo.patch というパッチを後から提供した際の、3.0 (quilt) ソースパッケージの変更はとてもシンプルです:

$ dpkg-source -x gentoo_0.9.12.dsc
$ cd gentoo-0.9.12
$ dquilt import ../foo.patch
$ dquilt push
$ dquilt refresh
$ dquilt header -e
... describe patch

新しい 3.0 (quilt) 形式で保存されるパッチには 曖昧さがあってはいけません。それを保証するために、dquilt pop -a; while dquilt push; do dquilt refresh; done としてください。



[54] dpkg(1) and Debian Policy Manual, "D.2.5 Conffiles" を参照下さい。

[55] filesファイルによって、dh_movefiles(1)コマンドが設定され、置換されます。

[56] help2man が作成する仮のマニュアルページに、詳細なドキュメントが info システムにあると記載されることに注意して下さい。info ページ中にコマンドが無い場合は、help2man コマンドが生成したページを手動で修正するべきです。

[57] {pre,post}{inst,rm} という bash 独自の短縮形をこれらのファイル名の表記としていますが、システムシェルである dash との互換性のために、これらのメンテナースクリプトでは純粋な POSIX シンタックスを使うべきです。

[58] ソースの書式を 3.0 (quilt)3.0 (native) に移行する際の注意点などは、DebSrc3.0 を参照下さい。

[59] この新しいフォーマットは、複数のアップストリームの tar アーカイブやこの他の圧縮方法もサポートしています。詳細は本稿の範疇を超えるため割愛します。

[60] パッチセットをメンテナンスするためのいくつかの方法が提案され、Debian パッケージで使われていますが、quilt が推奨されています。他には、dpatchdbscdbs、などがあります。これらの方法は、大抵 debian/patches/* ファイルでパッチを管理しています。

[61] スポンサーにパッケージのアップロードを頼む時にも、あなたが加えた変更に対するこのような明確な分離とドキュメントは、スポンサーによるパッケージのレビューを促進させるためにも、非常に重要です。