パッケージに関して、何か特別にユーザーに知らせなければならない情報や、オリジナルのソフトウェアと作成した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 v7 に設定しましょう。

$ echo 7 > debian/compat

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

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

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

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

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

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

上記のファイルの書式はシェルスクリプトです。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/パッケージ名/の中に収められるようなHTML、PS、およびPDFなどの形式の付属文書が含まれます。

例えば、gentoo の gentoo.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)を使ってパッケージ生成用の一時的なディレクトリーにインストールするために、パッケージに付属する資料のファイル名を指定してください。

デフォルトでは、ソースディレクトリーのトップレベルに存在する BUGS、 README*、 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

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

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

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

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

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

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

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

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

docs/gentoo.1

X Window System のユーザーは、大抵ウィンドウマネージャを使っており、好きなプログラムを起動できるようにメニュー機能をカスタマイズしています。menu パッケージをインストールしていれば、システムにある全プログラムのメニュー項目が作成され、menu に対応したウィンドウマネージャから利用できます。

以下が dh_make が生成したデフォルトの menu.ex ファイルです。

?package(gentoo):needs=X11|text|vc|wm \
        section=Applications/see-menu-manual\
        title=gentoo command=/usr/bin/gentoo

コロン「:」の後の最初のフィールドはneedsです。このフィールドは、プログラムがどんなどんなインターフェースが必要かを規定します。デフォルトとして挙げられたもの（例：text や X11など）に変更してください。

次はメニューやサブメニューの項目が現れる sectionです。^[58]

titleフィールドはプログラムの名称です。そうしたければ、大文字ではじめても大丈夫です。ただ、短くするようにしましょう。

最後の command フィールドは、実際にプログラムを実行するコマンドです。

それでは、ファイル名をmenuに変更し、メニューの項目を以下のように変更しましょう。

?package(gentoo): needs=X11 \
        section=Applications/Tools \
        title=Gentoo command=gentoo

他にも、longtitle、icon、hints 等のフィールドを追加できます。詳しくは dh_installmenu(1)、 menufile(5)、 update-menus(1)、The Debian Menu sub-policy を参照してください。

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

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

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

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

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

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

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

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

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

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

いかが素の内容です:

# 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 に関する問題を解決しています。

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

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

dpkg-sourceが3.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.sub と config.guess と Makefile に関してパッチファイルを生成をスキップします。

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 に記載する必要はありません。^[62]

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

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

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 としてください。