[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Documentation/pkgsrc/components.xml: 1.1 -> 1.3
以下のページの更新をしました。ツッコミをお願いします。
Documentation/pkgsrc/components.xml: 1.1 -> 1.3
火曜日までに異議がなければ、 commit します。
以下、訳と原文の差分です。
--- Documentation/pkgsrc/components.xml.orig 2006-05-29 22:54:17.000000000 +0900
+++ Documentation/pkgsrc/components.xml 2006-05-29 22:54:17.000000000 +0900
@@ -1,12 +1,12 @@
-<!-- $NetBSD: components.xml,v 1.1 2004/06/06 13:31:53 grant Exp $ -->
+<!-- $NetBSD: components.xml,v 1.3 2004/09/29 13:08:36 hubertf Exp $ -->
<!-- Based on english version: -->
-<!-- NetBSD: components.xml,v 1.1 2004/06/06 13:31:53 grant Exp -->
+<!-- NetBSD: components.xml,v 1.3 2004/09/29 13:08:36 hubertf Exp -->
-<chapter id="components">
+<chapter id="components"> <?dbhtml filename="components.html"?>
<title>パッケージコンポーネント - ファイル、ディレクトリー、およびコンテンツ</title>
-
- <para>パッケージを用意する際にはいつも、以下のセクションで述べられている多くのファ
- イルが存在します。</para>
+
+ <para> パッケージを用意する際にはいつも、以下のセクションで述べられている多くのファ
+ イルが存在します。 </para>
<sect1 id="components.Makefile">
<title><filename>Makefile</filename></title>
@@ -25,30 +25,41 @@
<varname>PKGNAME</varname>と、メンテナー名である<varname>MAINTAINER</varname>と、パッケージの一行説明(パッケージ
名は自動的に追加されるので、含めないでください) からなる<varname>COMMENT</varname>変数です。
maintainer変数は、そのパッケージを維持する人による(いつも完全に正しい)決定
- にへりくつを言う誰かが、活発に苦情を言うことができるようにするためです。</para>
+ にへりくつを言う誰かが、活発に苦情を言ったり、
+ 感謝のしるしにチョコレートを送ったりできるようにするためです。</para>
<para><varname>MASTER_SITES</varname>は、定義済みのサイトの一つをセットすることもできます。</para>
- <programlisting>${MASTER_SITE_XCONTRIB}
-${MASTER_SITE_GNU}
-${MASTER_SITE_PERL_CPAN}
-${MASTER_SITE_TEX_CTAN}
-${MASTER_SITE_SUNSITE}
-${MASTER_SITE_GNOME}
-${MASTER_SITE_SOURCEFORGE}</programlisting>
+ <programlisting>
+ ${MASTER_SITE_APACHE}
+ ${MASTER_SITE_DEBIAN}
+ ${MASTER_SITE_GNOME}
+ ${MASTER_SITE_GNU}
+ ${MASTER_SITE_GNUSTEP}
+ ${MASTER_SITE_MOZILLA}
+ ${MASTER_SITE_PERL_CPAN}
+ ${MASTER_SITE_SOURCEFORGE}
+ ${MASTER_SITE_SUNSITE}
+ ${MASTER_SITE_R_CRAN}
+ ${MASTER_SITE_SUSE}
+ ${MASTER_SITE_TEX_CTAN}
+ ${MASTER_SITE_XCONTRIB}
+ ${MASTER_SITE_XEMACS} </programlisting>
<para>もしこれらの予め定義されたサイトの1つを選んだ場合、そのサイトのサブディレク
トリーを指定する方法が必要となるかもしれません。これらのマクロは複数の実際
のサイトに展開されるかもしれませんので、サブディレクトリーを指定する場合は、
以下の表記を<emphasis>使わなければなりません</emphasis>:</para>
- <programlisting>${MASTER_SITE_GNU:=subdirectory/name/}</programlisting>
+ <programlisting>
+ ${MASTER_SITE_GNU:=subdirectory/name/}
+ ${MASTER_SITE_SOURCEFORGE:=project_name/} </programlisting>
<para>サブディレクトリー名の後のスラッシュ/に注意してください。</para>
<note>
<para><varname>MASTER_SITE_SUBDIR</varname> は廃止されましたので、
- <emphasis>もう使わないでください</emphasis>。</para>
+ <emphasis>もう使わないでください</emphasis>。</para>
</note>
<para>パッケージに複数の<varname>DISTFILES</varname>または複数の
@@ -57,10 +68,10 @@
<quote>foo</quote>があるURIを列挙したものに設定
します。<quote>foo</quote>にはサフィックスを含めます。たとえば以下のようにします。</para>
- <programlisting>DISTFILES= ${DISTNAME}${EXTRACT_SUFX}
-DISTFILES+= foo-file.tar.gz
+<programlisting>DISTFILES= ${DISTNAME}${EXTRACT_SUFX}
+DISTFILES+= foo-file.tar.gz
SITES_foo-file.tar.gz=http://www.somewhere.com/somehow/ \
- http://www.somewhereelse.com/mirror/somehow/</programlisting>
+ http://www.somewhereelse.com/mirror/somehow/</programlisting>
<para>なお、通常おこなうような、<varname>DISTFILES</varname>へのファイルの(置換ではなく)追加をする場
合は、標準的な<varname>DISTFILES</varname>のデフォルト設定を明示的におこなわなければなりません。</para>
@@ -68,50 +79,51 @@
<para>現在<varname>CATEGORIES</varname>の値として以下が使用できます。もし複数にまたがる場合、それら
の値はスペースで分けられる必要があります:</para>
- <programlisting>archivers audio benchmarks biology cad
-chat comms converters cross databases
-devel editors emulators finance fonts
-games graphics ham japanese lang
-mail math mbone misc net
-news parallel print security shells
-sysutils textproc time wm www
-x11</programlisting>
+ <programlisting>
+archivers cross geography meta-pkgs security
+audio databases graphics misc shells
+benchmarks devel ham multimedia sysutils
+biology editors inputmethod net textproc
+cad emulators lang news time
+chat finance mail parallel wm
+comms fonts math pkgtools www
+converters games mbone print x11</programlisting>
- <para>以下の事柄に気を配ってください。:</para>
+ <para> 以下の事柄に気を配ってください。: </para>
<itemizedlist>
<listitem>
- <para>もしパッケージによりマニュアルページが圧縮され
- た形式でインストールされる場合、<varname>MANCOMPRESSED</varname>を追加してください。
- <filename>bsd.pkg.mk</filename>のコメントを参照。</para>
+ <para>もしパッケージによりマニュアルページが圧縮され
+ た形式でインストールされる場合、<varname>MANCOMPRESSED</varname>を追加してください。
+ <filename>bsd.pkg.mk</filename>のコメントを参照。</para>
</listitem>
<listitem>
- <para>すべてのファイルの<filename>/usr/local</filename>を<quote>${PREFIX}</quote>に変更してください。(後述のパッチ
- を参照)</para>
+ <para>すべてのファイルの<filename>/usr/local</filename>を<quote>${PREFIX}</quote>に変更してください。(後述のパッチ
+ を参照)</para>
</listitem>
<listitem>
- <para>もし、パッケージがinfoファイルをインストールするのであれば、
- <xref linkend="features.info-files"/>を参照してください。</para>
+ <para>もし、パッケージがinfoファイルをインストールするのであれば、
+ <xref linkend="faq.info-files"/>を参照してください。</para>
</listitem>
<listitem>
- <para>もしあなたが将来の更新のために、そのパッケージをメンテナンスするつもりで
- あれば、
- <varname>MAINTAINER</varname>にあなたのメールアドレスをセットしてください。標準では
- MAINTAINERは<email>tech-pkg@NetBSD.org</email>にセットします。</para>
+ <para><varname>MAINTAINER</varname> をあなた自身に設定してください。
+ そのパッケージを将来の更新に応じて保守することがどうしてもできない場合は、
+ <email>tech-pkg@NetBSD.org</email> に設定します。</para>
</listitem>
<listitem>
- <para>もし問題のソフトウェアにホームページが存在するのであれば、
- <varname>MAINTAINER</varname>の後ろに
- <varname>HOMEPAGE</varname>を追加してください。
- <varname>HOMEPAGE</varname>の値はホームページのURLにしてください。</para>
+ <para>もし問題のソフトウェアにホームページが存在するのであれば、
+ <varname>MAINTAINER</varname>の後ろに
+ <varname>HOMEPAGE</varname>を追加してください。
+ <varname>HOMEPAGE</varname>の値はホームページのURLにしてください。</para>
</listitem>
<listitem>
- <para>パッケージの短い説明を<varname>COMMENT</varname>変数に設定してください。</para>
+ <para>パッケージの短い説明を、 (パッケージ名は含めずに)
+ <varname>COMMENT</varname>変数に設定してください。</para>
</listitem>
</itemizedlist>
</sect1>
@@ -124,7 +136,7 @@
このメッセージダイジェストが一致することを確認しています。これをもとに、イ
ンターネットから取得したdistfileが転送中にファイルが壊れたり、悪意によりセ
キュリティーホールを入れられたファイルに変更されていたりしていないことを確
- 認します。これは<command>make makesum</command>により生成するのが最善です。ダイジェストアル
+ 認します。これは<command>make makesum</command>により生成します。ダイジェストアル
ゴリズムには md5 が使われていましたが、これはsha1に比べて弱いため、現在は
sha1がデフォルトのアルゴリズムになっています。また、distfileの容量も生成さ
れ、新しいdistinfoファイルに格納されます。<pkg>pkgtools/digest</pkg>ユーティリ
@@ -136,7 +148,7 @@
<emphasis>sha384</emphasis>, <emphasis>sha512</emphasis></para>
<para>パッケージによっては、アーキテクチャー毎にdistfileの組が異なるものがありま
- す(<pkg>www/navigator</pkg>がよい例です)。この情報は単一のdistinfoファイルに
+ す(たとえば <pkg>www/navigator</pkg>)。この情報は単一のdistinfoファイルに
書かれるので、このようなパッケージの更新時には、distfileの情報が失われない
ように注意を払ってください。</para>
@@ -144,7 +156,8 @@
(<xref linkend="components.patches"/>参照)に入っている、公式なすべてのパッチ
のメッセージダイジェスト/チェックサムも、この<filename>distinfo</filename>ファイルに格納されます。
これは、パッチ中の&os; RCS Idを除いたすべての行のメッセージダイジェスト/
- チェックサムです。このファイルは<command>make makepatchsum</command>コマンドにより生成するこ
+ チェックサムです。このファイルは<command>make makepatchsum</command> (急を要する場合は
+ <command>make mps</command> でも可) コマンドにより生成するこ
とができます。</para>
</sect1>
@@ -160,7 +173,46 @@
展開順)で適用されます。つまり<filename>patch-aa</filename>は
<filename>patch-ab</filename>より前に適用されます。</para>
- <para>問題を避けるため、<filename>patch-??</filename>ファイルは
+ <para> オプションのパッチファイルであってローカルサイトの構成に依存するものは、
+ <filename>patches/patch-optional-*</filename> の形式の名前にして、
+ パッケージに含めることができます。オプションのパッチファイルは、
+ 適用するもののファイル名を <varname>OPTIONAL_PATCHFILES</varname>
+ 変数に割り当てます。オプションのパッチファイルは、
+ デフォルトでは適用されません。
+ </para>
+
+ <para> たとえば、パッケージのデータファイルに対して、
+ <varname>$PAPERSIZE</varname> ファイルで指定される
+ デフォルトのローカルプリンターの用紙サイズを示すために
+ パッチを適用する必要があったとします。
+ この場合、パッケージのデフォルトの設定値を置き換えるために、
+ 考えられるすべての用紙サイズ用のパッチを含めることができます。
+ この例では、
+ "<filename>patch-optional-Letter-papersize</filename>"
+ という名前のパッチや、さらに
+ "<filename>patch-optional-A4-papersize</filename>"
+ という名前で別のパッチも用意しておくことができます。
+ <filename>Makefile</filename> で以下のようにして、
+ これらのパッチを選択して適用するようにします。
+ </para>
+
+ <programlisting>
+ PATCHDIR= ${.CURDIR}/patches
+ .if exists(${PATCHDIR}/patch-optional-${PAPERSIZE}-papersize)
+ OPTIONAL_PATCHFILES+= ${PATCHDIR}/patch-optional-${PAPERSIZE}-papersize
+ .endif </programlisting>
+
+ <para> なお、この例のように
+ <quote><command>.if</command></quote> ステートメント内で
+ <varname>PATCHDIR</varname> を使うためには、その値を定義しておく必要があります。
+ 定義しておかないと、Makefile の処理において、
+ 必要なときより後にならないと定義されないためです。
+ 設定の対象 (この例では <varname>$PAPERSIZE</varname>)
+ が予期しない値に設定されるような問題を避けるため、
+ <quote><command>.if</command></quote> ステートメントを使うようにしてください。
+ </para>
+
+ <para>問題を避けるため、<filename>patch-*</filename>ファイルは
<command>diff -bu</command>フォーマットとし、かつ、曖昧
さなしで適用できるようにします。(曖昧さがあっても強制的にパッチを適用させる
ため、<varname>PATCH_FUZZ_FACTOR=-F2</varname>を設定することができます)。なお、将来の変更が難
@@ -173,19 +225,25 @@
<para>一つ重要なこととして、&os; CVSツリーにチェックインした後に問題を引き起こ
すので、パッチファイルにRCS IDを含ませないように注意してください。
- この問題を避けるため、 <pkg>pkgtools/pkgdiff</pkg> パッケージを使ってください。</para>
+ この問題を避けるため、 <pkg>pkgtools/pkgdiff</pkg> パッケージの
+ <command>pkgdiff</command>
+ を使ってください。</para>
- <para>さらに自動化するため、同パッケージのmkpatchesを使ってパッチ一式を作ることを
+ <para>さらに自動化するため、同パッケージの<command>mkpatches</command>を使ってパッチ一式を作ることを
おすすめします。あなたがやらねばならないことは、ファイルの編集前に
<command>cp -p filename filename.orig</command>のようにするか、あるいはさらに簡単に、同パッケージの
<command>pkgvi</command>を使って、元のファイルを<filename>filename.orig</filename>の名前でバックアップしておくだ
- けです。この方法でパッケージをアップグレードした場合、patchdiffを使って、新
+ けです。この方法でパッケージをアップグレードした場合、<command>patchdiff</command>を使って、新
しいパッチと既存のパッチを簡単に比較することができます。</para>
<para>パッケージを作り終えたとき、忘れずに<command>make makepatchsum</command>コマンドでパッチファ
イルのチェックサムを生成するようにしてください。<xref linkend="components.distinfo"/>を参照してくだ
さい。</para>
+ <para>作者その他のメンテナーが配布しているパッチファイルは、
+ <varname>$PATCHFILES</varname>
+ に列挙することができます。 </para>
+
<para>置いておきたいパッチがあるがpkgsrcにcommitすべきものではない場合、それを
pkgsrcツリーの外の
<filename>$LOCALPATCHES</filename>
@@ -203,75 +261,78 @@
<variablelist>
<varlistentry>
- <term><filename>DESCR</filename></term>
+ <term><filename>DESCR</filename></term>
- <listitem>
- <para>ソフトウェアについての複数行の説明。このファイルには適切なクレジットを含
- めておいてください。他人があなたのユーモアのセンス(あるいは変わった綴り)
- を理解してくれない事、そしてここに書かれたものすべてを他人が読むであろう
- という事を念頭においておいてください。</para>
- </listitem>
+ <listitem>
+ <para>ソフトウェアについての複数行の説明。このファイルには適切なクレジットを含
+ めておいてください。他人があなたのユーモアのセンス(あるいは変わった綴り)
+ を理解してくれない事、そしてここに書かれたものすべてを他人が読むであろう
+ という事を念頭においておいてください。</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term><filename>PLIST</filename></term>
+ <term><filename>PLIST</filename></term>
- <listitem>
- <para>
- このファイルは、システムにインストールされるファイルを管理します:すべて
- のバイナリー、マニュアルページ、その他。ディレクトリーの作成、削除、イン
- サートされた(inserted)ファイルの位置を管理するための、他のディレクティブ
- もこのファイルに記述されます。</para>
- </listitem>
+ <listitem>
+ <para>
+ このファイルは、システムにインストールされるファイルを管理します:すべて
+ のバイナリー、マニュアルページ、その他。ディレクトリーの作成、削除、イン
+ サートされた(inserted)ファイルの位置を管理するための、他のディレクティブ
+ もこのファイルに記述されます。
+ 詳細は<xref linkend="plist"/>を参照してください。 </para>
+ </listitem>
</varlistentry>
</variablelist>
</sect1>
- <sect1>
+ <sect1 id="components.optional">
<title>オプションのファイル</title>
<variablelist>
<varlistentry>
- <term><filename>INSTALL</filename></term>
+ <term><filename>INSTALL</filename></term>
- <listitem>
- <para>このシェルスクリプトは&man.pkg.add.1;実行中に二度起動されます。
- 最初は、パッケー
- ジが展開された後、ファイルが移動される前に、二度目はインストールするファ
- イルが移動された後。このファイルは、
- <filename>PLIST</filename>内の@execコマンドでは不可能な特
- 別な処理のために使うことができます。より詳細な情報は&man.pkg.add.1;と
- &man.pkg.create.1;を参照してください。</para>
- </listitem>
+ <listitem>
+ <para>このシェルスクリプトは&man.pkg.add.1;によって二度起動されます。
+ 最初は、パッケー
+ ジが展開された後、ファイルが移動される前に、二度目はインストールするファ
+ イルが移動された後。このファイルは、
+ <filename>PLIST</filename>内の@execコマンドでは不可能な特
+ 別な処理のために使うことができます。より詳細な情報は&man.pkg.add.1;と
+ &man.pkg.create.1;を参照してください。</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term><filename>DEINSTALL</filename></term>
+ <term><filename>DEINSTALL</filename></term>
- <listitem>
- <para>このスクリプトは、ファイルが削除される前後に実行されます。このスクリプト
- の責任は、パッケージのインストレーションにかかわる雑多なものをきれいにす
- ることです。なぜなら、pkg_deleteは、オリジナルのディストリビューションで
- 作成されたファイルをどのように削除するかをすべて知っておかなければならな
- いからです。より詳細な情報は&man.pkg.delete.1;と
- &man.pkg.create.1;を参照してください。</para>
- </listitem>
+ <listitem>
+ <para>このスクリプトは、ファイルが削除される前後に実行されます。このスクリプト
+ の責任は、パッケージのインストレーションにかかわる雑多なものをきれいにす
+ ることです。なぜなら、pkg_deleteは、オリジナルのディストリビューションで
+ 作成されたファイルをどのように削除するかをすべて知っておかなければならな
+ いからです。より詳細な情報は&man.pkg.delete.1;と
+ &man.pkg.create.1;を参照してください。</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term><filename>MESSAGE</filename></term>
+ <term><filename>MESSAGE</filename></term>
- <listitem>
- <para>パッケージのインストール後にこのファイルの内容が表示されます。
- 完全にフリーでないソフトウェアについての法的な通知等に役立ちます。
- パッケージの<filename>Makefile</filename>で
- <varname>MESSAGE_SUBST</varname>を使うことで、変数を簡単に変えられる
- ことに注意してください:</para>
+ <listitem>
+ <para>パッケージのインストール後にこのファイルの内容が表示されます。
+ 完全にフリーではないソフトウェアについての法的な通知や、
+ apache, PHP などのモジュールのインストール後の
+ 設定ファイルの更新に関するヒント等に役立ちます。
+ パッケージの<filename>Makefile</filename>で
+ <varname>MESSAGE_SUBST</varname>を使うことで、変数を簡単に変えられる
+ ことに注意してください:</para>
- <programlisting>MESSAGE_SUBST+= SOMEVAR="somevalue"</programlisting>
+ <programlisting>MESSAGE_SUBST+= SOMEVAR="somevalue"</programlisting>
- <para>とすると、<filename>MESSAGE</filename>中の "${SOMEVAR}" は、<quote>somevalue</quote>に置換されます。</para>
- </listitem>
+ <para>とすると、<filename>MESSAGE</filename>中の "${SOMEVAR}" は、<quote>somevalue</quote>に置換されます。</para>
+ </listitem>
</varlistentry>
</variablelist>
</sect1>
@@ -281,10 +342,9 @@
<para><command>make</command>とタイプした時に、配布ファイルがこのディレクトリーに展開されます。
<command>make clean</command>
- を実行すれば、これらを削除することができます。</para>
-
- <para>また、このディレクトリーはさまざまなタイムスタンプファイルを作っておくた
- めにも使用されます。</para>
+ を実行すれば、これらを削除することができます。
+ このディレクトリーは、ソースの展開のほか、
+ さまざまなタイムスタンプファイルを作っておくためにも使用されます。</para>
</sect1>
<sect1>
@@ -292,36 +352,9 @@
<para>また、もしあなたがコンフィギュレーションまたは構築するより前に、パッケージ
中に何かファイルを置きたいならば、それらのファイルをfilesディレクトリーに置
- くことができますし、pre-configureターゲットで、<quote>${CP}</quote>コマンドによりコピーす
+ くことができますし、<quote>pre-configure</quote>ターゲットで、
+ <quote>${CP}</quote>コマンドによりコピーす
ることができます。あるいは、<filename>/dev/null</filename>に対するそのファイルの単純なdiffをとり、
パッチメカニズムを使用して、そのファイルを生成することもできます。</para>
</sect1>
-
- <sect1>
- <title>パッケージの移植性</title>
-
- <para>pkgsrc の目玉の一つは、多くのプラットフォームで動作することです。
- そのため、pkgsrc のパッケージの移植性をできるかぎり高めることが重要になります。
- pkgsrc の作業に際して、
- 具体的には以下のような事項に注意してください。</para>
-
- <sect2>
- <title>${INSTALL}, ${INSTALL_DATA_DIR}, ...</title>
-
- <para>一部のプラットフォームに附属する BSD 互換の <command>install</command> は、
- 一度に複数の操作をおこなうことができません。
- このため、 <quote>${INSTALL}</quote> などを使うときは、以下のようにします。</para>
-
- <programlisting>${INSTALL_DATA_DIR} ${PREFIX}/dir1
-${INSTALL_DATA_DIR} ${PREFIX}/dir2</programlisting>
- </sect2>
-
-<!--
-<sect2>
-XXX more portability stuff
-XXX USE_PKGLOCALEDIR
-XXX ???
-</sect2>
--->
- </sect1>
</chapter>
Index: Documentation/pkgsrc/components.xml
===================================================================
RCS file: /cvsroot/htdocs/Documentation/pkgsrc/Attic/components.xml,v
retrieving revision 1.1
retrieving revision 1.3
diff -u -r1.1 -r1.3
--- Documentation/pkgsrc/components.xml 6 Jun 2004 13:31:53 -0000 1.1
+++ Documentation/pkgsrc/components.xml 29 Sep 2004 13:08:36 -0000 1.3
@@ -1,10 +1,11 @@
-<!-- $NetBSD: components.xml,v 1.1 2004/06/06 13:31:53 grant Exp $ -->
+<!-- $NetBSD: components.xml,v 1.3 2004/09/29 13:08:36 hubertf Exp $ -->
-<chapter id="components">
+<chapter id="components"> <?dbhtml filename="components.html"?>
<title>Package components - files, directories and contents</title>
-
- <para>Whenever you're preparing a package, there are a number of files
- involved which are described in the following sections.</para>
+
+ <para> Whenever you're preparing a package, there are a number of
+ files involved which are described in the following
+ sections. </para>
<sect1 id="components.Makefile">
<title><filename>Makefile</filename></title>
@@ -23,24 +24,33 @@
Internet, <varname>MASTER_SITES</varname> which specifies that site,
<varname>CATEGORIES</varname> which denotes the
categories into which the package falls, <varname>PKGNAME</varname>
- which is the name of the package, the <varname>MAINTAINER</varname>
+ which is the name of the package, the <varname>MAINTAINER</varname>'s
name, and the <varname>COMMENT</varname> variable, which should
contain a one-line description of the package (the package name
should not appear, it will be added automatically). The maintainer
variable is there so that anyone who quibbles with the (always
completely correct) decisions taken by the guy who maintains the
- port can complain vigorously.</para>
+ package can complain vigorously, or send chocolate as a sign of
+ appreciation.</para>
<para>The <varname>MASTER_SITES</varname> may be set to one of the
predefined sites:</para>
- <programlisting>${MASTER_SITE_XCONTRIB}
-${MASTER_SITE_GNU}
-${MASTER_SITE_PERL_CPAN}
-${MASTER_SITE_TEX_CTAN}
-${MASTER_SITE_SUNSITE}
-${MASTER_SITE_GNOME}
-${MASTER_SITE_SOURCEFORGE}</programlisting>
+ <programlisting>
+ ${MASTER_SITE_APACHE}
+ ${MASTER_SITE_DEBIAN}
+ ${MASTER_SITE_GNOME}
+ ${MASTER_SITE_GNU}
+ ${MASTER_SITE_GNUSTEP}
+ ${MASTER_SITE_MOZILLA}
+ ${MASTER_SITE_PERL_CPAN}
+ ${MASTER_SITE_SOURCEFORGE}
+ ${MASTER_SITE_SUNSITE}
+ ${MASTER_SITE_R_CRAN}
+ ${MASTER_SITE_SUSE}
+ ${MASTER_SITE_TEX_CTAN}
+ ${MASTER_SITE_XCONTRIB}
+ ${MASTER_SITE_XEMACS} </programlisting>
<para>If one of these predefined sites is chosen, you may require the
ability to specify a subdirectory of that site. Since these macros
@@ -48,13 +58,15 @@
<emphasis>must</emphasis> use the following construct to specify a
subdirectory:</para>
- <programlisting>${MASTER_SITE_GNU:=subdirectory/name/}</programlisting>
+ <programlisting>
+ ${MASTER_SITE_GNU:=subdirectory/name/}
+ ${MASTER_SITE_SOURCEFORGE:=project_name/} </programlisting>
<para>Note the trailing slash after the subdirectory name.</para>
<note>
<para><varname>MASTER_SITE_SUBDIR</varname> has been deprecated and
- <emphasis>should no longer be used</emphasis>.</para>
+ <emphasis>should no longer be used</emphasis>.</para>
</note>
<para>If the package has multiple <varname>DISTFILES</varname> or multiple
@@ -63,10 +75,10 @@
<quote>foo</quote> may be found. <quote>foo</quote>
includes the suffix, e.g.</para>
- <programlisting>DISTFILES= ${DISTNAME}${EXTRACT_SUFX}
-DISTFILES+= foo-file.tar.gz
+<programlisting>DISTFILES= ${DISTNAME}${EXTRACT_SUFX}
+DISTFILES+= foo-file.tar.gz
SITES_foo-file.tar.gz=http://www.somewhere.com/somehow/ \
- http://www.somewhereelse.com/mirror/somehow/</programlisting>
+ http://www.somewhereelse.com/mirror/somehow/</programlisting>
<para>Note that the normal default setting of <varname>DISTFILES</varname>
must be made explicit if you want to add to it (rather than replace
@@ -76,51 +88,51 @@
<varname>CATEGORIES</varname>. If more than
one is used, they need to be separated by spaces:</para>
- <programlisting>archivers audio benchmarks biology cad
-chat comms converters cross databases
-devel editors emulators finance fonts
-games graphics ham japanese lang
-mail math mbone misc net
-news parallel print security shells
-sysutils textproc time wm www
-x11</programlisting>
+ <programlisting>
+archivers cross geography meta-pkgs security
+audio databases graphics misc shells
+benchmarks devel ham multimedia sysutils
+biology editors inputmethod net textproc
+cad emulators lang news time
+chat finance mail parallel wm
+comms fonts math pkgtools www
+converters games mbone print x11</programlisting>
- <para>Please pay attention to the following gotchas:</para>
+ <para> Please pay attention to the following gotchas: </para>
<itemizedlist>
<listitem>
- <para>Add <varname>MANCOMPRESSED</varname> if manpages are installed in
- compressed form by the package; see comment in
- <filename>bsd.pkg.mk</filename>.</para>
+ <para>Add <varname>MANCOMPRESSED</varname> if manpages are installed in
+ compressed form by the package; see comment in
+ <filename>bsd.pkg.mk</filename>.</para>
</listitem>
<listitem>
- <para>Replace <filename>/usr/local</filename> with
- <quote>${PREFIX}</quote> in all files (see patches, below).</para>
+ <para>Replace <filename>/usr/local</filename> with
+ <quote>${PREFIX}</quote> in all files (see patches, below).</para>
</listitem>
<listitem>
- <para>If the package installs any info files, see
- <xref linkend="features.info-files"/>.</para>
+ <para>If the package installs any info files, see
+ <xref linkend="faq.info-files"/>.</para>
</listitem>
<listitem>
- <para>Adjust <varname>MAINTAINER</varname> to be either yourself,
- if you plan
- to maintain the package for future updates, or set it to the default
- maintainer <email>tech-pkg@NetBSD.org</email>.</para>
+ <para>Set <varname>MAINTAINER</varname> to be yourself.
+ If you really can't maintain the package for future updates,
+ set it to <email>tech-pkg@NetBSD.org</email>.</para>
</listitem>
<listitem>
- <para>If there exists a home page for the software in question, please
- add the variable <varname>HOMEPAGE</varname> right after
- <varname>MAINTAINER</varname>. The value of this
- variable should be the URL for the home page.</para>
+ <para>If a home page for the software in question exists,
+ add the variable <varname>HOMEPAGE</varname> right after
+ <varname>MAINTAINER</varname>. The value of this
+ variable should be the URL for the home page.</para>
</listitem>
<listitem>
- <para>Be sure to set the <varname>COMMENT</varname> variable to a short
- description of the package.</para>
+ <para>Be sure to set the <varname>COMMENT</varname> variable to a short
+ description of the package, not containing the pkg's name.</para>
</listitem>
</itemizedlist>
</sect1>
@@ -133,7 +145,7 @@
original file distributed by the author. This ensures that the
distfile retrieved from the Internet has not been corrupted during
transfer or altered by a malign force to introduce a security hole.
- It is best generated using the <command>make makesum</command> command.
+ It is generated using the <command>make makesum</command> command.
The digest algorithm used was, at one stage, md5, but that was felt
lacking compared to sha1, and so sha1 is now the default algorithm.
The distfile size is also generated and stored in new distinfo files.
@@ -145,7 +157,7 @@
<emphasis>sha384</emphasis> and <emphasis>sha512</emphasis>.</para>
<para>Some packages have different sets of distfiles on a per architecture
- basis (a good example is <pkg>www/navigator</pkg>). These are kept in the
+ basis, for example <pkg>www/navigator</pkg>). These are kept in the
same distinfo file and care should be taken when upgrading such a
package to ensure distfile information is not lost.</para>
@@ -154,7 +166,9 @@
<xref linkend="components.patches"/>) for the package is also stored in
the <filename>distinfo</filename> file. This is a message
digest/checksum of all lines in the patch file except the &os; RCS Id.
- This file is generated by invoking <command>make makepatchsum</command>.</para>
+ This file is generated by invoking <command>make
+ makepatchsum</command> (or <command>make mps</command> if you're
+ in a hurry).</para>
</sect1>
<sect1 id="components.patches">
@@ -169,9 +183,48 @@
<filename>patch-aa</filename> is applied before
<filename>patch-ab</filename>, etc.</para>
- <para>The <filename>patch-??</filename> files should be in
+ <para> Patch files which are optional and will depend on local
+ site configuration can be included with names matching the
+ pattern <filename>patches/patch-optional-*</filename>. Their
+ suffixes should match the configuration options. The selected
+ optional patch file names should be assigned to the variable
+ <varname>OPTIONAL_PATCHFILES</varname>. They will not be
+ applied by default.
+ </para>
+
+ <para> For example if a package data file needs patching to
+ indicate the default local printer paper size as specified in
+ the <varname>$PAPERSIZE</varname> file you can include patches
+ for all the possible paper sizes other than the one the package
+ comes configured for by default. In this case you might have a
+ patch called
+ "<filename>patch-optional-Letter-papersize</filename>" and/or
+ another patch called
+ "<filename>patch-optional-A4-papersize</filename>". In your
+ <filename>Makefile</filename> you would select between them with
+ the following construct:
+ </para>
+
+ <programlisting>
+ PATCHDIR= ${.CURDIR}/patches
+ .if exists(${PATCHDIR}/patch-optional-${PAPERSIZE}-papersize)
+ OPTIONAL_PATCHFILES+= ${PATCHDIR}/patch-optional-${PAPERSIZE}-papersize
+ .endif </programlisting>
+
+ <para> Note that you have to define the value of
+ <varname>PATCHDIR</varname> in order to use it in a
+ <quote><command>.if</command></quote> statement like this as
+ otherwise it's not defined until too late during the processing
+ of the Makefile. You should use a
+ <quote><command>.if</command></quote> statement in order to
+ avoid problems should the configuration item
+ (<varname>$PAPERSIZE</varname> in this example) be set to an
+ unexpected value.
+ </para>
+
+ <para>The <filename>patch-*</filename> files should be in
<command>diff -bu</command> format, and apply without a fuzz to avoid
- problems (To force patches to apply
+ problems. (To force patches to apply
with fuzz you can set <varname>PATCH_FUZZ_FACTOR=-F2</varname>).
Furthermore, do not put changes for more than one file into a single
patch-file, as this will make future modifications more difficult.</para>
@@ -183,20 +236,25 @@
<para>One important thing to mention is to pay attention that no RCS IDs
get stored in the patch files, as these will cause problems when
later checked into the &os; CVS tree. Use the
+ <command>pkgdiff</command> from the
<pkg>pkgtools/pkgdiff</pkg> package to avoid these problems.</para>
- <para>For even more automation, we recommend using mkpatches from the same
+ <para>For even more automation, we recommend using <command>mkpatches</command> from the same
package to make a whole set of patches. You just have to backup files
before you edit them to <filename>filename.orig</filename>, e.g. with
<command>cp -p filename filename.orig</command> or, easier, by using
- <command>pkgvi</command> from the same package. If you upgrade a package
+ <command>pkgvi</command> again from the same package. If you upgrade a package
this way, you can easily compare the new set of patches with the
- previously existing one with patchdiff.</para>
+ previously existing one with <command>patchdiff</command>.</para>
<para>When you have finished a package, remember to generate the checksums
for the patch files by using the <command>make makepatchsum</command>
command, see <xref linkend="components.distinfo"/>.</para>
+ <para>Patch files that are distributed by the author or other
+ maintainers can be listed in
+ <varname>$PATCHFILES</varname>. </para>
+
<para>If it is desired to store any patches that should not be committed into
pkgsrc, they can be kept outside the pkgsrc tree in the
<filename>$LOCALPATCHES</filename>
@@ -216,76 +274,79 @@
<variablelist>
<varlistentry>
- <term><filename>DESCR</filename></term>
+ <term><filename>DESCR</filename></term>
- <listitem>
- <para>A multi-line description of the piece of software. This should include
- any credits where they are due. Please bear in mind that others do not
- share your sense of humour (or spelling idiosyncrasies), and that others
- will read everything that you write here.</para>
- </listitem>
+ <listitem>
+ <para>A multi-line description of the piece of software. This should include
+ any credits where they are due. Please bear in mind that others do not
+ share your sense of humour (or spelling idiosyncrasies), and that others
+ will read everything that you write here.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term><filename>PLIST</filename></term>
+ <term><filename>PLIST</filename></term>
- <listitem>
- <para>
- This file governs the files that are installed on your system: all the
- binaries, manual pages, etc. There are other directives which may be
- entered in this file, to control the creation and deletion of
- directories, and the location of inserted files.</para>
- </listitem>
+ <listitem>
+ <para>
+ This file governs the files that are installed on your system: all the
+ binaries, manual pages, etc. There are other directives which may be
+ entered in this file, to control the creation and deletion of
+ directories, and the location of inserted files.
+ See <xref linkend="plist"/> for more information. </para>
+ </listitem>
</varlistentry>
</variablelist>
</sect1>
- <sect1>
+ <sect1 id="components.optional">
<title>Optional files</title>
<variablelist>
<varlistentry>
- <term><filename>INSTALL</filename></term>
+ <term><filename>INSTALL</filename></term>
- <listitem>
- <para>Shell script invoked twice during &man.pkg.add.1;.
- First time after package
- extraction and before files are moved in place, the second time after
- the files to install are moved in place. This can be used to do any
- custom procedures not possible with @exec commands in
- <filename>PLIST</filename>. See
- &man.pkg.add.1; and &man.pkg.create.1; for more information.</para>
- </listitem>
+ <listitem>
+ <para>This shell script is invoked twice by &man.pkg.add.1;.
+ First time after package
+ extraction and before files are moved in place, the second time after
+ the files to install are moved in place. This can be used to do any
+ custom procedures not possible with @exec commands in
+ <filename>PLIST</filename>. See
+ &man.pkg.add.1; and &man.pkg.create.1; for more information.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term><filename>DEINSTALL</filename></term>
+ <term><filename>DEINSTALL</filename></term>
- <listitem>
- <para>This script is executed before and after any files are removed. It is
- this script's responsibility to clean up any additional messy details
- around the package's installation, since all pkg_delete knows is how to
- delete the files created in the original distribution.
- See &man.pkg.delete.1;
- and &man.pkg.create.1; for more information.</para>
- </listitem>
+ <listitem>
+ <para>This script is executed before and after any files are removed. It is
+ this script's responsibility to clean up any additional messy details
+ around the package's installation, since all pkg_delete knows is how to
+ delete the files created in the original distribution.
+ See &man.pkg.delete.1;
+ and &man.pkg.create.1; for more information.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term><filename>MESSAGE</filename></term>
+ <term><filename>MESSAGE</filename></term>
- <listitem>
- <para>Display this file after installation of the package.
- Useful for things like legal notices on almost-free software, etc.
- Please note that you can modify variables in it easily by using
- <varname>MESSAGE_SUBST</varname> in the package's
- <filename>Makefile</filename>:</para>
-
- <programlisting>MESSAGE_SUBST+= SOMEVAR="somevalue"</programlisting>
-
- <para>replaces "${SOMEVAR}" with <quote>somevalue</quote> in
- <filename>MESSAGE</filename>.</para>
- </listitem>
+ <listitem>
+ <para>Display this file after installation of the package.
+ Useful for things like legal notices on almost-free
+ software and hints for updating config files after
+ installing modules for apache, PHP etc.
+ Please note that you can modify variables in it easily by using
+ <varname>MESSAGE_SUBST</varname> in the package's
+ <filename>Makefile</filename>:</para>
+
+ <programlisting>MESSAGE_SUBST+= SOMEVAR="somevalue"</programlisting>
+
+ <para>replaces "${SOMEVAR}" with <quote>somevalue</quote> in
+ <filename>MESSAGE</filename>.</para>
+ </listitem>
</varlistentry>
</variablelist>
</sect1>
@@ -295,9 +356,8 @@
<para>When you type <command>make</command> the distribution files are
unpacked into this directory. It can be removed by running
- <command>make clean</command>.</para>
-
- <para>This directory is also used to keep various timestamp files.</para>
+ <command>make clean</command>. Besides the sources, this
+ directory is also used to keep various timestamp files.</para>
</sect1>
<sect1>
@@ -305,37 +365,10 @@
<para>If you have any files that you wish to be placed in the package prior
to configuration or building, you could place these files here and use
- a <quote>${CP}</quote> command in the pre-configure target to achieve
+ a <quote>${CP}</quote> command in the
+ <quote>pre-configure</quote> target to achieve
this. Alternatively, you could simply diff the file against
<filename>/dev/null</filename> and use the patch mechanism to manage
the creation of this file.</para>
</sect1>
-
- <sect1>
- <title>Portability of packages</title>
-
- <para>One appealing feature of pkgsrc is that it runs on many different
- platforms. As a result, it is important to ensure, where possible,
- that packages in pkgsrc are portable. There are some particular
- details you should pay attention to while working on pkgsrc.</para>
-
- <sect2>
- <title>${INSTALL}, ${INSTALL_DATA_DIR}, ...</title>
-
- <para>The BSD-compatible <command>install</command> supplied with some
- operating systems will not perform more than one operation at a time.
- As such, you should call <quote>${INSTALL}</quote>, etc. like this:</para>
-
- <programlisting>${INSTALL_DATA_DIR} ${PREFIX}/dir1
-${INSTALL_DATA_DIR} ${PREFIX}/dir2</programlisting>
- </sect2>
-
-<!--
-<sect2>
-XXX more portability stuff
-XXX USE_PKGLOCALEDIR
-XXX ???
-</sect2>
--->
- </sect1>
</chapter>