[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[update] maint-guide.ja.sgml (3/5)
- From: Taketoshi Sano <kgh12351@xxxxxxxxxxx>
- Subject: [update] maint-guide.ja.sgml (3/5)
- Date: Sun, 28 Apr 2002 10:41:53 +0900
- X-dispatcher: imput version 991025(IM133)
- X-fingerprint: A1A0 F2D0 9C5D 7D61 DBA1 1507 D0B3 F3D0 AE31 C009
- X-ml-info: If you have a question, send e-mail with the body "help" (without quotes) to the address debian-doc-ctl@debian.or.jp; help=<mailto:debian-doc-ctl@debian.or.jp?body=help>
- X-ml-name: debian-doc
- X-mlserver: fml [fml 3.0pl#17]; post only (only members can post)
- Message-id: <20020428103111H.kgh12351@xxxxxxxxxxxxxxxxxxxx>
- X-mail-count: 02721
- X-mailer: Mew version 1.94.2 on Emacs 20.7 / Mule 4.0 (HANANOEN)
佐野＠浜松です。Debian New Maintainers' Guide 日本語訳更新の
第 3 弾です。よろしくお願いします。
====== Japanese translation ======
<chapt id="dother">debian/ の中にあるその他のファイル
<p>debian/ サブディレクトリには他にもいくつかのファイルが
あるはずです。それらのほとんどには「.ex」サフィックスが
付いており、そのファイルがただの例、サンプルであることを
示しています。
これらのファイルにはすべて目を通しておいてください。
もしこれらの機能のどれかを使いたいと思ったり、また使う必要が
生じたりした場合には、
<list>
<item>関連する文書 (ヒント: Debian ポリシーマニュアル) を調べ、
<item>必要に応じてそのファイルの内容を変更し、
<item>「.ex」というサフィックスが付いていたら、それを取り除く
ために名前を変更し、
<item>必要なら「rules」ファイルを編集してください。
</list>
<p>これらのファイルのうち、特によく利用されるものについては、
以下のセクションに説明があります。
<sect id="readme">README.Debian
<p>パッケージに関して何か特別にユーザに知らせる必要がある情報や、
オリジナルのソフトウェアとあなたが Debian パッケージにした
バージョンとの相違点は、ここに記述しておくべきです。
<p>以下はデフォルトとして dh_make が生成するものです。
<example>
gentoo for Debian
----------------------
<possible notes regarding this package - if none, delete this file>
Josip Rodin <jrodin@xxxxxxxxxxxxx>, Wed, 11 Nov 1998 21:02:14 +0100
</example>
<p>今回は特に何も書き込む必要はありませんから、あとでこのファイルを
削除しておきます。
<sect id="conffiles">conffiles.ex
<p>ソフトウェアに関して最もうんざりさせられることのひとつに、
大変な量の時間と労力を費してプログラムをカスタマイズした後で
そのための設定変更が一回のアップグレードによってすべて上書き
されてしまった場合が挙げられるでしょう。
Debian はこの問題を、設定ファイルを記録しておいて、パッケージを
アップグレードする際に古い設定をそのまま使いたいかどうか質問する
という方法で解決しました。
<p>この機能を使うには、パッケージのプログラムが使う各設定ファイル
(たいてい /etc にあります) のフルパス名を 1 行にひとつずつ、
<tt/conffiles/ という名前のファイルに記載します。
gentoo では /etc/gentoorc という名前の設定ファイルが
使われるので、これを <tt/conffiles/ ファイルに記載します。
<p>あなたのプログラムが設定ファイルを利用する場合であっても、
その設定ファイルがプログラム自身によって頻繁に上書きされる
ような場合には、パッケージをアップグレードするたびに dpkg に
よって設定ファイルの変更について確認を求められることになるので、
その設定ファイルを conffiles に登録しないほうが良いでしょう。
<p>あなたがパッケージにしたプログラムでは、設定ファイルを
変更しない限り、誰も利用できない、というような場合も、
その設定ファイルを conffile として登録しないほうが良いかも
しれません。
<p>設定ファイルのサンプルを「メンテナースクリプト」によって
用意することも可能です。詳細は <ref id="maintscripts"> を
参照してください。
<p>もしあなたのプログラムが設定ファイルを一切利用しないので
あれば、 debian/ ディレクトリから <tt/conffiles/ ファイルを
問題無く削除できます。
<sect id="crond">cron.d.ex
<p>もしあなたのパッケージがきちんと動作するために、
決められたスケジュールに従った定期的な作業の実行を
必要とする場合、このファイルを使ってその作業を
cron に登録します。
<p>ここではログのローテーションは扱いません。
ログローテーションについては
<manref name="dh_installlogrotate" section="1"> および
<manref name="logrotate" section="8">
を参照してください。
<p>もし必要無ければ、このファイルを削除してください。
<sect id="dirs">dirs
<p>このファイルには、我々のパッケージが必要としているが、
通常のインストール手順 (make install) では作成されない
ディレクトリを指定します。
デフォルトでは、こんな風になっています:
<p><example>
usr/bin
usr/sbin
</example>
<p>一番最初のスラッシュが含まれない事に注意してください。
たいていの場合、このファイルの内容は以下のように変更して
おけば問題無いでしょう。
<p><example>
usr/bin
usr/share/man/man1
</example>
ただ今回の場合、これらのディレクトリは Makefile 中の
処理によって既に作成されているので、このファイルは
不要であり、そのまま削除してしまうことにします。
<sect id="docs">docs
<p>このファイルには、dh_installdocs を使ってパッケージ
生成用の一時的なディレクトリにインストールするために、
パッケージに附属する資料のファイル名を指定します。
<p>ソースディレクトリのトップレベルに存在する「BUGS」、
「README*」、「TODO」などの名前を持つファイルはすべて
デフォルトとして含まれます。
<p>ここでは gentoo のために、附属文書をいくつか指定します。
<p><example>
BUGS
CONFIG-CHANGES
CREDITS
ONEWS
README
README.gtkrc
TODO
</example>
<p>別の方法として、このファイルを削除し、その代わり以下のように
<tt/rules/ ファイルにある <tt/dh_installdocs/ コマンド行の中で
これらの文書ファイル名を指定することも可能です。
<p><example>
dh_installdocs BUGS CONFIG-CHANGES CREDITS ONEWS README \
README.gtkrc TODO
</example>
<p>ありそうにないことですが、パッケージのソース中にここで
指定したくなるような附属文書がまったく存在しないという
場合もあるかもしれません。
そうした場合には、この docs ファイルを削除しても問題無い
でしょう。
ただし、その場合にも <tt/rules/ ファイルの中の
<tt/dh_installdocs/ コマンドを削除してはいけません。
このコマンドは <tt/copyright/ ファイルやその他のファイルを
インストールするために利用されます。
<sect id="emacsen">emacsen-*.ex
<p>パッケージをインストールする際にバイトコンパイル可能な
Emacs ファイルがあなたのパッケージに含まれている場合、
これらの emacsen-* ファイルを利用してそれを設定することが
できます。
<p>これらの emacsen-* ファイルは
<manref name="dh_installemacsen" section="1">
によってパッケージ作成用の一時的なディレクトリに
インストールされます。このため、もしこれらのファイルを
使用するのなら、<tt/rules/ ファイルの中にコメントとして
書かれている、この dh_installemacsen コマンドを起動して
いる行を、忘れずに有効にしておいてください。
<p>もしこれらの emacsen-* ファイルが必要なければ、
削除しておいてください。
<sect id="initd">init.d.ex
<p>もしあなたのパッケージがデーモンであり、システムの起動時に
自動的に動作させる必要があるとしたら、私が最初に勧めたことを
あなたはまるっきり無視してしまったわけですよね。そうでしょ ? :-)
<p>これは <file>/etc/init.d/</file> スクリプトの
非常に一般的なほんの骨組みのファイルにすぎません。
もしこれを使いたければ、内容を大幅に変更する必要が
あるでしょう。このファイルは
<manref name="dh_installinit" section="1">
によってパッケージ作成用の一時的なディレクトリに
インストールされます。
<p>もし不要なら、このファイルを削除してください。
<!-- updated for version 1.2, t-sano, 2002 Apr 27 -->
<sect id="manpage">manpage.1.ex, manpage.sgml.ex
<p>すべてのプログラムは man ページを持つべきです。
もし無かったら、これらのひな型のどちらかを利用して、
必要な情報を追加すれば作成できます。
<p>マニュアルページは通常
<manref name="nroff" section="1">
を利用して作成されます。
これにならって、<tt/manpage.1.ex/ も nroff で
作成されています。
<manref name="man" section="7"> のマニュアルページには、
このファイルの編集方法についての簡潔な説明があります。
<p>一方、もし nroff より SGML のほうが好みでしたら、
<tt/manpage.sgml.ex/ のほうをひな型として使うことも
できます。こちらの場合には、以下の手順が必要です。
<list>
<item>パッケージ <package/docbook-to-man/ のインストール
<item><tt/control/ ファイルの <tt/Build-Depends/ 行へ
<tt/docbook-to-man/ を追加
<item><tt/rules/ ファイルに記述された「build」ルールの
中で docbook-to-man を実行している行を有効にする
</list>
<p>それから、このファイルの名前を <tt/gentoo.sgml/ と
いった名前に変更することを忘れないように!
<p>最終的なマニュアルページファイルの名前には、そのマニュアル
ページで解説するプログラムの名前が含まれているべきです。
このため、ここではファイル名を「gentoo」から「manpage」に
変更します。ファイル名にはまた、デフォルトの拡張子として
「.1」が含まれていますが、これはこのファイルがユーザー
コマンドのマニュアルページであることを示しています。
この拡張子の示す分類が正しいものであることを確認して
おいてください。
マニュアルページの分類をまとめたリストを以下に示します。
<p><example>
セクション | 説明 | メモ
1 ユーザコマンド 実行可能なコマンドやスクリプト
2 システムコール カーネルの提供する機能
3 ライブラリコール システムライブラリに含まれる機能
4 特別ファイル たいていは /dev 内にあるもの
5 ファイルの書式 例えば /etc/passwd の書式
6 ゲーム またはその他のおもしろいプログラム
7 マクロパッケージ man マクロのようなもの
8 システム管理 実行するのに root 権限が必要なものなど
9 カーネルルーチン 標準的でないシステムコールや内部仕様
</example>
<p>そんなわけで gentoo のman ページは gentoo.1 と呼ばれることに
なります。X 用のプログラムの場合、例えば <tt/gentoo.1x/ のように
分類番号に「x」を追加することもできます。
元のソースには gentoo.1 という man ページが含まれていなかったので、
上に説明したサンプルと、上流開発者が提供している文書からの情報を
もとに筆者が作成しました。
<sect id="menu">menu.ex
<p>X Window System のユーザはたいていウィンドウマネージャを
使っており、そのメニュー機能を設定することで好きなプログラムを
ウィンドウマネージャから起動できます。
もしユーザが Debian の <package/menu/ パッケージをインストール
していれば、システムにあるすべてのプログラム用のメニューが作成され、
menu に対応したウィンドウマネージャから利用できます。
<p>以下が dh_make によって生成されたデフォルトの <tt/menu.ex/
ファイルです。
<p><example>
?package(gentoo):needs=X11|text|vc|wm section=Apps/see-menu-manual\
title="gentoo" command="/usr/bin/gentoo"
</example>
<p>コロン (:) の後の最初の「needs」フィールドには、
プログラムがどういう種類のインターフェースを必要とするかを
指定します。このフィールドはデフォルトとして列挙された
選択肢のどれか (例えばテキスト、X11 など) に変更してください。
<p>次は「section」、プログラムのエントリーが表示される
メニューやサブメニューの指定です。現在のセクション一覧は
<file>/usr/share/doc/debian-policy/menu-policy.html/ch2.html#s2.1</file> に
記載されています。
<p>「title」フィールドはプログラムの名称です。
好みによって、大文字から始めることもできます。
ただし、なるべく短くしておきましょう。
<p>最後の「command」フィールドは、実際にプログラムを
実行するコマンドです。
<p>さて、今回はこんな風に menu エントリを変えましょう。
<p><example>
?package(gentoo): needs=X11 section=Apps/Tools title="Gentoo" command="gentoo"
</example>
<p>他にも「longtitle」、「icon」、「hints」などの
フィールドを追加することができます。
より詳細な説明は
<manref name="menufile" section="5">、
<manref name="update-menus" section="1">、
および <file>/usr/share/doc/debian-policy/menu-policy.html/</file> を
参照してください。
<sect id="watch">watch.ex
<p>このファイルを
<manref name="uscan" section="1"> および
<manref name="uupdate" section="1"> プログラム
(これらは <package/devscripts/ パッケージにあります) と
合わせて使うことによって、オリジナルソースを入手したサイトの
更新をチェックすることができます。
<p>今回は以下のようにしました。
<p><example>
# watch control file for uscan
# Site Directory Pattern Version Script
ftp.obsession.se /gentoo gentoo-(.*)\.tar\.gz debian uupdate
</example>
<p>ヒント:このファイルを作成したら、インターネットに接続し、ソースを
展開したディレクトリの中から「uscan」を試しに実行してみるとよいでしょう。
それから、マニュアルページも読んでみてください。:)
<sect id="doc-base">ex.package.doc-base
<p>もしあなたのパッケージがマニュアルページや info 形式の
文書以外に附属文書を含んでいるのなら、
「<package/doc-base/」ファイルを使ってそれを登録し、
ユーザがそれらの附属文書を、例えば
<manref name="dhelp" section="1"> や
<manref name="dwww" section="1"> あるいは
<manref name="doccentral" section="1"> などの
コマンドで参照できるようにするべきです。
<p>これには通常 <file>/usr/share/doc/packagename/</file>
の中に収められるような HTML、PS および PDF などの形式の
附属文書が含まれます。
<p>以下に gentoo の doc-base ファイルの例を示します。
<p><example>
Document: gentoo
Title: Gentoo Manual
Author: Emil Brink
Abstract: This manual describes what Gentoo is, and how it can be used.
Section: Apps/Tools
Format: HTML
Index: /usr/share/doc/gentoo/html/index.html
Files: /usr/share/doc/gentoo/html/*.html
</example>
<p>このファイルの書式については
<manref name="install-docs" section="8"> および
<file>/usr/share/doc/doc-base/doc-base.html/</file> にある
<package/doc-base/ のマニュアルを参照してください。
<sect id="maintscripts">postinst.ex、preinst.ex、postrm.ex、prerm.ex
<p>これらのファイルはメンテナスクリプトと呼ばれるもので、
パッケージの制御パートに収録され、
あなたのパッケージがインストール、アップグレード、あるいは
削除されるときに dpkg によって実行されます。
<p>今のところは、メンテナスクリプトを手でいじるのは、
できるだけ避けるようにするべきでしょう。
というのも、これらはどんどん複雑になっていってしまう傾向が
あるからです。
詳しくはポリシーマニュアルの第 6 節と
dh_make によって用意されたこれらのサンプルファイルを
注意して読んでください。
<chapt id="build">パッケージの構築
<p>これでパッケージを構築する準備が整いました。
<sect id="completebuild">完全な再構築
<p>プログラムのメインディレクトリに移動して
以下のコマンドを実行してください:
<p><example>
dpkg-buildpackage -rfakeroot
</example>
<p>このコマンドは、あなたのためにパッケージ構築の
作業をすべて行なってくれます。これには以下の作業が
含まれます。
<list>
<item><prgn/fakeroot/ を使ったソースツリーの初期化 (debian/rules clean)
<item>ソースパッケージの構築 (dpkg-source -b)
<item>プログラムの構築 (debian/rules build)
<item><prgn/fakeroot/ を使ったバイナリパッケージの構築 (debian/rules binary)
<item><prgn/gnupg/ を使ったソース <tt/.dsc/ ファイルへの署名
<item><prgn/dpkg-genchanges/ および <prgn/gnupg/ を使った
アップロード用 <tt/.changes/ ファイルの作成および署名
</list>
<p>途中で GPG の秘密鍵を 2 回入力する必要がありますが、
それを除けばこのプログラムにすべてお任せで大丈夫です。
<p>一連の作業が終わった後、上記のディレクトリ (<tt>~/debian/</tt>) には
以下のファイルが作成されているはずです。
<p><list>
<item><em>gentoo_0.9.12.orig.tar.gz</em>
<p>これは単に Debian 標準に合わせるために名前を変更しただけで、
中身はオリジナルなソースコードの tar アーカイブです。
これは <prgn/dh_make/ を最初に実行した際、「-f」オプションを
指定して作成されたということを覚えておいてください。
<item><em>gentoo_0.9.12-1.dsc</em>
<p>これはソースコードの内容の概要です。このファイルは
あなたの「control」ファイルから生成され、
<manref name="dpkg-source" section="1"> によって
ソースを展開する時に使われます。
このファイルは GPG で署名されているので、本当にあなた自身が
作成したものかどうかを利用者が検証できます。
<item><em>gentoo_0.9.12-1.diff.gz</em>
<p>この圧縮されたファイルにはあなたがオリジナルのソースコードに
行なったすべての変更や追加などの情報が「unified diff」の形式で
含まれています。これは <manref name="dpkg-source" section="1">
によって生成され、また利用されます。警告: もしオリジナルの
tar アーカイブの名前を packagename_version.orig.tar.gz の形式に
変更していなかった場合、<prgn/dpkg-source/ を使って
適切な .diff.gz ファイルを作成できなくなります!
<p>上記の 3 つのファイルを使えば、誰でも簡単にあなたのパッケージを
最初から再構築できます。ソースツリーを取り出す手順は簡単です。
単にこれらの 3 つのファイルをどこか別の場所にコピーして、
<tt>dpkg-source -x gentoo_0.9.12-1.dsc</tt>.
を実行するだけです。
<item><em>gentoo_0.9.12-1_i386.deb</em>
<p>これは作成されたバイナリパッケージです。他のすべてのパッケージと
同じく、<prgn/dpkg/ を使ってインストールしたり削除したりできます。
<item><em>gentoo_0.9.12-1_i386.changes</em>
<p>このファイルは現在のレビジョンのパッケージにおける変更点を
すべて記載したもので、Debian FTP アーカイブ管理プログラムに
よってバイナリおよびソースパッケージを FTP アーカイブに
インストールするために利用されます。
これは「changelog」ファイルと .dsc ファイルとを元にして
生成されます。このファイルは GPG で署名されているので、
パッケージの利用者はこのファイルが本当にあなた自身が作成した
ものかどうかをちゃんと判断できます。
<p>パッケージの保守管理を続けていくと、プログラムの動作が
変更されたり新機能が追加されたりすることがあります。
あなたのパッケージをダウンロードする人は、このファイルを見れば
何が変わったのか一目で分かります。
またこのファイルの中身は Debian アーカイブ管理プログラムによって
debian-devel-changes メーリングリストへ流されます。
<p>.dsc ファイルと .changes ファイルに記載されている長い数字の
羅列は各ファイルの MD5 チェックサムで、パッケージをダウンロード
した人は <manref name="md5sum" section="1"> を使って整合性を
テストすることができます。もし数字が一致しない場合には、
ファイルが壊れているか、あるいは何者かによって改ざんされている
と分かるわけです。
</list>
<sect id="quickrebuild">部分的な再構築
<p>大規模なパッケージの場合には、<file>debian/rules</file> を
ちょっといじるたびに、毎回最初からパッケージの再構築を
やりなおしたくはないでしょう。
テスト目的の場合、以下のようにすれば上流 (upstream) ソースの
再構築をしないで .deb ファイルを生成できます。
<p><example>
fakeroot debian/rules binary
</example>
<p>最終的にきちんとテストが完了したら、正しい手順に従って
パッケージを最初から再構築することを忘れないでください。
このやり方で生成した .deb ファイルをアップロードしようと
しても、おそらくきちんとアップロードできないでしょう。
====== Original version ======
<chapt id="dother">Other files under debian/
<p>You will see that there exist several other files in the debian/
subdirectory, most of them with the `.ex' suffix, meaning that they are
examples. Take a look at all of them. If you wish or need to use any of
those features:
<list>
<item>take a look at the related documentation (hint: the Policy Manual),
<item>if necessary modify the files to suit your needs,
<item>rename them to remove the `.ex' suffix if they have one,
<item>modify the `rules' file if necessary.
</list>
<p>Some of those files, those commonly used ones, are explained in the
following sections.
<sect id="readme">README.Debian
<p>Any extra details or discrepancies between the original package and
your debianized version should be documented here.
<p>dh_make created a default one, this is what it looks like:
<p><example>
gentoo for Debian
-----------------
<possible notes regarding this package - if none, delete this file>
-- Josip Rodin <jrodin@xxxxxxxxxxxxx>, Wed, 11 Nov 1998 21:02:14 +0100
</example>
<p>Since we don't have anything to put there, we'll delete the file.
<sect id="conffiles">conffiles.ex
<p>One of the most annoying things about software is when you spend a
great deal of time and effort customizing a program, only to have an
upgrade stomp all over your changes. Debian solves this problem by
marking configuration files so that when you upgrade a package, you'll
be prompted whether you want to keep your old configuration or not.
<p>The way to do this in a package is to enter the full path to each
configuration file (usually in /etc), one per line, in a file called
<tt/conffiles/. Gentoo has one conffile, /etc/gentoorc, and we'll enter
that in the <tt/conffiles/ file.
<p>If your program uses configuration files but also rewrites them on its
own, it's best not to mark them as conffiles because dpkg will then prompt
users to verify the changes all the time.
<p>If the program you're packaging requires every user to modify the
configuration file in order to work at all, also consider not marking the
file as a conffile.
<p>You can handle example configuration files from the `maintainer
scripts', for more information see <ref id="maintscripts">.
<p>If your program has no conffiles, you can safely delete the
<tt/conffiles/ file from the debian/ directory.
<sect id="crond">cron.d.ex
<p>If your package requires regularly scheduled tasks to operate properly,
you an use this file to set it up.
<p>Note that this doesn't include log rotation; for that, see
<manref name="dh_installlogrotate" section="1"> and
<manref name="logrotate" section="8">.
<p>If not, remove it.
<sect id="dirs">dirs
<p>This file specifies the directories which we need but the normal
installation procedure (make install) somehow doesn't create.
<p>By default, it looks like this:
<p><example>
usr/bin
usr/sbin
</example>
<p>Note that the preceding slash is not included. We would have normally
changed it to look like this:
<p><example>
usr/bin
usr/man/man1
</example>
<p>but those directories are already created in the Makefile, so we won't
need this file, and we will instead delete it.
<sect id="docs">docs
<p>This file specifies the file names of documentation files we can have
dh_installdocs install into the temporary directory for us.
<p>By default, it will include all existing files in the top-level source
directory that are called "BUGS", "README*", "TODO" etc.
<p>For gentoo, I also included some other stuff:
<p><example>
BUGS
CONFIG-CHANGES
CREDITS
ONEWS
README
README.gtkrc
TODO
</example>
<p>We can also remove this file and instead list these files on the
<tt/dh_installdocs/ command line in the <tt/rules/ file, like this:
<p><example>
dh_installdocs BUGS CONFIG-CHANGES CREDITS ONEWS README \
README.gtkrc TODO
</example>
<p>How ever unlikely it may seem, you may not have any such files in your
package's sources. In that case you can safely remove this file. But don't
remove the <tt/dh_installdocs/ invocation from the <tt/rules/ file because
that's used to install the <tt/copyright/ file and other things.
<sect id="emacsen">emacsen-*.ex
<p>If your package supplies Emacs files that can be bytecompiled at
package installation time, you can use these files to set it up.
<p>They are installed into the temporary directory by
<manref name="dh_installemacsen" section="1">, so don't forget to
uncomment that line in the <tt/rules/ file if you use this.
<p>If you don't need these, remove them.
<sect id="initd">init.d.ex
<p>If your package is a daemon that needs to be run at system startup,
you've obviously disregarded my initial recommendation, haven't you? :-)
<p>This is a fairly generic skeleton file for an <file>/etc/init.d/</file>
script, so you'll likely have to edit it, a lot. It gets installed into
the temporary directory by <manref name="dh_installinit" section="1">.
<p>If you don't need this, remove the file.
<sect id="manpage">manpage.1.ex, manpage.sgml.ex
<p>Your program(s) should have a manual page. If they don't, each of these
files are a template that you can fill out.
<p>Manual pages are normally written in <manref name="nroff" section="1">.
The <tt/manpage.1.ex/ example is written in nroff, too.
See the <manref name="man" section="7"> manual page
for a brief description of how to edit such a file.
<p>If on the other hand you prefer writing SGML instead of nroff, you can
use the <tt/manpage.sgml.ex/ template. If you do this, you have to:
<list>
<item>install the <package/docbook-to-man/ package
<item>add <tt/docbook-to-man/ to the <tt/Build-Depends/ line in the
<tt/control/ file
<item>remove the comment from the docbook-to-man invocation in the
`build' rule of your <tt/rules/ file
</list>
<p>And remember to rename the file to something like <tt/gentoo.sgml/!
<p>The final manual page file name should include the name of the program
it is documenting, so we will rename it from "manpage" to "gentoo".
The file name also includes ".1" as the first suffix, which means it's a
manual page for a user command. Be sure to verify that this section is
indeed the correct one. Here's a short list of manual page sections:
<p><example>
Section | Description | Notes
1 User commands Executable commands or scripts.
2 System calls Functions provided by the kernel.
3 Library calls Functions within system libraries.
4 Special files Usually found in /dev
5 File formats E.g. /etc/passwd's format
6 Games Or other frivolous programs
7 Macro packages Such as man macros.
8 System administration Programs typically only run by root.
9 Kernel routines Non-standard calls and internals.
</example>
<p>So gentoo's man page should be called <tt/gentoo.1/. For X programs you
can tack on another "x" to the section, i.e. <tt/gentoo.1x/.
There was no gentoo.1 man page in the original source so I wrote
it using information from the example and from upstream docs.
<sect id="menu">menu.ex
<p>X Window System users usually have a window manager with a menu that
can be customized to launch programs. If they have installed the Debian
<package/menu/ package, a set of menus for every program on the system will be
created for them.
<p>Here's the default <tt/menu.ex/ file that dh_make creates:
<p><example>
?package(gentoo):needs=X11|text|vc|wm section=Apps/see-menu-manual\
title="gentoo" command="/usr/bin/gentoo"
</example>
<p>The first field after the colon character is "needs", and it specifies
what kind of interface the program needs. Change this to one of the listed
alternatives, e.g. "text" or "X11".
<p>The next is "section", where the menu and submenu the entry should
appear in. The current list of sections is at:
<file>/usr/share/doc/debian-policy/menu-policy.html/ch2.html#s2.1</file>
<p>The "title" field is the name of the program. You can start this one
in uppercase if you like. Just keep it short.
<p>Finally, the "command" field is the command that runs the program.
<p>Now we'll change the menu entry to this:
<p><example>
?package(gentoo): needs=X11 section=Apps/Tools title="Gentoo" command="gentoo"
</example>
<p>You can also add other fields like "longtitle", "icon", "hints" etc.
See <manref name="menufile" section="5">,
<manref name="update-menus" section="1">
and <file>/usr/share/doc/debian-policy/menu-policy.html/</file> for more
information.
<sect id="watch">watch.ex
<p>This file is used to configure the <manref name="uscan" section="1">
and <manref name="uupdate" section="1"> programs (in the
<package/devscripts/ package). These are used to watch the site you got
the original source from.
<p>Here's what I put in it:
<p><example>
# watch control file for uscan
# Site Directory Pattern Version Script
ftp.obsession.se /gentoo gentoo-(.*)\.tar\.gz debian uupdate
</example>
<p>Hint: connect to the Internet, and try running "uscan" in the program
directory once you create the file. And read the manuals! :)
<sect id="doc-base">ex.package.doc-base
<p>If your package has documentation other than manual pages and info
docs, you should use the `<package/doc-base/' file to register it,
so the user can find it with e.g. <manref name="dhelp" section="1">,
<manref name="dwww" section="1"> or <manref name="doccentral" section="1">.
<p>This usually includes HTML, PS and PDF files, shipped in
<file>/usr/share/doc/packagename/</file>.
<p>This is how gentoo's doc-base file looks like:
<p><example>
Document: gentoo
Title: Gentoo Manual
Author: Emil Brink
Abstract: This manual describes what Gentoo is, and how it can be used.
Section: Apps/Tools
Format: HTML
Index: /usr/share/doc/gentoo/html/index.html
Files: /usr/share/doc/gentoo/html/*.html
</example>
<p>For information on the file format, see
<manref name="install-docs" section="8"> and the <package/doc-base/ manual,
in <file>/usr/share/doc/doc-base/doc-base.html/</file>.
<sect id="maintscripts">postinst.ex, preinst.ex, postrm.ex, prerm.ex
<p>These files are called maintainer scripts. They are scripts which are
put in the control area of the package and run by <prgn/dpkg/ when your
package is installed, upgraded or removed.
<p>For now, you should try to avoid any manual editing of maintainer
scripts if you possibly can because they tend to get complex. For more
information look in the Policy Manual, section 6, and take a look at
these example files provided by dh_make.
<chapt id="build">Building the package
<p>We should now be ready to build the package.
<sect id="completebuild">Complete rebuild
<p>Enter the program's main directory and then issue this command:
<p><example>
dpkg-buildpackage -rfakeroot
</example>
<p>This will do everything for you. It will:
<list>
<item>clean the source tree (debian/rules clean), using <prgn/fakeroot/
<item>build the source package (dpkg-source -b)
<item>build the program (debian/rules build)
<item>build the binary package (debian/rules binary), using <prgn/fakeroot/
<item>sign the source <tt/.dsc/ file, using <prgn/gnupg/
<item>create and sign the upload <tt/.changes/ file, using
<prgn/dpkg-genchanges/ and <prgn/gnupg/
</list>
<p>The only input that will be required of you is your GPG key secret pass
phrase, twice.
<p>After all this is done, you will see the following files in the
directory above (<tt>~/debian/</tt>):
<p><list>
<item><em>gentoo_0.9.12.orig.tar.gz</em>
<p>This is the original source code tarball, merely renamed to the above
so that it adheres to the Debian standard. Note that this was created
using the `-f' option to <prgn/dh_make/ when we initially ran it.
<item><em>gentoo_0.9.12-1.dsc</em>
<p>This is a summary of the contents of the source code. The file is
generated from your `control' file, and is used when
unpacking the source with <manref name="dpkg-source" section="1">. This
file is GPG signed, so that people can be sure that it's really yours.
<item><em>gentoo_0.9.12-1.diff.gz</em>
<p>This compressed file contains each and every addition you made to the
original source code, in the form known as "unified diff". It is made
and used by <manref name="dpkg-source" section="1">. Warning: if you don't name
the original tarball packagename_version.orig.tar.gz, <prgn/dpkg-source/
will fail to generate the .diff.gz file properly!
<p>If someone else wants to re-create your package from scratch, they can
easily do so using the above three files. The extraction procedure is
trivial: just copy the three files somewhere else and run
<tt>dpkg-source -x gentoo_0.9.12-1.dsc</tt>.
<item><em>gentoo_0.9.12-1_i386.deb</em>
<p>This is your completed binary package. You can use <prgn/dpkg/ to
install and remove this just like any other package.
<item><em>gentoo_0.9.12-1_i386.changes</em>
<p>This file describes all the changes made in the current package
revision, and it is used by the Debian FTP archive maintenance programs
to install the binary and source packages in it. It is partly generated
from the `changelog' file and the .dsc file. This file is GPG signed, so
that people can be sure that it's really yours.
<p>As you keep working on the package, behavior will change and new
features will be added. People downloading your package can look at this
file and quickly see what has changed. Debian archive maintenance programs
will also post the contents of this file to the debian-devel-changes
mailing list.
</list>
<p>The long strings of numbers in the .dsc and .changes files are MD5
checksums for the files mentioned.
A person downloading your files can test them with <manref name="md5sum"
section="1"> and if the numbers don't match, they'll know the file is
corrupt or has been tampered with.
<sect id="quickrebuild">Quick rebuild
<p>With a large package, you may not want to rebuild from scratch every
time while you tune a detail in <file>debian/rules</file>. For testing
purposes, you
can make a .deb file without rebuilding the upstream sources like this:
<p><example>
fakeroot debian/rules binary
</example>
<p>Once you are finished with your tuning, remember to rebuild following
the above, proper procedure. You may not be able to upload correctly if
you try to upload .deb files built this way.
====== End ======
--
＃ わたしのおうちは浜松市、アカウミガメもやってくる
<kgh12351@xxxxxxxxxxx> : Taketoshi Sano (佐野 武俊)