第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/*

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

dh_makeコマンドは、debianディレクトリーの中に設定ファイルのテンプレートを作成します。大抵の場合、.exサフィックスが付いています。ファイル名の先頭にpackageなどのように、バイナリーパッケージの名前がつくものもあります。これらのファイルにはすべて目を通しておいてください。[54]

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)を参照してください。

The compat file defines the debhelper compatibility level. Currently, you should set it to the debhelper v10 as follows:

$ echo 10 > debian/compat

You may use compat level v9 in certain circumstances for compatibility with older systems. However, using any level below v9 is not recommended and should be avoided for new packages.

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

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)コマンドはこのディレクトリーに列挙されたファイルを例としてインストールします。

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

package.init ファイルはデーモンの起動や停止をする init スクリプト のための /etc/init.d/package スクリプトとしてインストールされます。その極めて標準的なテンプレートファイルは dh_make コマンドによって提供される init.d.ex です。Linux Standard Base (LSB) に準拠したヘッダーを提供するように確実にするとともに、ファイル名の変更とかなりの内容編集がおそらく必要です。このファイルは dh_installinit(1) によって、一時的なディレクトリーにインストールされます。

package.default ファイルは /etc/default/package にインストールされます。このファイルは init スクリプトによりソースされるデフォルトを設定します。この package.default ファイルは大抵、デーモンを停止したり、デフォルトのフラグやタイムアウトなどの設定に使われます。もしもあなたの init スクリプトが、特定の設定可能な機能を有しているのであれば、それは init スクリプトではなく、この package.default ファイルに設定しておくべきでしょう。

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

override_dh_installinit:
        dh_installinit --onlyscripts

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

If there are files that need to be installed into your package but your standard make install won't do it, put the filenames and destinations into this install file. They are installed by dh_install(1).[56] You should first check that there is not a more specific tool to use. For example, documents should be in the docs file and not in this one.

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) コマンドでそれらをインストールするべきです。

If lintian reports an erroneous diagnostic for a case where Debian policy allows exceptions to some rule, you can use package.lintian-overrides or source/lintian-overrides to quieten it. Please read the Lintian User's Manual (https://lintian.debian.org/manual/index.html) and refrain from abusing this.

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コマンドを用いてマニュアルページを作成することも可能です。[57]

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

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

docs/gentoo.1

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

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

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

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

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

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

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

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

Packaging of a library is not easy for a novice maintainer and should be avoided. Having said it, if your package has libraries, you should have debian/package.symbols files. See debian/package.symbols の管理」.

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

The watch file format is documented in the uscan(1) manpage. The watch file configures the uscan program (in the devscripts package) to watch the site where you originally got the source. This is also used by the Debian Package Tracker service.

以下がその内容です:

# 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 プログラムを実行します。

Although this is true for other sites, the SourceForge download service at http://sf.net is an exception. When the watch file has a URL matching the Perl regexp ^http://sf\.net/, the uscan program replaces it with http://qa.debian.org/watch/sf.php/ and then applies this rule. The URL redirector service at http://qa.debian.org/ is designed to offer a stable redirect service to the desired file for any watch pattern of the form http://sf.net/project/tar-name-(.+)\.tar\.gz. This solves issues related to periodically changing SourceForge URLs.

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

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

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

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

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

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

When you want to manage Debian packaging activities under a VCS, you typically create one branch (e.g., upstream) tracking the upstream source and another branch (e.g., typically master for Git) tracking the Debian package. For the latter, you usually want to have unpatched upstream source with your debian/* files for the Debian packaging to ease merging of the new upstream source.

パッケージをビルドした後は、ソースのパッチは通常当てたままにされます。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 に記載する必要はありません。[61]

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

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

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

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

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

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

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

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

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

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