Scroll to navigation

debhelper(7) Debhelper debhelper(7)

名前

debhelper - debhelper 関連ツール群

書式

dh_* [-v] [-a] [-i] [--no-act] [-ppackage] [-Npackage] [-Ptmpdir]

説明

debhelper は、Debian パッケージのビルドを容易にするために使われます。debhelper の根底にある考えは「パッケージビルド時の各種の共通的な作業を自動化するために debian/rules で用いられている、小さく単純で、容易に理解可能なツールをまとめて提供すること」です。つまり、あなた＝パッケージを作成する人の負担を減らします。さらに、Debian ポリシーが変わった場合にはこのツール群を多少変更さえすれば、debhelper を使っているパッケージが新しいポリシーに適合するのに必要になるのは、再ビルドだけになります。

debhelper を利用している典型的な debian/rules ファイルは、複数の debhelper コマンドを順番に呼び出しているか、dh(1) を使って一連の処理を自動化しています。debhelper を使った rules ファイルの例は /usr/share/doc/debhelper/examples/ にあります。

debhelper を使って Debian パッケージを作成するには、サンプルの rules ファイルのどれかをコピーして手で修正するだけです。あるいは dh-make パッケージを利用してみてください。このパッケージには部分的に作業を自動化してくれる dh_make コマンドが含まれています。よりやさしい案内については、maint-guide-ja パッケージに debhelper を使って初めてパッケージを作る人向けのチュートリアルが含まれています。

Except where tool explicitly denotes otherwise, all of the debhelper tools assumes that they run from root directory of an unpacked source package. This is so they can locate find debian/control and debian/compat when needed.

DEBHELPER コマンド

以下が利用可能な debhelper コマンドの一覧です。詳細は、各コマンド付属の man ページを参照してください。

dh_auto_build(1)
自動的にパッケージをビルドする
dh_auto_clean(1)
ビルド後、自動的にビルドディレクトリを消去する
dh_auto_configure(1)
パッケージビルド前に自動的に configure を行う
dh_auto_install(1)
make install や類似コマンドを自動的に実行する
dh_auto_test(1)
パッケージのテストスイートを自動的に実行する
dh_bugfiles(1)
カスタマイズされたバグレポート用ファイルをインストールする
dh_builddeb(1)
Debianバイナリパッケージのビルドを行う
dh_clean(1)
パッケージビルドディレクトリを消去する
dh_compress(1)
ビルドディレクトリでファイル圧縮とシンボリックリンクの修正を行う
dh_fixperms(1)
パッケージビルドディレクトリ内のファイル権限を修正する
GConf デフォルトファイルをインストールし、スキーマに登録する
dh_gencontrol(1)
control ファイルを生成し、インストールする
dh_icons(1)
Freedesktop 規格のアイコンキャッシュを更新する
dh_install(1)
パッケージビルドディレクトリにファイルをインストールする
dh_installcatalogs(1)
SGML カタログファイルをインストール・登録する
dh_installchangelogs(1)
ビルドディレクトリに changelog をインストールする
dh_installcron(1)
cron スクリプトを etc/cron.* へインストールする
dh_installdeb(1)
DEBIAN ディレクトリにファイルをインストールする
dh_installdebconf(1)
ビルドディレクトリの debconf が使うファイルをインストールする
dh_installemacsen(1)
Emacsのアドオンパッケージを登録する
dh_installifupdown(1)
if-up と if-down フックをインストールします
dh_installinfo(1)
info ファイルをインストールする
dh_installlogcheck(1)
etc/logcheck/ に logcheck 用ルールファイルをインストールする
dh_installlogrotate(1)
logrotate用設定ファイルをインストールする
dh_installmenu(1)
ビルドディレクトリへ Debian メニューファイルをインストールする
dh_installmime(1)
mime ファイルをビルドディレクトリへインストールする
dh_installmodules(1)
カーネルモジュールを登録する
dh_installpam(1)
pam サポートファイルをインストールする
dh_installppp(1)
ppp 用の ip-up, ip-down ファイルをインストールする
dh_installudev(1)
udev 用ルールファイルをインストールする
dh_installwm(1)
ウィンドウマネージャを登録する
dh_installxfonts(1)
X 用フォント群の登録を行う
パッケージビルドディレクトリ内でシンボリックリンクを作成する
dh_lintian(1)
ビルドディレクトリに lintian への override ファイルをインストールする
dh_listpackages(1)
debhelper が処理するバイナリパッケージの一覧を列挙する
dh_md5sums(1)
DEBIAN/md5sums ファイルを生成する
dh_movefiles(1)
debian/tmp からサブパッケージへファイルを移動する
dh_perl(1)
Perlへの依存関係を検討し、MakeMaker 実行後に生成したものを消去する
dh_prep(1)
バイナリパッケージビルドの事前準備として諸々の消去を行う
dh_shlibdeps(1)
共有ライブラリの依存関係を計算する
dh_strip(1)
実行ファイル、共有ファイル、静的ライブラリのデバッグ情報を削る
dh_testdir(1)
Debian パッケージをビルドする前にディレクトリの状態を検証する
dh_usrlocal(1)
usr/local ディレクトリをメンテナスクリプトへ移行する

廃止されたコマンド一覧

廃止されており、使うべきでない debhelper コマンド一覧

dh_installmanpages(1)
古いスタイルの man ページのインストール用プログラム (廃止)

他のコマンド

プログラムの名前が dh_ で始まり、先のリストにないものは、debhelper パッケージ付属のプログラムではありません。しかし、このような名前を持つコマンドは、このページに記述されている他のプログラムのように動作するべきです。

DEBHELPER 設定ファイル

debhelper のコマンドの多くは、どのように動作するかについて debian/ ディレクトリ以下にあるファイルを用います。共通の debian/changelog や debian/control はすべてのパッケージに存在していますが、これに加えて特定の debhelper コマンドの動作を制御できる追加ファイルがあります。これらのファイルは、大抵 debian/package.foo というファイル名です (もちろん、package は処理しようとしているパッケージ名に変えてください)。

例えば、dh_installdocs では、インストールするドキュメントの一覧を得るのに debian/package.docs という名前のファイルを利用します。各コマンドが使うファイルの名前とフォーマットについては、詳細はコマンドの man ページを参照してください。大抵、これらのファイルでは１行ごとに処理するファイルを１つずつ列挙します。いくつかの debhelper プログラムでは、ファイルと宛先の組み合わせや、もう少々複雑なフォーマットなどを使います。

Note for the first (or only) binary package listed in debian/control, debhelper will use debian/foo when there's no debian/package.foo file. However, it is often a good idea to keep the package. prefix as it is more explicit. The primary exception to this are files that debhelper by default installs in every binary package when it does not have a package prefix (such as debian/copyright or debian/changelog).

稀ではありますが、これらのファイルを、異なるアーキテクチャ／異なる OS 用にそれぞれ用意したい場合があります。ファイル名が debian/package.foo.ARCH や、debian/package.foo.OS のものが存在すると、"dpkg-architecture -qDEB_HOST_ARCH" / "dpkg-architecture -qDEB_HOST_ARCH_OS" でそれぞれ指定した ARCH と OS を含むものが、通常のファイルよりも優先的に使われます。

多くの場合、これらの設定ファイルは、いろいろな種類のファイルを列挙して指定するのに使われます。例えばインストールすべきドキュメントやサンプルファイルであったり、移動すべきファイルだったり等となります。シェルのワイルドカード文字列 (?, * 及び [..] 文字クラス) をファイルに含める事ができ、状況次第ではこちらが望ましい事もあります。また、行頭がB <#> で始まる行は無視される事を利用して、コメントを記載できます。

これらファイルの文法は、読解・修正しやすいよう、意図的にシンプルにしてあります。もし、さらに強力で複雑な事をしたければ、これらのファイルに実行権限を付与し、状況にあった出力をするプログラムを作成してください。ただし、この場合の出力結果では、後の処理でワイルドカードは展開されず、コメントも取り除かれない事に気をつけてください。

DEBHELPER 間で共有されるオプション

以下のコマンドラインオプションは、全ての debhelper プログラムでサポートされています。

冗長出力モード。パッケージビルドディレクトリを変更するようなコマンドを全て表示します。
実際の処理を行いません。-v オプションと併用すると、コマンドがどのような処理を行うかが出力されます。
アーキテクチャ依存パッケージを、DEB_HOST_ARCH アーテキクチャ向けにビルドするように動作します。
全てのアーキテクチャ非依存パッケージに対して処理を行います。
package で指定されたパッケージに対して処理を行います。複数のパッケージを debhelper に処理させる際には、繰り返し列挙して指定してください。
廃止された -a のエイリアスです。

This option is removed in compat 12.

-a, -i, -p オプションで処理すべきパッケージとして対象としていても、指定されているパッケージについては処理を行わないようにします。
この debhelper コマンドにより、すでに処理済のパッケージについては処理をしないようにします (つまり、debhelper のログにコマンドの記録があるものは処理しない)。例えば、いくつかのバイナリパッケージだけに対して特別なオプション付きでコマンドを呼び出し、残りのパッケージに対しては本オプションをつけてコマンドを呼び出し、デフォルト設定による処理を行うという事ができます。
特定のファイルを無視します。debian/ 以下に実際には debhelper コマンドが実行しては困るような debhelper 設定ファイルがあるような時に利用できます。ただ、debian/compat, debian/control, debian/changelog は無視する事ができません。これは動作の都合上、これらのファイルを無視するわけにはいかないからです。

例えば、開発元 (upstream) が debian/init を提供しているが dh_installinit でインストールして欲しくは無い場合、--ignore=debian/init を使うことになります。

tmpdir をパッケージビルドディレクトリとして利用します。デフォルトでは debian/package ディレクトリが使われます。
このあまり使われないオプションは、debhelper コマンドが "main package" とみなすパッケージ、つまり、debian/control の最初に記載されたパッケージを変更するものです。これにより、通常の debian/package.foo ファイルではなく debian/foo ファイルが使われるようになります。
これは、実行するすべてのコマンドへユーザー指定のオプションを渡す際に dh(1) が利用します。コマンドが指定のオプションをサポートしている、あるいは内蔵している場合は、オプションは効果を発揮します。コマンドが指定されたオプションをサポートしていない場合 (あるいは、内蔵しているオプションにない場合)、オプションは無視されます。

DEBHELPER の共通オプション

以下のコマンドラインオプションが、debhelper プログラムのうち複数でサポートされています。「オプションが何を意味するか」という完全な説明は、各コマンドの man ページを参照してください。

postinst, postrm 等のスクリプトに変更を加えません。
item を処理対象から除外します。複数の item を除外するためにこのオプションを複数指定して使う。ことができます。通常、\fIitem\fR はファイル名の一部で、指定されたテキストが含まれるファイルはすべて除外されます。
コマンドラインで指定したファイル、あるいは他の item について、最初のパッケージだけでなく全パッケージに対して処理を行います。

ビルドシステム用オプション

以下のコマンドラインオプションが、すべての dh_auto_* の debhelper プログラムによってサポートされています。これらのプログラム群は様々なビルドシステムをサポートしており、通常の場合は推定によって、どのビルドシステムがどのように使われるかを決定します。これらのコマンドラインオプションを使って、デフォルトの動作を override することが可能です。大抵の場合は、これらのオプションはまず dh(1) に渡され、それからすべての dh_auto_* プログラムへと渡されます。

パッケージに合わせて自動的に選択されたビルドシステムではなく、buildsystem で指定したビルドシステムを強制的に使用します。
オリジナルのソースツリーが、Debian ソースパッケージツリーの最上位のディレクトリではなく、directory で指定した場所にあると仮定します。
ソースのビルドディレクトリ外にある、指定した directory をビルドディレクトリとしてソースのビルドを有効にします。directory パラメータが省略された場合はデフォルトのビルドディレクトリが利用されます。

このオプションが指定されない場合は、ビルドシステムがソースツリー外でのビルドを必要とする、あるいはそちらが望ましいと判断されない限り、デフォルトではソースディレクトリ内部でビルドが行われます。その場合、--builddirectory が指定されていなくてもデフォルトのビルドディレクトリが使用されます。

ビルドシステムが、ソースディレクトリ以外の場所でビルドを選択してしまうけれどもソースディレクトリでのビルドが可能な場合には、ソースディレクトリのパスと同じものとしてビルドディレクトリのパスを指定すれば、ソースディレクトリ内でビルドを行うようにできます。

ビルドシステムがサポートしている場合、並列ビルドを有効にするかどうかを管理します。どれだけの数でジョブを並列にするかは、ビルドが行われる際に DEB_BUILD_OPTIONS 環境変数によって決定されます (Debian ポリシーマニュアル、4.9.1章)。ビルドシステム固有の制限に影響を受ける場合もあります。

どちらのオプションも指定されていない場合、debhelper は現在では互換性レベル 10 (以降) の場合は --parallel をデフォルトに、そうでない場合は --no-parallel が指定されます。

これらのオプションが不要である場合、あるいはこのオプションだけが渡された場合には、dh はこれらのオプションをサブプロセスに渡すのを最適化のため避けようとします。特に、これは DEB_BUILD_OPTIONS が parallel パラメーターを持たない (またはこの値が 1 である) 場合に起こります。

このオプションは --parallel とともに利用し、並列ビルドにおける並列数の上限を引き上げます。もしパッケージが、とある並列数まででしかビルドできないことがわかっている場合、このオプションを使って最大限の並列数または利用したい並列数を指定できます。

特に、最大値を 1 に設定するのは --no-parallel を使うのと同じ効果があります。

このシステム上で、debhelper がサポートしているビルドシステム一覧を表示します。この一覧にはデフォルトのビルドシステム、そしてサードパーティー製 (であると明記されている) ビルドシステムの双方を含みます。また、どれが自動的に選択されたか、あるいは手動で --buildsystem オプションにて何が指定されたのかも表示します。

互換性レベル

時が経ち、後方互換性を崩すような大きな変更を debhelper にする必要がでてきました。これは、変化に対して debhelper の構造を綺麗でうまく設計されたままに保つ必要があることと、debhelper の作者がより経験を得てより深く考えるようになったためです。このような大きな変更によって既存のパッケージを壊さないようにするため、互換性レベルという考え方が導入されました。debhelper にどの互換性レベルを使うべきかを指定することで、これに合わせて動作が様々に変化します。互換性レベルは debian/compat ファイルで指定され、このファイルは必須となっています。

数字を debian/compat に記述して、debhelper にどの互換性レベルを使うかを教えます。例えば、v11 モードを使うには次の様にします:

  % echo 11 > debian/compat

パッケージは、利用する互換性レベルと同じ (あるいはそれ以上) のバージョンの debhelper プログラムをビルド依存として設定する必要があります。互換性レベル 11 の場合、debian/control ファイルが以下の様になっていることを確認してください:

  Build-Depends: debhelper (>= 11~)

特に指定が無い場合、debhelper のドキュメントは最新の互換性レベルを利用している事を前提とおり、多くの場合では以前の互換性レベルではどう動作が異なるかについては言及していません。最新の互換性レベルを使っていない場合には、それ以前の互換性レベルとはどう動作が違うのか、以下の説明を参照しておく事をおすすめします。

Supported compatibility levels

利用可能な互換性レベルは以下の通りです:

これはサポートされている最低限の互換性レベルです。

これ以前の互換性レベルからアップグレードしようとしている場合、debhelper-obsolete-compat(7) を確認して下さい。

このモードは廃止されました。

v5 からの変更点:
  • メンテナンス用スクリプトの一部を生成するコマンドは、prerm と postrm スクリプト用にこれらを逆順に並び替えるようになりました。
  • dh_installwm は x-window-manager.1.gz という slave な man ページへリンクを作るようになりました。これはパッケージビルドディレクトリ内の usr/share/man/man1 ディレクトリに man ページがある場合に行われます。
  • dh_builddeb は、CVS:.svn:.git のように除外する対象を DH_ALWAYS_EXCLUDE に指定しても該当するファイルを削除していませんでした。本互換性レベルでは削除するようになっています。
  • dh_installman は、パッケージビルドディレクトリにすでに存在する man ページを上書きしても良くなりました。これより以前の互換性レベルの元では、このような動作は何の警告もなく拒絶されていました。

このモードは廃止されました。

v6 からの変更点:
  • もし、debian/tmp 以下にあるようなファイルが、カレントディレクトリにない場合 (もしくは、--sourcedir で指定したディレクトリにない場合) 、dh_install は debian/tmp を探しにいくようになりました。この振る舞いの変更により、dh_install に特に何か引数を指定しなくても、debian/tmp にインストールしようとする dh_auto_install と協調して動作できるようになりました。
  • dh_clean は debian/clean を読み、そこに記載されているファイルを消すようになりました。
  • dh_clean はビルドディレクトリの最上位の階層にある *-stamp ファイルを消すようになりました。
  • dh_installchangelogs は、何も指定しなくてもどのファイルが upstream の changelog であるかを推定するようになりました。

このモードは廃止されました。

v7 からの変更点:
  • 未定義のオプションを渡そうとすると、警告文を出して処理続行するのではなく、エラーにして処理を失敗させるようになりました。
  • dh_makeshlibs は、shlibs ファイルを作成する為に、dpkg-gensymbols をすべての共有ライブラリに対して実行するようになりました。-X を指定すると実行を除外するライブラリを指定できます。また、通常ではない場所にライブラリがある為 dh_makeshlibs へ渡す前に dpkg-gensymbols が処理できないような場合、パッケージのビルドが失敗に終わるようになりました。
  • dh は最初のパラメータとして、一連の処理の名前を指定し、その次にオプションを記載しなければならなくなりました。つまり、"dh $@ --foo" が正しく、"dh --foo $@" は間違いとなります。
  • dh_auto_* は Makefile.PL ファイルよりも、Perl の Module::Build モジュールを優先して利用するようになりました。

このモードは廃止されました。

v8 からの変更点:
  • multiarch をサポートします。特に dh_auto_configure は autoconfコマンドへ --libdir や --libexecdir に multiarch 用途のディレクトリを渡すようになっています。
  • dh コマンドは debian/rules に記載されているターゲット間の一般的な依存性を考慮します。そのため、"dh binary" は rules ファイルに存在する build, build-arch, build-indep, install 等のターゲットを実行していきます。つまり、他のターゲットに関する依存関係をいちいち細かく明示した binary ターゲットを用意する必要はありません。
  • dh_strip はデバッグシンボルファイルを圧縮し、-dbg パッケージのインストール時に必要とする容量を削減します。
  • dh_auto_configure は、autoconf を使ったときに、--libexecdir にソースパッケージ名を追加しなくなりました。
  • dh は --with=python-support オプションを、デフォルトでは無効にするようになりました。

    (Obsolete: As the dh_pysupport tool was removed from Debian stretch. Since debhelper/10.3, dh no longer enables this sequence add-on regardless of compat level)

  • すべての dh_auto_* debhelper プログラムと dh コマンドは、dpkg-buildflags で指定される環境変数を設定します。すでに該当する環境変数が設定されている場合は設定を行いません。
  • dh_auto_configure は、dpkg-buildflags によって設定されるCFLAGS、CPPFLAGS, LDFLAGS パラメータを Makefile.PL や Build.PL へ引き渡します。
  • dh_strip は build-id に基づく場所に、分離したデバッグシンボルを配置します。
  • 実行可能権限を付与した debhelper 用の設定ファイルは、実行され出力が設定として扱われます。
v9 からの変更点:
  • dh_installinit は、init スクリプトとして debian/package という名前でファイルをインストールしなくなりました。
  • dh_installdocs は、アーキテクチャ "all" と 非 "all" のパッケージ間で --link-doc で作られたリンクが binNMU を壊すのを検知してエラーを吐き出すようになります。
  • dh は、実行している debhelper コマンドをスキップした場合にはパッケージビルドディレクトリを作成しなくなりました。これは debhelper コマンドのみを使ってビルドされているパッケージには影響しませんが、debhelper に含まれていないコマンドのバグを暴くかもしれません。
  • dh_installdebは、メンテナが提供した debian/package.shlibs ファイルをインストールしなくなりました。現在これは、dh_makeshlibs によって代わりに行われます。
  • dh_installwm は、man ページが見つからない場合に壊れたパッケージを作成するのを拒否するようになりました (x-window-manager の alternative 登録に必要)。
  • debhelper は、並列ビルドをサポートしている全てのビルドシステムで、デフォルトで --parallel を使用します。これは、--no-parallel を使うか --max-parallel へ 1 の値を渡すことで無効にできます。
  • dh コマンドは、使われなくなった "手動シーケンスコントロール" パラメーター(--before, --after など)を受け付けなくなります。代わりに override ターゲットを使ってください。
  • dh コマンドはどのコマンドが実行されたのかを追跡するのにログファイルを使わなくなります。dh コマンドは 依然として 既に "build" シーケンスを実行したかどうかを記録し、もし実行されていたらスキップします。

    これの主な影響:

  • これにより、install 及び binary シーケンスを ("clean 及び rebuild" のサイクルを全て実施する必要が無くなり) 気軽に再実行可能になったため、デバッグがより簡単になっています。
  • The main caveat is that dh_* now only keeps track of what happened in a single override target. When all the calls to a given dh_cmd command happens in the same override target everything will work as before.

    動かなくなる可能性がある例:

      override_dh_foo:
    dh_foo -pmy-pkg
  override_dh_bar:
    dh_bar
    dh_foo --remaining

    この場合、dh_foo --remaining の呼び出しは、dh_foo -pmy-pkg が分かれている override ターゲット内にあるため、my-pkg も含みます。この問題は --remaining に限らず -a, -i なども含みます。

  • dh_installdeb コマンドは maintscript 設定ファイル内の行をシェルエスケープするようになりました。これは元々意図していた動作でしたが正しく動作しておらず、パッケージが不完全なシェルエスケープ (例: ファイル名のクォート) に依存するようになっていました。
  • dh_installinit コマンドは標準で --restart-after-upgrade を利用するようになりました。以前の動作が必要なパッケージには --no-restart-after-upgrade を利用してください。
  • autoreconf シーケンスが標準で有効になりました。指定のパッケージでこの動作を望まない場合は、dh に --without autoreconf を指定してください。
  • systemd シーケンスが標準で有効になりました。指定のパッケージでこの動作を望まない場合は、dh に --without systemd を指定してください。
これが動作推奨モードです。

v10 からの変更点:

  • dh_installinit no longer installs service or tmpfile files, nor generates maintainer scripts for those files. Please use the new dh_installsystemd helper.
  • The dh_systemd_enable and dh_systemd_start helpers have been replaced by the new dh_installsystemd helper. For the same reason, the systemd sequence for dh has also been removed. If you need to disable the dh_installsystemd helper tool, please use an empty override target.

    Please note that the dh_installsystemd tool has a slightly different behaviour in some cases (e.g. when using the --name parameter).

  • dh_installdirs no longer creates debian/package directories unless explicitly requested (or it has to create a subdirectory in it).

    The vast majority of all packages will be unaffected by this change.

  • The makefile buildsystem now passes INSTALL=install --strip-program=true to make(1). Derivative buildsystems (e.g. configure or cmake) are unaffected by this change.
  • The autoconf buildsystem now passes --runstatedir=/run to ./configure.
  • The cmake buildsystem now passes -DCMAKE_INSTALL_RUNSTATEDIR=/run to cmake(1).
  • dh_installman will now prefer detecting the language from the path name rather than the extension.
  • dh_auto_install will now only create the destination directory it needs. Previously, it would create the package build directory for all packages. This will not affect packages that only build with debhelper commands, but it may expose bugs in commands not included in debhelper.
  • The helpers dh_installdocs, dh_installexamples, dh_installinfo, and dh_installman now error out if their config has a pattern that does not match anything or reference a path that does not exist.

    Known exceptions include building with the nodoc profile, where the above tools will silently permit failed matches where the patterns are used to specify documentation.

  • The helpers dh_installdocs, dh_installexamples, dh_installinfo, and dh_installman now accept the parameter --sourcedir with same meaning as dh_install. Furthermore, they now also fall back to debian/tmp like dh_install.

    Migration note: A bug in debhelper 11 up to 11.1.5 made dh_installinfo incorrectly ignore --sourcedir.

  • The perl-makemaker and perl-build build systems no longer pass -I. to perl. Packages that still need this behaviour can emulate it by using the PERL5LIB environment variable. E.g. by adding export PERL5LIB=. in their debian/rules file (or similar).
  • The PERL_USE_UNSAFE_INC environment variable is no longer set by dh or any of the dh_auto_* tools. It was added as a temporary work around to avoid a lot of packages failing to build at the same time.

    Note this item will eventually become obsolete as upstream intends to drop support for the PERL_USE_UNSAFE_INC environment variable. When perl drops support for it, then this variable will be removed retroactively from existing compat levels as well.

  • The dh_makeshlibs helper will now exit with an error if objdump returns a non-zero exit from analysing a given file.
  • The dh_installdocs and dh_installexamples tools will now attempt to guess the "main package" for a given documentation package (e.g. pkg-doc will have pkg as main package if the latter exists). If a main package is found, most of the documentation will be installed into /usr/share/doc/main-pkg by default as recommended by Debian policy §12.3 since version 3.9.7. Notable exceptions include the copyright file and changelog files.

    The --doc-main-package option can be used when the auto-detection is insufficient.

  • The dh_strip and dh_shlibdeps tools no longer uses filename patterns to determine which files to process. Instead, they open the file and look for an ELF header to determine if a given file is an shared object or an ELF executable.

    This change may cause the tools to process more files than previously.

この互換性レベルは未だ開発中の状態です。使う場合は注意して使ってください。

Changes from v11 are:

  • The dh_makeshlibs tool now generates shlibs files with versioned dependency by default. This means that -VUpstream-Version (a.k.a. -V) is now the default.

    If an unversioned dependency in the shlibs file is wanted, this can be obtained by passing -VNone instead. However, please see dh_makeshlibs(1) for the caveat of unversioned dependencies.

  • The -s (--same-arch) option is removed. Please use -a (--arch) instead.
  • dh_clean -k の起動は deprecate 警告ではなくエラーを起こすようになりました。
  • The --no-restart-on-upgrade option in dh_installinit has been removed. Please use the new name --no-stop-on-upgrade
  • There was a bug in the doit (and similar) functions from Debian::Debhelper::Dh_Lib that made them spawn a shell in one particular circumstance. This bug is now removed and will cause helpers that rely on the bug to fail with a "command not found"-error.
  • The --list-missing and --fail-missing in dh_install has been removed. Please use dh_missing and its corresponding options, which can also see the files installed by other helpers.
  • The dh_installinit helper no longer installs configuration for the upstart init system. Instead, it will abort the build if it finds an old upstart configuration file. The error is there to remind the package maintainer to ensure the proper removal of the conffiles shipped in previous versions of the package (if any).
  • The dh_installdeb tool will do basic validation of some dpkg-maintscript-helper(1) commands and will error out if the commands appear to be invalid.
  • The dh_missing tool will now default to --list-missing.
  • The dh_makeshlibs tool will now only pass libraries to dpkg-gensymbols(1) if the ELF binary has a SONAME (containing ".so").
  • The dh_compress tool no longer compresses examples (i.e. anything installed in </usr/share/doc/package/examples>.)
  • The standard sequence in dh now includes dh_dwz and dh_installinitramfs by default. This makes the dwz and installinitramfs sequences obsolete and they will now fail with an error. If you want to skip these commands, then please insert an empty override target for them in debian/rules (e.g. override_dh_dwz:)

付記

複数のバイナリパッケージのサポート

ソースパッケージが複数のバイナリパッケージを生成する場合、デフォルトでは debhelper は実行時にすべてのバイナリパッケージを生成します。この場合ソースパッケージが、アーキテクチャ依存パッケージとアーキテクチャ非依存パッケージを同時に生成するとしたら、この振る舞いは正しくありません。というのも、debian/rules では、アーキテクチャ依存パッケージを生成するなら binary-arch ターゲット内で生成する必要があり、アーキテクチャ非依存のパッケージならば、binary-indep ターゲットで生成する必要がある為です。

これを容易にする為、どのパッケージが debhelper プログラムによって処理されるかをよりコントロールするのと同様、すべての debhelper プログラムは -a, -i, -p, -s パラメータを解釈できます。これらのパラメータは重複可能です。何も指定しない場合、debhelper プログラムは、以下の例外を除いて control ファイルに列挙されたすべてのパッケージに対して処理を行います。

まず、debian/control 中の Architecture フィールドが DEB_HOST_ARCH アーキテクチャに一致しない全てのパッケージが除外されます ("Debian ポリシー 5.6.8 章")。

また、<https://wiki.debian.org/BuildProfileSpec> にあるドラフトのポリシーによると、DEB_BUILD_PROFILES 環境変数と debian/control 中のバイナリパッケージ節の Build-Profiles フィールドの内容を元に追加でパッケージが除外されます。

Interaction between package selections and Build-Profiles

Build-Profiles affect which packages are included in the package selections mechanisms in debhelper. Generally, the package selections are described from the assumption that all packages are enabled. This section describes how the selections react when a package is disabled due to the active Build-Profiles (or lack of active Build-Profiles).

The package disabled by Build-Profiles is silently excluded from the selection.

Note you will receive a warning if all packages related to these selections are disabled. In that case, it generally does not make sense to do the build in the first place.

The option is accepted and effectively does nothing.
The option is accepted, but debhelper will not act on the package.

Note that it does not matter whether a package is enabled or disabled by default.

メンテナスクリプトの自動生成

debhelper コマンドには、Debian メンテナスクリプトの一部を自動的に生成するものがあります。もし、既存の Debian メンテナスクリプトに自動生成された部分を含むようにしたければ、コードを追加したい場所に #DEBHELPER# と追記してください。#DEBHELPER# は dh_installdeb が実行される際に、自動生成されたコードへ置換されます。

スクリプトがまったく存在しないが debhelper が何かをスクリプトに追加する必要がある場合、debhelper はスクリプトを一式生成します。

-n パラメーターを指定すると、このような debhelper プログラムによるスクリプトの自動生成を行わないようにできます (上記参照)。

挿入されるコードはシェルスクリプトなので、Perl スクリプトには直接埋め込めない事に注意してください。もし何かを Perl スクリプトに埋め込みたい場合、以下に一例を挙げます ($1, $2 等は set コマンドにより設定される事に注意):

  my $temp="set -e\nset -- @ARGV\n" . << 'EOF';
  #DEBHELPER#
  EOF
  if (system($temp)) {
     my $exit_code = ($? >> 8) & 0xff;
     my $signal = $? & 0x7f;
     if ($exit_code) {
         die("debhelper スクリプトは失敗しました。エラーコード: ${exit_code}");
     } else {
         die("debhelper スクリプトは以下のシグナルで終了されました: ${signal}");
     }
  }

様々な依存関係の自動生成

debhelper は他のパッケージに依存するようなパッケージを作成することがあります。例えば、dh_installdebconf(1) を使うと、ビルドしたパッケージは debconf パッケージにも依存するようになります。あるいは dh_installxfonts(1) を使うと、特定のバージョンの xutils に依存することになります。これらの様々な依存関係を追いかけるのは、debhelper がどのような処理を行うかによるために面倒なことになりがちです。そのため、debhelper は 自動的に依存関係を解決する機能を提供します。

他のパッケージに依存するようなパッケージを生成する debhelper コマンドは、何に依存するかについて man ページに記載してある他に、${misc:Depends} と呼ばれる変数を、自動的に生成した依存情報と置き換えます。もし debian/control にこの変数を指定すれば、debhelper は必要とする依存関係を自動的に展開するようになります。

この変数は、dh_makeshlibs(1) により生成された標準の ${shlibs:Depends} 変数とはまったく関連を持ちません。また、dh_perl(1) により生成された ${perl:Depends} 変数も同様です。debhelper コマンドの推測が実状に合わない場合は、これらを使わないようにすることも可能です。

パッケージビルドディレクトリ

デフォルトでは、すべての debhelper プログラムはパッケージに含めるファイル群をまとめる一時ディレクトリとして debian/package ディレクトリを使用します。

時折、別の一時ディレクトリを利用したくなる場合があるでしょう。この場合は、-P フラグを利用してください。例えば、"dh_installdocs　-Pdebian/tmp" では debian/tmp を一時ディレクトリとして利用できます。ただし、-P を使うと、debhelper プログラムは一度に 1 つのパッケージの処理しかできません。その為、複数のバイナリパッケージを生成するような場合、どのバイナリパッケージに対して debhelper が作用するかを指定するために -p フラグを併用する必要があります。

udeb パッケージについて

debhelper は udeb もサポートしています。debhelper で udeb パッケージを作成するには、"Package-Type: udeb" を debian/control のパッケージ定義に加えてください。debhelper は udeb ファイルを debian-installer ポリシーにあわせてビルドします。これは、パッケージの拡張子が .udeb となるファイルで、いかなるドキュメントや、preinst, postrm, prerm, config スクリプト等も省いたものです。

環境変数

以下の環境変数は debhelper の振る舞いに影響を与えることができます。正しく動作するためには、(単なる Makefile 変数ではなく) 実際の環境変数である必要があることに注意するのが重要です。これらを正しく debian/rules で指定するには、必ず "export" してください。例えば "export DH_VERBOSE" などとします。

1 を指定すると冗長出力モードになります。debhelper は動作する全てのコマンドについて出力を行うようになります。また、autoconf のようなビルドシステムについても冗長出力されたビルドログを有効にします。
quiet モードを有効にするには 1 を指定して下さい。debhelperは upstream のビルドシステムの呼び出しコマンドや、dh がどのサブコマンドが呼び出されたのかも出力しなくなり、upstream のビルドシステムによってはさらに静かになります。これは重要なメッセージに注目するのが簡単になりますが、buildd のログとしては出力は極めて使い物にならなくなります。DH_VERBOSE が同時にセットされていると無視されます。
この環境変数は、debhelper をどの互換性レベルで実行するかを一時的に指定するものです。こちらを指定すると debian/compat の値を上書きします。
1 に設定すると、何もしない (no-act) モードになります。
この環境変数に指定したものは、すべての debhelper コマンドの末尾に指定されるようになります。

dh(1) を使えば、続いて呼び出される debhelper コマンドに指定したオプションを渡すことができます。大抵の場合、こちらの方が DH_OPTIONS を使うよりも良い方法です。

こちらが設定されていると、-X オプションをサポートするすべてのコマンドに対し、-X オプションの値として環境変数の値を指定します。さらに、dh_builddeb コマンドはビルドツリーの元で環境変数の値に基づくパターンにマッチするもの全部を rm -rf するようになります。

これは CVS ソースツリーからパッケージビルドをする場合に便利な場合があります。例えば、DH_ALWAYS_EXCLUDE=CVS を指定すれば、CVS ディレクトリがビルドの際に検索されるのを防ぐことができます。あるいは、ソースの tarball にすでに CVS ディレクトリが (愚かにも) 含まれている場合、debian/rules で DH_ALWAYS_EXCLUDE=CVS 環境変数を export すれば、どこでパッケージをビルドしようとも効果を発揮するようになります。

除外したいものを複数指定したい場合は、DH_ALWAYS_EXCLUDE=CVS:.svn のようにコロンで区切ってください。

If set, this adds the specified dh addons to be run in the appropriate places in the sequence of commands. This is equivalent to specifying the addon to run with the --with flag in the debian/rules file. Any --without calls specifying an addon in this environment variable will not be run.

This is intended to be used by downstreams or specific local configurations that require a debhelper addon to be run during multiple builds without having to patch a large number of rules file. If at all possible, this should be avoided in favor of a --with flag in the rules file.

参照

/usr/share/doc/debhelper/examples/
debhelper を使うときの debian/rules ファイルの例が格納されています。
<http://joeyh.name/code/debhelper/>
Debhelper の Web サイトです。

作者

Joey Hess <joeyh@debian.org>

2018-05-23 11.3.2