目次
Debian の品質は、全ての Debian パッケージが満たす必要がある基本的要求を明示的に規定するDebian ポリシーに大きく依存しています。そして、パッケージングでの長年の経験で溜め込まれた財産である、Debian ポリシーを越えて共有してきた経験の積み重ねというものもあります。多くの非常に優秀な人々が素晴らしいツールを作っており、このツールがあなた、つまり Debian のメンテナが素晴らしいパッケージを作り、維持していくのを手助けしてくれます。
この章では、Debian 開発者へのベストプラクティスをいくつか提供します。すべての勧めは単に勧めであり、要求事項やポリシーではありません。Debian 開発者らからの主観的なヒント、アドバイス、ポインタです。あなたにとって一番うまくいくやり方を、どうぞご自由に選んでください。
以下の推奨事項は、debian/rules
ファイルに適用されます。debian/rules
は、ビルド作業を管理し、(直接にせよ、そうでないにせよ)
パッケージにどのファイルが入るかを選択します。大抵の場合、メンテナが最も時間を費やすファイルです。
debian/rules
でヘルパースクリプトを使う根拠は、多くのパッケージ間でメンテナらに共通のロジックを利用・共有させるようになるからです。メニューエントリのインストールについての問いを例にとってみましょう:
ファイルを /usr/share/menu
(必要であれば、実行形式のバイナリのメニューファイルの場合
/usr/lib/menu
)
に置き、メンテナスクリプトにメニューエントリを登録・解除するためのコマンドを追加する必要があります。これはパッケージが行う、非常に一般的なことです。なぜ個々のメンテナがこれらのすべてを自分で書き直し、時にはバグを埋め込む必要があるでしょう?
また、メニューディレクトリが変更された場合、すべてのパッケージを変更する必要があります。
ヘルパースクリプトがこれらの問題を引き受けてくれます。ヘルパースクリプトの期待するやり方に従っているならば、ヘルパースクリプトはすべての詳細について考慮をします。ポリシーの変更はヘルパースクリプト中で行えます; そして、パッケージを新しいバージョンのヘルパースクリプトでリビルドする必要があるだけです。他に何の変更も必要ありません。
付録A Debian メンテナツールの概要 には、複数の異なったヘルパーが含まれています。もっとも一般的で (我々の意見では)
ベストなヘルパーシステムは debhelper
です。debmake
のような、以前のヘルパーシステムはモノリシックでした:
使えそうなヘルパーの一部を取り出して選ぶことはできず、何を行うにもヘルパーを使う必要がありました。ですが、debhelper
は、いくつもの分割された小さな
dh_* プログラムです。たとえば、dh_installman は man
ページをインストールして圧縮し、dh_installmenu は menu
ファイルをインストールするなどします。つまり、debian/rules
内で使える部分では小さなヘルパースクリプトを使い、手製のコマンドを使うといった十分な柔軟性を与えてくれます。
debhelper(1)
を読んで、パッケージに付属している例を参照すれば、debhelper
を使い始めることができます。 dh-make
パッケージ (「dh-make
」 参照) の dh_make は、素のソースパッケージを
debhelper
化されたパッケージに変換するのに利用できます。ですが、この近道では個々の
dh_*
ヘルパーをわざわざ理解する必要がないので、満足できないでしょう。ヘルパースクリプトを使おうとするのであれば、そのヘルパーを使うこと、つまり前提と動作を学ぶのに時間を割く必要があります。
巨大で複雑なパッケージには、対処が必要なたくさんのバグが含まれているかもしれません。直接ソース中で大量のバグを修正し、あまり注意を払っていなかった場合、適用した様々なパッチを識別するのは難しいことになるでしょう。(全てではなく)
幾つか修正を取り入れた新しい開発元のバージョンへパッケージを更新する必要が出た場合、とても悲惨なことになります。(例えば、.diff.gz
から) diff をすべて適用することもできませんし、開発元で修正されたバグごとにどのパッチをバックアウトするようにすればよいのか分かりません。
幸いなことに、ソースフォーマット“3.0 (quilt)”では、パッチシステムを設定するために
debian/rules
を変更することなく、パッチを分割して保持できるようになっています。パッチは
debian/patches/
に保持され、ソースパッケージが展開されるときに
debian/patches/series
に記載されているパッチが自動的に適用されます。名前が指すように、パッチは quilt で管理することができます。
より古いソースフォーマット“1.0”を使っている場合でも、パッチを分割することは可能ですが、専用のパッチシステムを使う必要があります: パッチファイルは
Debian パッチファイル (.diff.gz
) 内に組み込まれ、通常
debian/
ディレクトリ内にあります。違いは、すぐに
dpkg-source では適用されないが、debian/rules
の
build
ルールで patch
ルールへの依存を通じて適用されることだけです。逆に言うと、これらのパッチは unpatch
ルールへの依存を通じて
clean
ルールで外されます。
quilt はこの作業にお勧めのツールです。上記の全てを行う上、パッチ一覧の管理も可能です。詳細な情報は
quilt
パッケージを参照してください。
他にもパッチを管理するツールはあります。dpatch や、パッチシステムが統合されている cdbs
などです。
単一のソースパッケージはしばしば複数のバイナリパッケージを生成します。それは、同じソフトウェアで複数のフレーバーを提供することであったり (例:
vim
ソースパッケージ)、巨大なパッケージではなく複数の小さなパッケージを作ったりします (例:
ユーザがサブセットのみをインストールできるようにして、ディスク容量を節約できます)。
二つ目の例は、debian/rules
で簡単に扱うことができます。ビルドディレクトリからパッケージの一時ツリーへ、適切なファイルを移動する必要があるだけです。これは、install
または debhelper
の
dh_install を使ってできます。パッケージ間の依存関係を
debian/control
内で正しく設定したのを忘れずに確認してください。
最初の例は、同じソフトウェアでありながら異なった設定オプションで複数回再コンパイルする必要があるので、ちょっと難しくなります。vim
ソースパッケージは、手作りの
debian/rules
ファイルを使ってどのようにこの作業を扱うか、という例です。
以下のプラクティスは、debian/control
ファイルに関するものです。パッケージ説明文についてのポリシーを補完します。
パッケージの説明文は、control
ファイルの対応するフィールドにて定義されている様に、パッケージの概要とパッケージに関する長い説明文の両方を含んでいます。「パッケージ説明文の基本的なガイドライン」
では、パッケージ説明文の双方の部分についての一般的なガイドラインが記述されています。それによると、「パッケージの概要、あるいは短い説明文」 が概要に特化したガイドラインを提供しており、そして 「長い説明文 (long description)」 が説明文 (description) に特化したガイドラインを含んでいます。
パッケージの説明文は平均的なユーザーに向けて書く必要があります。平均的な人というのは、パッケージを使って得をするであろう人のことです。例えば、開発用パッケージであれば開発者向けですし、彼ら向けの言葉でテクニカルに記述することができます。より汎用的なアプリケーション、例えばエディタなどであれば、あまり技術的ではないユーザ向けに書く必要があります。
パッケージ説明文のレビューを行った結果、ほとんどのものがテクニカルである、つまり、技術に詳しくはないユーザに通じるようには書かれてはいないという結論に達しました。あなたのパッケージが、本当に技術に精通したユーザ用のみではない限り、これは問題です。
どうやって技術に詳しくはないユーザに対して書けばいいのでしょう? ジャーゴンを避けましょう。ユーザが詳しくないであろう他のアプリケーションやフレームワークへの参照を避けましょうー GNOME や KDE については、おそらくユーザはその言葉について知っているでしょうから構いませんが、GTK+ はおそらくダメです。まったく知識がないと仮定してみましょう。技術用語を使わねばならない場合は、説明しましょう。
客観的になりましょう。パッケージ説明文はあなたのパッケージの宣伝場所ではありません。あなたがそのパッケージをどんなに愛しているかは関係ありません。その説明文を読む人は、あなたが気にすることと同じことを気にはしないであろうことを覚えておいてください。
他のソフトウェアパッケージ、プロトコル名、標準規格、仕様の名前を参照する場合には、もしあれば正規名称を使いましょう。X Windows や X-Windows や X Window ではなく、X Window System あるいは X11 または X を使いましょう。GTK や gtk ではなく GTK+ を使いましょう。Gnome ではなく GNOME を使いましょう。Postscript や postscript ではなく PostScript を使いましょう。
説明文を書くことに問題があれば、<debian-l10n-english@lists.debian.org>
へそれを送ってフィードバックを求めるとよいでしょう。
ポリシーでは、概要行 (短い説明文) はパッケージ名を繰り返すのではなく、簡潔かつ有益なものである必要がある、となっています。
概要は、完全な文章ではなくパッケージを記述するフレーズとして機能します。ですので、句読点は不適切です: 追加の大文字や最後のピリオドは不要です。また、最初の不定冠詞や定冠詞 — "a", "an", or "the" を削る必要があります。つまり、例えば以下のようになります:
Package: libeg0 Description: exemplification support library
技術的に言えば、動詞のフレーズに対して、これは名詞のフレーズから文章を差し引いたものです。パッケージ名
と要約
をこの決まり文句に代入できるのがよい見つけ方です:
パッケージの名前
は概要
を提供します。
関連パッケージ群は、概要を 2 つに分けた別の書き方をした方が良いでしょう。最初はその組一式の説明文で、その次はその組内でのパッケージの役割のサマリにします:
Package: eg-tools Description: simple exemplification system (utilities) Package: eg-doc Description: simple exemplification system - documentation
これらの要約が、手が加えられた決まり文句に続きます。パッケージ "名
"
が、"プログラム一式
(役割
)" あるいは
"プログラム一式
- 役割
"
という要約を持つ場合、要素はフレーズにすべきで、決まり文句に合うようになります:
パッケージ名
は、プログラム一式
に対する役割
を表しています。
長い説明文は、ユーザーがパッケージをインストールする前に利用可能な最初の情報です。ユーザーがインストールするか否かを決めるのに必要な情報を、すべて提供する必要があります。ユーザーがパッケージの概要を既に読んでいると仮定してください。
長い説明文は、完全な文章から成る必要があります。
長い説明文の最初の段落は、以下の質問に答えている必要があります: このパッケージは何をするの? ユーザが作業を完了するのに、どのタスクが役に立つの? ─ 技術寄りではない書き方でこれを記述するのが重要です。もちろんパッケージの利用者が必然的に技術者ではない限り、です。
続く段落は以下の質問に答える必要があります: 何故私はユーザーとしてこのパッケージを必要とするの? パッケージは他にどんな機能を持っているの? 他のパッケージと比べて、どんな特別な機能や不足している部分があるがあるの? (例: X が必要な場合、代わりに Y を使いましょう) このパッケージはパッケージマネージャーで管理していない、何らかの方法で他のパッケージに関連している? (例: これは foo サーバのクライアントです)
スペルミスや文法の間違いを避けるよう、注意してください。スペルチェックを確実に行ってください。ispell と
aspell の双方に、debian/control
ファイルをチェックするための特別なモードがあります:
ispell -d american -g debian/control
aspell -d en -D -c debian/control
通常、ユーザは以下のような疑問がパッケージ説明文で答えられることを期待しています:
パッケージは何をするの? 他のパッケージのアドオンだった場合、パッケージがアドオンであるということを概要文に書く必要があります。
なぜこのパッケージを使うべきなの? これは上記に関連しますが、同じではありません (これはメールユーザーエージェントです; クールで速く、PGP や LDAP や IMAP のインターフェイスがあり、X や Y や Z の機能があります)。
パッケージが直接インストールされるべきではないが、他のパッケージから引っ張ってこられる時には、付記しておく必要があります。
パッケージが実験的
である、あるいは使われない方が良い他の理由がある場合、同様にここに記載する必要があります。
パッケージは競合のものと比べてどうでしょうか? より良い実装なのでしょうか? 機能がより豊富なのでしょうか? 違った機能があるのでしょうか? このパッケージを選ぶ理由は何でしょう。
debian/control
中の Source
セクションの
Homepage
フィールドへ、パッケージのホームページの URL
を追加することをお勧めします。この情報をパッケージ説明文自身に追加するのは推奨されない (deprecated) であると考えられています。
debian/control
には、バージョン管理システムの場所についての追加フィールドがあります。
このフィールドの値は、指定したパッケージのメンテナンスに使われているバージョン管理システムのリポジトリのコピーがもしあれば、それを指し示す
http://
URL である必要があります。
この情報は、パッケージに行われた最新の作業を閲覧したいエンドユーザにとって有用であるのが目的です (例: バグ追跡システムで
pending
とタグがつけられているバグを修正するパッチを探している場合)。
このフィールドの値は、もし利用可能でなのであれば、指定されたパッケージをメンテナンスするのに使われているバージョン管理システムの位置を明確に識別できる文字列である必要があります。*
はバージョン管理システムの識別に使われます; 現在では、以下のシステムがパッケージ追跡システムによってサポートされています:
arch
、bzr
(Bazaar)、cvs
、darcs
、git
、hg
(Mercurial)、mtn
(Monotone)、svn
(Subversion)。同じパッケージについて異なった VCS を指定することも可能です: これらはすべて PTS
のウェブインターフェイスに表示されます。
この情報は、そのバージョン管理システムについて知識があり、VCS ソースから現在のバージョンパッケージを生成ユーザにとって有益であるよう意図されています。この情報の他の使い方としては、指定されたパッケージの最新の VCS バージョンを自動ビルドするなどがあるかもしれません。このため、フィールドによって指し示される場所は、バージョンに関係なく、(そのようなコンセプトをサポートしている VCS であれば) メインブランチを指すのが良いでしょう。また、指し示される場所は一般ユーザがアクセス可能である必要があります; この要求を満たすには SSH アクセス可能なリポジトリを指すのではなく、匿名アクセスが可能なリポジトリを指すようにすることを意味します。
以下の例では、vim
パッケージの Subversion
リポジトリに対するフィールドの例が挙げられています。(svn+ssh://
ではなく)
svn://
スキーム中で URL
がどのようになっているか、trunk/
ブランチをどのように指し示しているかに注意してください。上で挙げられた
Vcs-Browser
フィールドと Homepage
フィールドの使い方も出ています。
Source: vim Section: editors Priority: optional <snip> Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim Vcs-Browser: http://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim Homepage: http://www.vim.org
以下のプラクティスは changelog ファイルに対するポリシーを補完します。
パッケージリビジョンに対する changelog エントリは、そのリビジョンでの変更それだけを記載します。最後のバージョンから行われた、重要な、そしてユーザに見える形の変更を記述することに集中しましょう。
何が変更されたかについて集中しましょう — 誰が、どうやって、何時なのか通常あまり重要ではありません。そうは言っても、パッケージ作成について明記すべき手助けをしてくれた人々 (例えば、パッチを送ってくれた人) を丁寧に明記するのを忘れないようにしましょう。
些細で明白な変更を詳細に書く必要はありません。複数の変更点を一つのエントリにまとめることもできます。逆に言えば、大きな変更をした場合には、あまりに簡潔にしすぎないようにしましょう。プログラムの動作に影響を与える変更がある場合には、特に確認しておきましょう。詳細な説明については、README.Debian
ファイルを使ってください。
平易な英語を使いましょう。そうすれば読者の大半が理解できます。バグをクローズする変更を説明する際には略語や、テクニカルな言い方やジャーゴンを避けましょう。特に、技術的に精通していないと思われるユーザによって登録されたバグを閉じる際には気をつけましょう。礼儀正しく、断言をしないように。
時折、changelog エントリに変更したファイルの名前を頭に付けたくなることがあります。ですが、個々のすべての変更したファイルを一覧にする必要性はありません。特に変更点が小さくて繰り返される場合です。ワイルドカードを使いましょう。
バグに触れる際には、何も仮定しないようにしましょう。何が問題だったのか、どうやってそれが直されたのかについて言い、closes: #nnnnn の文字列を追加しましょう。詳細については 「新規アップロードでバグがクローズされる時」 を参照してください。
changelog エントリは、一般的なパッケージ化の事柄 (ほら、foo.conf を探しているなら /etc/blah にあるよ) を記載するべきではありません。何故なら、管理者やユーザは少なくとも Debian システム上でそのようなことがどのように扱われるかを多少は知らされているでしょうから。ですが、設定ファイルの場所を変更したのであれば、それは一言添えておくべきです。
changelog エントリでクローズされるバグは、実際にそのパッケージリビジョンで修正されたものだけにすべきです。changelog で関係ないバグを閉じるのは良くない習慣です。「新規アップロードでバグがクローズされる時」 を参照してください。
changelog エントリは、バグ報告者との各種の議論の場 (foo をオプション bar 付きで起動した際にはセグメンテーションフォルトは見られません; もっと詳しい情報を送ってください)、生命、宇宙、そして万物についての概要 (すいませんが、このアップロードに時間がかかったので風邪をひきました)、手助けの求め (このパッケージのバグ一覧は巨大です、手を貸してください) に使うべきではありません。そのようなことは、大抵の場合対象としている読者は気づくことが無く、パッケージで実際にあった変更点の情報について読みたい人々を悩ますことでしょう。どの様にバグ報告システムを使えばいいのかについて、詳細な情報は「バグへの対応」を参照してください。
正式なメンテナによるアップロードの changelog エントリの最初で、non-maintainer upload で修正されたバグを承認するのは、古い慣習です。今はバージョン管理を行っているので、NMU された changelog エントリを残しておいて自分の changelog エントリ中でその事実に触れるだけで十分です。
以下の例で、changelog エントリ中のよくある間違いや間違ったスタイルの例を挙げます。
* Fixed all outstanding bugs.
これは、全く読み手に何も有用なことを教えてくれません。
* Applied patch from Jane Random.
何についてのパッチですか?
* Late night install target overhaul.
何をオーバーホールしてどうなったのですか? 深夜というのに言及しているのは、私たちにこのコードを信用するなと言いたいのですか?
* Fix vsync FU w/ ancient CRTs.
略称が多すぎます。そして、ええっと、fsckup (あぁ、ひどい言葉!) は実際何だったのか、あるいはどうやって修正したのかがまったく明らかではありません。
* This is not a bug, closes: #nnnnnn.
まず初めに、この情報を伝えるためにパッケージをアップロードする必要は、全くありません; 代わりにバグ追跡システムを使ってください。次に、何故この報告がバグではなかったのかについての説明がありません。
* Has been fixed for ages, but I forgot to close; closes: #54321.
何らかの理由で以前の changelog エントリ内でバグ番号について触れていなかったとしても、何も問題はありません。単にいつも通りに BTS でバグをクローズしてください。修正の記述が既にあるものと考えて、changelog ファイルに触れる必要はありません (これは、開発元の作者/メンテナによる修正にも同様に適用されます。彼らがずっと前に修正したバグを、あなたの changelog 内で追いかける必要はありません)。
* Closes: #12345, #12346, #15432
説明はどこ? 説明文を考えられないのなら、それぞれのバグのタイトルを入れるところから始めてください。
パッケージの変更に関する重要なニュースは NEWS.Debian
ファイルにも書くことができます。このニュースは apt-listchanges
のようなツールで、残りすべての changelog
の前に表示されます。これは、ユーザにパッケージ内の著しい変更点について知らせるのに好ましいやり方です。インストール後にユーザが一旦戻って
NEWS.Debian
ファイルを参照できるので、debconf
の notes を使うより良いです。そして、目立った変更点を
README.Debian
に列挙するより良いです。何故ならば、ユーザは容易にそのような注意書きを見逃すからです。
ファイル形式は debian changelog ファイルと同じですが、アスタリスク (*) を取って各ニュースを changelog
に書くような簡潔な要約ではなく、必要に応じて完全な段落で記述してください。changelog
のようにビルド中に自動的にはチェックされないので、ファイルを dpkg-parsechangelog
を実行してチェックするのは良い考えです。実際の NEWS.Debian
ファイルの例が、以下になります:
cron (3.0pl1-74) unstable; urgency=low The checksecurity script is no longer included with the cron package: it now has its own package, checksecurity. If you liked the functionality provided with that script, please install the new package. -- Steve Greenland <stevegr@debian.org> Sat, 6 Sep 2003 17:15:03 -0500
NEWS.Debian
ファイルは
/usr/share/doc/
ファイルとしてインストールされます。圧縮されていて、Debian
ネイティブパッケージ中でも常にこの名前です。package
/NEWS.Debian.gzdebhelper
を使う場合は、dh_installchangelogs
が
debian/NEWS
ファイルをインストールしてくれます。
changelog ファイルと違って、毎回のリリースごとに NEWS.Debian
ファイルを更新する必要はありません。何か特にユーザが知るべき目新しいことがあったときにのみ、更新してください。全くニュースがない場合、NEWS.Debian
ファイルをパッケージに入れてリリースする必要はありません。便りが無いのは良い知らせ、です (No news is good news!)。
メンテナスクリプトには
debian/postinst
、debian/preinst
、debian/prerm
、debian/postrm
ファイルが含まれます。これらのスクリプトは、単なるファイルやディレクトリの作成や削除では扱われない、パッケージのインストールと削除のセットアップの面倒をみます。以下の説明は、Debian ポリシーを補完します。
メンテナスクリプトは冪等でなければなりません。これは、通常は 1 回呼ばれるスクリプトが 2 回呼ばれた場合、何も悪いことが起きないのを保証する必要があるという意味です。
標準入出力はログの取得のためにリダイレクトされることがあります (例: パイプへ向けられる)。ですので、これらが tty であることに依存してはいけません。
質問や対話的な設定はすべて最小限に止めておく必要があります。必要になった時は、インターフェイスに debconf
パッケージを使いましょう。どのような場合でも、質問は
postinst
スクリプトの configure
段階にのみ、配置することができます。
メンテナスクリプトは、できる限りシンプルなものにしておきましょう。我々は、あなたは純粋な POSIX
シェルスクリプトを使っているものだと考えています。覚えておいて欲しいのですが、何かしら bash の機能が必要になったら、メンテナスクリプトは bash
のシェバン行にしておく必要があります。スクリプトへ簡単にちょっとした変更を追加するのに debhelper
を使えるので、Perl より POSIX シェル、あるいは Bash
の方が好まれます。
メンテナスクリプトを変更したら、パッケージの削除や二重インストール、purge のテストを確認してください。purge されたパッケージが完全に削除されたことを確認してください。つまり、メンテナスクリプト中で直接/間接を問わず作成されたファイルを削除する必要があるということです。
コマンドの存在をチェックする必要がある場合は、このような感じで行います
if [ -x /usr/sbin/install-docs ]; then ...
メンテナスクリプト中でコマンドの path をハードコードしたくない場合には、以下の POSIX 互換シェル機能が役立つでしょう:
pathfind() { OLDIFS="$IFS" IFS=: for p in $PATH; do if [ -x "$p/$*" ]; then IFS="$OLDIFS" return 0 fi done IFS="$OLDIFS" return 1 }
コマンド名を引数として渡すことで、$PATH
の検索するのにこの関数を使うことができます。コマンドが見つかった場合は true (ゼロ) を返し、そうでない場合は false
を返します。command
-v
、type、which は POSIX
に無いので、これがもっとも汎用性の高いやり方です。
which は、Required となっている debianutils
パッケージにあるので、別解として利用可能ですが、ルートパーティションにありません。つまり、/usr/bin
にあって /bin
ではないので、/usr
パーティションがマウントする前に走るスクリプトの中では使えないということです。ほとんどのスクリプトは、この問題を持つようなことはありませんが。
debconf
は、(主に
postinst
をはじめとする)
すべての様々なパッケージスクリプトが、ユーザはどの様にパッケージを設定したいのかというフィードバックを問い合わせるのに使うことが可能な設定管理システムです。直接ユーザとの対話処理は、debconf
での処理の方を選んだので、現状では避けるべきです。これにより、将来には非対話的なインストールが可能になる予定です。
debconf は素晴らしいツールですが、しばしば適当に扱われています。多くの共通する失敗は、debconf-devel(7) man ページに記載されています。これは、debconf を使うのを決めた時、あなたが読むべきものです。また、ここではベストプラクティスを記述しています。
これらのガイドラインは、ディストリビューションの一部 (例えば、インストールシステム) に関する、より明確な推奨と同様に、幾つかの書き方と体裁に関する推奨、そして debconf の使い方についての一般的な考慮すべき事柄を含んでいます。
debconf が Debian に現れて以来、広く乱用され続けています。そして、debconf の乱用によって、ちょっとしたものをインストールする前に、大量の質問に答える必要があることに由来するいくつもの非難が Debian ディストリビューションに寄せられました。
使い方のメモは載せるべきところへ載せましょう: NEWS.Debian
、または
README.Debian
ファイルです。notes
はパッケージのユーザビリティに直接影響する重要な記述にだけ使いましょう。notes は確認する (あるいはメールでユーザを悩ます)
まで、インストールを常にブロックすることを覚えておいてください。
メンテナスクリプト中の質問の優先度を注意深く選びましょう。優先度の詳細については、debconf-devel(7) を参照してください。ほとんどの質問は優先度が medium あるいは low を使うべきです。
ほとんどの Debian パッケージメンテナはネイティブの英語話者ではありません。ですので、正しいフレーズのテンプレートを書くのは彼らにとっては容易ではありません。
<debian-l10n-english@lists.debian.org>
メーリングリストを利用してください
(むしろ乱用してください)。テンプレートを査読してもらいましょう。
下手に書かれたテンプレートは、パッケージに対して、そしてあなたの作業に対して、さらには Debian それ自体にすら対して、悪い印象を与えます。
可能な限り技術的なジャーゴンを避けましょう。いくつかの用語があなたにとっては普通に聞こえても、他の人には理解不可能かもしれません。避けられない場合には、 (説明文を使って) 解説してみましょう。その場合には、冗長さとシンプルさのバランスを取るようにしましょう。
debconf テンプレートは翻訳されるでしょう。debconf、そして関連する姉妹パッケージ po-debconf は、テンプレートを翻訳チームやさらには個人が翻訳できるようにする、シンプルなフレームワークを提供します。
gettext ベースのテンプレートを使ってください。開発用のシステムに po-debconf
をインストールしてドキュメントを読みましょう (man
po-debconf が取っ掛かりとして良いでしょう)。
テンプレートを頻繁に変更しすぎることを避けましょう。テンプレート文の変更は、翻訳を fuzzy にして、さらなる作業を翻訳作業者に強います。fuzzy
になっている翻訳文は、翻訳されてから元の文章が変更された文字列であり、使えるようにするには翻訳作業者による若干の更新が必要なものです。変更点が十分に小さい場合、fuzzy
とマークされますが、元の翻訳文は PO ファイル中に保持されます。
大本のテンプレートを変更する予定がある場合、po-debconf
パッケージで提供されている、podebconf-report-po
という名の通知システムを使って翻訳作業者にコンタクトを取ってください。ほとんどのアクティブな翻訳作業者たちはとても反応が良く、変更を加えたテンプレートに対応するための作業をしてくれ、あなたが追加でアップロードする必要を減らしてくれます。gettext
ベースのテンプレートを使っている場合、翻訳作業者の名前とメールアドレスは PO
ファイルのヘッダに表示されており、podebconf-report-po によって使われます。
このユーティリティの使い方のお勧めの使い方:
cd debian/po && podebconf-report-po --call --languageteam --withtranslators --deadline="+10 days"
このコマンドは、まず debian/po
にある PO ファイルと POT ファイルを
debian/po/POTFILES.in
に記載しているテンプレートファイルを使って同期します。そして、<debian-i18n@lists.debian.org>
メーリングリストに call for new
translations (新しい翻訳作業の募集) を送信します。最後に、call for translation updates
(翻訳更新作業者の募集) を (各 PO ファイルの Language-Team
欄に記載されている)
各言語チームおよび (Last-translator
に記載されている) 最後の翻訳者に送信します。
翻訳作業者に締切りを伝えるのは常にお勧めです。それによって、彼らは作業を調整できます。いくつかの翻訳作業チームは形式化された翻訳/レビュープロセスを整えており、10 日未満の猶予は不合理であると考えられています。より短い猶予期間は強すぎるプレッシャーを翻訳チームに与えるので、非常に些細な変更点に対してのみに留めるべきです。
迷った場合は、該当の言語の翻訳チーム (debian-l10n-xxxxx@lists.debian.org) か <debian-i18n@lists.debian.org>
にも問い合わせましょう。
debconf テンプレートの文章が修正されて、その変更が翻訳に影響しないと確信している場合には、翻訳作業者を労って翻訳文を fuzzy を取り除いてください。
そうしないと、翻訳作業者が更新をあなたに送るまでテンプレート全体は翻訳されていない状態になります。
翻訳をfuzzy ではなくすために、(po4a
パッケージの一部である)msguntypot
を使うことができます。
POT ファイルと PO ファイルを再生成する。
debconf-updatepo
POT ファイルのコピーを作成する。
cp templates.pot templates.pot.orig
すべての PO ファイルのコピーを作成する。
mkdir po_fridge; cp *.po po_fridge
debconf テンプレートファイルを誤字修正のために変更する。
POT ファイルと PO ファイルを再生成する (もう一度)。
debconf-updatepo
この時点では、typo 修正はすべての翻訳を fuzzy にしており、この残念な変更はメインディレクトリの PO ファイルと fridge の PO ファイルのみに適用されている。ここではどの様にしてこれを解決するかを示す。
fuzzy になった翻訳を捨て、fridge から作り直す。
cp po_fridge/*.po .
手動で PO ファイルと新しい POT ファイルをマージするが、不要な fuzzy を考慮に入れる。
msguntypot -o templates.pot.orig -n templates.pot *.po
ゴミ掃除。
rm -rf templates.pot.orig po_fridge
テンプレートのテキストは、debconf のインターフェイスに属するウィジェットには言及してはいけません。「はい」と答えた場合には... のような文章は、2 択の質問に対してチェックボックスを使うようなグラフィカルインターフェイスのユーザには何の意味もありません。
文字列テンプレートは、説明文中でのデフォルト値について言及することも避けましょう。まず、ユーザによってそして、デフォルト値はメンテナの考え方によって違う場合があるからです (たとえば、debconf データベースが preseed で指定されている場合など)。
より一般的に言うと、ユーザの行動を参照させるのを避けるようにしましょう。単に事実を与えましょう。
(I will do this... や We recommend... などの) 一人称の利用を避けましょう。コンピュータは人ではなく、debconf テンプレートは Debian 開発者を代弁するものではありません。中立的な解釈を行いましょう。あなたが科学論文を書いたことがあるならば、論文を書くのと同様にテンプレートを書きましょう。ですが、可能であれば This can be enabled if... ではなく Enable this if ... などとして生の声を届けるようにしましょう。
この章の情報は、ほとんどを debconf-devel(7) マニュアルページから得ています。
ユーザにパスワードの入力を求めます。これを使う場合は注意して使ってください: ユーザが入力したパスワードは debconf のデータベースに書き込まれることに注意してください。おそらく、この値をデータベースから可能な限り早く消す必要があります。
複数の値から一つを選びます。選択するものは 'Choices'
というフィールド名で指定されている必要があります。利用可能な値をコンマとスペースで区切ってください。以下のようになります:
Choices: yes, no, maybe
選択肢が翻訳可能な文字列である場合、'Choices' フィールドは __Choices
を使って翻訳可能であることを示しておくと良いでしょう。2つのアンダースコアは、各選択肢を分かれた文字列に分割してくれます。
po-debconf システムは、翻訳可能ないくつかの選択肢のみをマークする面白い機能を提供してくれます。例:
Template: foo/bar Type: Select #flag:translate:3 __Choices: PAL, SECAM, Other _Description: TV standard: Please choose the TV standard used in your country.
この例では、他は頭文字から構成されていて翻訳できませんが、'Other' 文字列だけは翻訳可能です。上記では 'Other' だけが PO および POT ファイルに含めることができます。
debconf テンプレートのフラグシステムは、この様な機能をたくさん提供します。po-debconf(7) マニュアルページでは、これらの利用可能な機能をすべて列挙しています。
本来質問ではありませんが、このデータ型が示すのはユーザに表示することができる覚え書きです。debconf はユーザが必ず参照するようにするため、多大な苦痛を与えることになる (キーを押すためにインストールを休止したり、ある場合にはメモをメールさえする) ので、ユーザが知っておく必要がある重要な記述にのみ使うべきです。
テンプレート説明文は 2 つのパートに分かれます: short と extended です。短い説明文 (short description) はテンプレートの Description: 行にあります。
短い説明文は、ほとんどの debconf インターフェイスに適用するように、短く (50 文字程度に) しておく必要があります。通常、翻訳はオリジナルよりも長くなる傾向にあるので、短くすることは翻訳作業者を助けます。
短い説明文はそれ単体で成り立つようにしておく必要があります。いくつかのインターフェイスは、デフォルトでは長い説明文を表示せず、ユーザが明示的に尋ねたときに表示するか、あるいは全く表示しません。「What do you want to do?」のような表現を避けてください。
短い説明文は完全な文章である必要はありません。これは文章を短くしておき、効率的に推奨を行うためです。
拡張された説明文 (extended description) は、短い説明文を一語一句繰り返しをしてはなりません。長い説明文章を思いつかなければ、まず、もっと考えてください。debian-devel に投稿しましょう。助けを求めましょう。文章の書き方講座を受講しましょう! この拡張された説明文は重要です。もし、まったく何も思いつかなければ、空のままにしておきましょう。
拡張された説明文は完全な文章である必要があります。段落を短くしておくのは可読性を高めます。同じ段落で 2 つの考えを混ぜてはいけません。代わりに別の段落を書きます。
あまり冗長にしないようにしてください。ユーザは長すぎる画面を無視しようとします。経験からすると、20 行が越えてはならない境界です。何故ならば、クラシックなダイアログインターフェイスでは、スクロールする必要がでてくることになり、そして多くの人がスクロールなどしないからです。
拡張された説明文では、質問を含めては決していけません。
テンプレートの type (string、boolean など) に応じた特別なルールについては、以下を読んでください。
このフィールドは select あるいは multiselect 型に使ってください。これには、ユーザに表示される可能な選択肢が含まれます。これらの選択肢はコンマで区切る必要があります。
以下は、テンプレートの型に応じて適切な Description (short および extended) を書くための特別な指示です。
短い説明文は、プロンプトであってタイトルではありません。質問形式のプロンプト (IP アドレスは?) を避け、代わりに閉じていない形のプロンプト (IP アドレス:) を使ってください。コロン (:) の使用をお勧めします。
拡張された説明文は、短い説明文を補足します。拡張の部分では、長い文章を使って同じ質問を繰り返すのではなく、何を質問されているのかを説明します。完全な文章を書いてください。簡潔な書き方は強く忌避されます。
短い説明文は、短いままで大抵の場合は ? で終わる質問の体裁の言い回しをせねばなりません。簡潔な書き方は許されており、質問が若干長い場合は推奨されすらしています (翻訳文は、大抵の場合原文よりも長くなるのを覚えておきましょう)。
繰り返しますが、特定のインターフェイスのウィジェットを参照するのを避けてください。このようなテンプレートで良くある間違いは、「はい」と答える形かどうかです。
短い説明文は、プロンプトであってタイトルではありません。「Please choose...」のような意味の無い文章を文章を使わないでください。ユーザは何かを選ぶ必要があるくらいには十分賢いです... :)
拡張された説明文は、短い説明文を完備します。これでは、利用可能な選択肢に言及することがあります。テンプレートが multiselect なものの場合、ユーザが選べる選択肢が 1 つではないことについても言及するかもしれません (インターフェイスが大抵これを明確にはしてくれますが)。
短い説明文はタイトルとして扱われます。
拡張された説明文では、note のより詳細な説明を表示します。フレーズで、簡潔過ぎない書き方です。
debconf を乱用しないでください。 note は、debconf
の乱用で最も良く使われます。debconf-devel マニュアルページに書かれています:
とても深刻な問題について警告する場合のみに使うのがベストです。多くの覚え書きについては、NEWS.Debian
ファイルや README.Debian
ファイルが適切な場所です。もし、これを読んで、Note
型のテンプレートを NEWS.Debian
あるいは
README.Debian
中のエントリに変換することを考えた場合、既存の翻訳を捨てないことを検討してください。
もし Choise が頻繁に変わるようであれば、__Choices という使い方をするのを検討してください。これは個々の選択項目を単一の文字列に分割するので、翻訳作業者が作業を行うのを助けてくれると考えられています。
select のテンプレートで、デフォルト値がユーザの言語に応じて変化するようであれば、_Default という使い方をしてください (例えば、選択肢が言語の選択の場合等) 。
この特別なフィールドによって、翻訳作業者は言語に応じたもっとも適切な選択肢を挿入することができるようになります。彼らの言語が選択された場合にデフォルトの選択になりますが、英語を使うときには最初に提示された Default Choice が使われます。
geneweb パッケージのテンプレートを例にとってみましょう:
Template: geneweb/lang Type: select __Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian (it), Japanese (ja), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv) # This is the default choice. Translators may put their own language here # instead of the default. # WARNING : you MUST use the ENGLISH NAME of your language # For instance, the french translator will need to put French (fr) here. _Default: English[ translators, please see comment in PO files] _Description: Geneweb default language:
ブラケットを使うと、debconf のフィールド中に内部コメントができることに注意してください。コメントの利用は、翻訳作業者が作業するファイルに表示されるのにも注意ください。
_Default を使うやり方は、若干混乱するのでコメントが必要です: 翻訳者は自身の選択肢を書きます。
空のデフォルトフィールドを使っては「いけません」。デフォルト値を設定したくないのであれば、Default は使うべきではありません。
po-debconf を使うのであれば (そして 使うべき です、「翻訳者へ丁寧に接する」 参照)、このフィールドが翻訳できるのであれば、翻訳可能な状態にするのを検討しましょう。
(例えば言語選択のデフォルト値など) デフォルト値が言語/地域に応じて変化するようであれば 、po-debconf(7) に記載されている特別な _Default 型を使うことを考えましょう。
この章では、開発者に対して、翻訳作業者の作業がより楽になるようにするための大まかな情報を含めています。国際化について興味を持っている翻訳作業者と開発者への詳細な情報は、Internationalisation and localisation in Debian で入手できます。
移植作業者同様に、翻訳作業者は難しい課題を抱えています。多くのパッケージについて作業を行い、多くの異なったメンテナと共同作業をする必要があります。さらには、ほとんどの場合、彼らはネイティブな英語話者ではないので、あなたは特に忍耐強くあらねばいけないでしょう。
debconf
のゴールはメンテナとユーザにとってパッケージ設定を簡単にすることでした。元々、debconf
テンプレートの翻訳はdebconf-mergetemplate
で行われていました。しかし、このやり方は現在は非推奨 (deprecated) です; debconf
の国際化を成し遂げる最も良いやり方は、po-debconf
パッケージを使うことです。このやり方はメンテナと翻訳者の双方にとって、より楽なやり方です; 移行スクリプトが提供されています。
po-debconf
を使うと、翻訳は
.po
ファイルに収められます (gettext
による翻訳技術からの引き出しです)。特別なテンプレートファイルには、元の文章と、どのフィールドが翻訳可能かがマークされています。翻訳可能なフィールドの値を変更すると、debconf-updatepo
を呼び出すことで、翻訳作業者の注意が必要なように翻訳にマークがされます。そして、生成時には
dh_installdebconf
プログラムが、テンプレートに加え、最新の翻訳をバイナリパッケージに追加するのに必要となる魔法について、すべての面倒を見ます。詳細は
po-debconf(7) マニュアルページを参照してください。
ドキュメントの国際化はユーザにとって極めて重要ですが、多くの労力がかかります。この作業をすべて除去する方法はありませんが、翻訳作業者を気楽にはできます。
どのようなサイズであれドキュメントをメンテナンスしている場合、翻訳作業者がソースコントロールシステムにアクセスできるのであれば、彼らの作業が楽になるでしょう。翻訳作業者が、ドキュメントの
2
つのバージョン間の違いを見ることができるので、例えば、何を再翻訳すればいいのかがわかるようになります。翻訳されたドキュメントは、翻訳作業がどのソースコントロールリビジョンをベースにしているのかという記録を保持しておくことをお勧めします。debian-installer
パッケージ中の doc-check
では興味深いシステムが提供されています。これは、翻訳すべき現在のリビジョンのファイルに対する構造化されているコメントを使って、指定されたあらゆる言語の翻訳状況の概要を表示し、翻訳されたファイルについては、翻訳がベースにしているオリジナルのファイルのリビジョンを表示します。自分の
VCS 領域でこれを導入して利用した方が良いでしょう。
XML あるいは SGML のドキュメントをメンテナンスしているのであれば、言語非依存の情報を分離し、それらをすべての異なった翻訳に含まれる分割されたファイルにエンティティとして定義した方が良いでしょう。これは、URL を複数のファイル間で最新に保つなど、作業をより楽にしてくれます。
いくつかのツール (例: po4a
、poxml
、translate-toolkit
)
は異なった形式から翻訳可能な素材を展開するのに特化しています。これらは、翻訳作業者には極めて馴染み深い形式である PO
ファイルを生成します。これによって、翻訳したドキュメントが更新された際に何を再翻訳すればよいのかを見ることを可能にしてくれます。
autoconf の config.sub
および
config.guess
を最新に保ちつづけるのは、移植作業者、特により移行中の状況であるアーキテクチャの移植作業者にとって非常に重要です。autoconf
や automake を使うあらゆるパッケージについてのとても素晴らしいパッケージ化における教訓が
autotools-dev
パッケージの
/usr/share/doc/autotools-dev/README.Debian.gz
にまとめられています。このファイルを読んで書かれている推奨に従うことを強くお勧めします。
ライブラリは様々な理由から常にパッケージにするのが難しいです。ポリシーは、メンテナンスに楽にし、新しいバージョンが開発元から出た際にアップグレードを可能な限りシンプルであることを確保するため、多くの制約を課しています。ライブラリでの破損は、依存している何十ものパッケージの破損を招き得ます。
ライブラリのパッケージ化の良い作法が the library packaging guide にまとめられています。
ドキュメント化のポリシーに忘れず従ってください。
あなたのパッケージが XML や SGML から生成されるドキュメントを含んでいる場合、XML や SGML のソースをバイナリパッケージに含めてリリースしないことをお勧めします。ユーザがドキュメントのソースを欲しい場合には、ソースパッケージを引っ張ってくれば良いのです。
ポリシーではドキュメントは HTML 形式でリリースされるべきであると定めています。我々は、もし手がかからないで問題ない品質の出力が可能であれば、ドキュメントを PDF 形式とテキスト形式でもリリースすることをお勧めしています。ですが、ソースの形式が HTML のドキュメントを普通のテキスト版でリリースするのは、大抵の場合は適切ではありません。
リリースされたメジャーなマニュアルは、インストール時にdoc-base
で登録されるべきです。詳細については、doc-base
パッケージのドキュメントを参照してください。
Debian ポリシー (12.1 章) では、マニュアルページはすべてのプログラム・ユーティリティ・関数に対して付属すべきであり、設定ファイルのようなその他のものについては付属を提案を示しています。もし、あなたがパッケージングをしているものがそのようなマニュアルページを持っていない場合は、パッケージに含めるために記述を行い、開発元 (upstream) へ送付することを検討してください。
manpage は直接 troff 形式で書く必要はありません。よく使われるソース形式は、Docbook、POD、reST で、それぞれ xsltproc、pod2man、rst2man を使うことで変換できます。少なくとも、スタブを書くために help2man プログラムを使うことは可能です。
いくつかの特定の種類のパッケージは、特別なサブポリシーと対応するパッケージ化ルールおよびプラクティスを持っています:
Perl 関連パッケージは、Perl ポリシー
があり、このポリシーに従っているパッケージの例が libdbd-pg-perl
(バイナリ perl モジュール) または libmldbm-perl
(アーキテクチャ非依存 perl モジュール) です。
Python 関連パッケージは、python ポリシーを持っています; python
パッケージ中の /usr/share/doc/python/python-policy.txt.gz
を参照してください。
Emacs 関連パッケージには、emacs ポリシーがあります。
Java 関連パッケージには、java ポリシーがあります。
Ocaml 関連パッケージは、固有のポリシーを持っており、ocaml
パッケージの /usr/share/doc/ocaml/ocaml_packaging_policy.gz
でみることができます。良い例は camlzip
ソースパッケージです。
XML や SGML DTD を提供しているパッケージは、sgml-base-doc
パッケージ中の推奨に従わねばなりません。
lisp パッケージは、パッケージ自身を common-lisp-controller
に登録する必要があります。これについては、/usr/share/doc/common-lisp-controller/README.packaging
を参照してください。
大量のアーキテクチャ非依存データがプログラムと共にパッケージ化されるのは、良くあることではありません。例えば、音声ファイル、アイコン集、様々な模様の壁紙、その他一般的な画像ファイルです。このデータのサイズがパッケージの残りのサイズと比較して取るに足らないのであれば、おそらくは単一パッケージでひとまとめにしておくのがベストでしょう。
しかし、データのサイズが考えた方が良い程であれば、分かれたアーキテクチャ非依存パッケージ (_all.deb
)
に分割するのを考えてください。これによって、11 あるいはそれ以上の .deb
ファイルについて、1アーキテクチャごとに同じデータの不必要な重複を避けられます。これは Packages
ファイルに更なるオーバーヘッドを追加しますが、Debian
ミラーサーバ上で多くのディスク容量を節約します。アーキテクチャ非依存のデータを分割することは、Debian アーカイブ全体に対して実行される
lintian の処理時間の削減にもつながります (「パッケージチェック (lint) 用ツール」
参照)。
ビルド中に特定のロケールを必要とする場合、こんな技を使えば一時ファイルを作成できます:
LOCPATH
を /usr/lib/locale
と同等のものに、そして LC_ALL
を生成したロケールの名前に設定すれば、root
にならなくても欲しいものが手に入ります。こんな感じです:
LOCALE_PATH=debian/tmpdir/usr/lib/locale LOCALE_NAME=en_IN LOCALE_CHARSET=UTF-8 mkdir -p $LOCALE_PATH localedef -i $LOCALE_NAME.$LOCALE_CHARSET -f $LOCALE_CHARSET $LOCALE_PATH/$LOCALE_NAME.$LOCALE_CHARSET # ロケールを使う LOCPATH=$LOCALE_PATH LC_ALL=$LOCALE_NAME.$LOCALE_CHARSET date
deborphan は、どのパッケージがシステムから安全に削除できるか、ユーザが検出するのを助けてくれるプログラムです; すなわち、どのパッケージも依存していないものです。デフォルトの動作は、使われていないライブラリを見つけ出すために libs と oldlibs セクションからのみ検索を行います。ですが、正しい引数を渡せば、他の使われていないパッケージを捕らえようとします。
例えば、--guess-dummy
つきだと、deborphan
はアップグレードに必要ではあったが、現在は問題なく削除できるすべての移行パッケージを探そうとします。これには、それぞれの短い説明文中に dummy
あるいは transitional の文字列を探します。
ですので、あなたがそのようなパッケージを作る際には、この文章を短い説明文に必ず追加してください。例を探す場合は、以下を実行してください: apt-cache search .|grep dummy または apt-cache search .|grep transitional
それから、deborphan の作業を楽にするため、section を
oldlibs
、priority を extra
にするのもお勧めです。
オリジナルのソース tarball には 2 種類あります: 手が入れられていない素のソース (Pristine source) と再パッケージした開発元のソース (repackaged upstream source) です。
素のソース tarball (pristine source tarball)
の特徴の定義は、.orig.tar.{gz,bz2,xz}
は、開発元の作者によって公式に配布された
tarball と 1 バイトたりとも違わない、というものです。[5]
これは、Debian diff 内に含まれているDebian
バージョンと開発元のバージョン間のすべての違いを簡単に比較するのにチェックサムを使えるようになります。また、オリジナルのソースが巨大な場合、既に
upstream の tarball を持っている upstream
の作者と他の者は、あなたのパッケージを詳細に調査したい場合、ダウンロード時間を節約できます。
tarball 中のディレクトリ構成に関して開発元の作者が従う、万人に受け入れられているガイドラインというものはありませんが、それにも関わらず dpkg-source は ほとんどの upstream の tarball を素のソース (pristine source) として対処できます。そのやり方は以下の通りです:
以下のようにして空の一時ディレクトリに tarball を展開します
zcat path/to/パッケージ名
_開発元のバージョン
.orig.tar.gz | tar xf -
もし、この後で、一時ディレクトリが 1
つのディレクトリ以外含まず他にどのファイルも無い場合、dpkg-source はそのディレクトリを
パッケージ名
-開発元のバージョン
(.orig)
にリネームします。tarball 中の最上位のディレクトリ名は問題にはされず、忘れられます。
それ以外の場合、upstream の tarball は共通の最上位ディレクトリ無しでパッケージされなくては いけません (upstream
の作者よ、恥を知りなさい!)。この場合、dpkg-source
は一時ディレクトリそのものを
パッケージ名
-開発元のバージョン
(.orig)
へリネームします。
パッケージは手が入っていない素のソース tarball と共にアップロードすべきですが、それが可能ではない場合が色々とあります。upstream がソースを gzip 圧縮した tarball を全く配布していない場合や、upstream の tarball が DFSG-free ではない、あなたがアップロード前に削除しなければならない素材を含んでいる場合がこれにあたります。
この様な場合、開発者は適切な .orig.tar.{gz,bz2,xz}
ファイルを自身で準備する必要があります。この様な tarball を、再パッケージした開発元のソース (repackaged upstream
source) と呼びます。再パッケージした開発元のソースでは Debian
ネイティブパッケージとは違うことに注意してください。再パッケージしたソースは、Debian 固有の変更点は分割された
.diff.gz
または
.debian.tar.{gz,bz2,xz}
のままであり、バージョン番号は
開発元のバージョン
と debian
リビジョン
から構成されたままです。
開発元が、原則的にはそのままの形で使える .tar.{gz,bz2,xz}
を配布していたとしても再パッケージをしたくなるという場合がありえます。最も明解なのは、tar アーカイブを再圧縮することや upstream
のアーカイブから純粋に使われていないゴミを削除することで、非常に容量を節約できる時です。ここで慎重になって頂きたいのですが、ソースを再パッケージする場合は、決定を貫く用意をしてください。
.orig.tar.{gz,bz2,xz}
についてのベストプラクティス
ソースパッケージの由来をドキュメントにすべきです。どうやってソースを得たのかという詳細情報が得たのか、どの様にすれば再生成できるのかを
debian/copyright
で提供しましょう。ポリシーマニュアルで、メイン構築スクリプト:
debian/rules
に記述しているように、debian/rules
に作業を繰り返してくれる
get-orig-source
ターゲットを追加するのも良い考えです。
開発元の作者由来ではないファイルや、あなたが内容を変更したファイルを含めるべきではありません。[6]
法的理由から不可能であるものを除いて、開発元の作者が提供しているビルドおよび移植作業環境を完全に保全すべきです。例えば、ファイルを省略する理由として MS-DOS
でのビルドにしか使われないから、というのは十分な理由にはなりません。同様に、開発元から提供されている
Makefile
を省略すべきではありません。たとえ
debian/rules
が最初にすることが configure
スクリプトを実行してそれを上書きすることであったとしても、です。
(理由: Debian 以外のプラットフォームのためにソフトウェアをビルドする必要がある Debian ユーザが、開発元の一次配布先を探そうとせずに Debian ミラーからソースを取得する、というのは普通です)。
tarball の最上位ディレクトリの名前として
パッケージ名
-開発元のバージョン
.orig
を使うべきです。これは、大元の使用されていない tarball
と再パッケージしたものを判別できるようにしてくれます。
gzip あるいは bzip で最大限圧縮されるべきです。
オリジナルの tarball
に含まれているバイナリファイルを変更する、あるいは存在していなかったバイナリファイルを追加する必要がある場合がしばしばあります。これは、ソースパッケージが“3.0
(quilt)”形式を使っている場合は完全にサポートされています。詳細は
dpkg-source(1)
マニュアルのページを参照してください。古い“1.0”形式を使っている場合、バイナリファイルを .diff.gz
中に保存できないので、uuencode (か類似のもの)
を使ったファイルを保存し、debian/rules
中でビルド時にデコードします
(そしてファイルを正しい位置へ移動する)。
デバッグパッケージは名前が -dbg で終わっているもので、gdb が利用可能な追加情報を含んでいます。Debian のバイナリはデフォルトで strip されているので、関数名や行番号を含むデバッグ情報は、Debian のバイナリに gdb を走らせたときに利用できません。デバッグパッケージは、この追加デバッグ情報を必要とするユーザが、通常のシステムを巨大化させること無く使えるようにしてくれます。
デバッグパッケージを作るか否かは、パッケージのメンテナ次第です。メンテナは、ライブラリパッケージについてデバッグパッケージを作成するのが推奨されています。これは、ライブラリにリンクしている沢山のプログラムをデバッグする助けになるからです。一般的に言って、デバッグパッケージはすべてのプログラムに追加する必要はありません; これを行うとアーカイブが巨大なものになるでしょう。しかし、メンテナは、ユーザがデバッグ版のプログラムを頻繁に必要とするのに気づいた場合、デバッグパッケージを作るのに値するでしょう。インフラストラクチャの核となっている、apache や X サーバのようプログラムも、デバッグパッケージの良い作成候補です。
デバッグパッケージのうちいくつかは、ライブラリあるいは他のバイナリの完全に特別なデバッグビルドを含むでしょうが、それらの大半は容量やビルドする時間を節約できます。/usr/lib/debug/
の場合、path
path
は実行ファイルかライブラリへのパスになります。例えば、/usr/bin/foo
のデバッグシンボルは
/usr/lib/debug/usr/bin/foo
に行き、/usr/lib/libfoo.so.1
のデバッグシンボルは
/usr/lib/debug/usr/lib/libfoo.so.1
になります。
デバッグシンボルは objcopy --only-keep-debug を使ってオブジェクトファイルから展開できます。そうすればオブジェクトファイルを strip することができ、objcopy --add-gnu-debuglink がデバッグシンボルファイルへのパスを指定するのに使われます。objcopy(1) で、これがどの様に動作するのかを詳細に説明しています。
debhelper
中の
dh_strip コマンドは、デバッグパッケージの作成をサポートし、デバッグシンボルを分離するのに
objcopy の利用の面倒を見てくれます。あなたのパッケージが debhelper
を使っている場合、あなたがする必要があるのは
dh_strip --dbg-package=libfoo-dbg
を呼び出し、debian/control
にデバッグパッケージのエントリを追加することだけです。
デバッグパッケージは、そのパッケージがデバッグシンボルを提供するパッケージに依存する必要があり、この依存関係はバージョン指定が必要であるということに注意してください。以下のような例になります:
Depends: libfoo (= ${binary:Version})
メタパッケージは、時間がかかる一貫したセットのパッケージをインストールするのを楽にしてくれる、ほぼ空のパッケージです。そのセットの全パッケージに依存することで、これを実現しています。APT
の力のおかげで、メタパッケージのメンテナは依存関係を調整すればユーザのシステムが自動的に追加パッケージを得ることができます。自動的にインストールされていてメタパッケージから落とされたパッケージは、削除候補としてマークされます
(そして aptitude によって自動的に削除もされます)。gnome
と linux-image-amd64
は、メタパッケージの 2 つの例です (ソースパッケージ
meta-gnome2
and linux-latest
から生成されています)。
メタパッケージの長い説明文は、目的を明確に記述している必要があります。これによって、ユーザはもしそのパッケージを削除した場合に何を失うことになるのかを知ることができます。のちの影響について明示的にするのもお勧めです。これは、初めのインストール時にインストールされており、ユーザが明示的にインストールしたわけではないメタパッケージにとって、特に重要です。システムのアップグレードをスムースに保証するのに重要になり、潜在的な破損をさけるためにユーザに対してアンインストールする気をなくさせることでしょう。
[5] 我々は、配布されている tarball
がバージョン番号をインクリメントすることなく、開発元の作者によって変更されるのを防ぐことはできません。ですので、手が入れられていない素の tarball
が、どの時点でも開発元が現在配布していると等しいものである保証はありません。期待できることは、一度は配布されたものと等しいものであるということだけです。後から違いが発生した場合
(そう、例えば upstream が元々の配布物が最大の圧縮率を使っていなかったことに気づいて、再度 gzip
しなおした場合など)、それはとても残念なことです。同じバージョンに対して新しい
.orig.tar.{gz,bz2,xz}
をアップロードするのには良い方法がないので、この状況をバグと考える意味はありません。
[6] 特別な例外として、non-free なファイルが Debian diff
からの助けが無いとソースからのビルド失敗を引き起こす場合、適切な処置はファイルを編集するのではなく、non-free
な部分を削除して、ソースツリーのルートに README.source
ファイルとして状況を説明することです。ですがその場合、開発元の作者に non-free
なコンポーネントを残りのソースから分離しやすくするように促してください。