[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
pkgsrc/doc/guide/files/components.xml: 1.32 -> 1.34
以下のページの更新をしました。ツッコミをお願いします。
pkgsrc/doc/guide/files/components.xml: 1.32 -> 1.34
> revision 1.34
> date: 2007/01/11 07:33:15; author: wiz; state: Exp; lines: +2 -2
> Fix typo.
> ----------------------------
> revision 1.33
> date: 2007/01/11 03:37:44; author: rillig; state: Exp; lines: +65 -25
> Modernized the section on the patches/ directory.
月曜日までに異議がなければ、 commit します。
以下、訳と原文それぞれの新旧の差分です。
--- components.xml.orig 2007-01-27 22:34:51.000000000 +0900
+++ components.xml 2007-01-27 22:34:51.000000000 +0900
@@ -1,6 +1,6 @@
-<!-- $NetBSD: components.xml,v 1.32 2006/12/15 13:22:14 martti Exp $ -->
+<!-- $NetBSD: components.xml,v 1.34 2007/01/11 07:33:15 wiz Exp $ -->
<!-- Based on english version: -->
-<!-- NetBSD: components.xml,v 1.32 2006/12/15 13:22:14 martti Exp -->
+<!-- NetBSD: components.xml,v 1.34 2007/01/11 07:33:15 wiz Exp -->
<chapter id="components"> <?dbhtml filename="components.html"?>
<title>パッケージコンポーネント - ファイル、ディレクトリー、およびコンテンツ</title>
@@ -212,31 +212,66 @@
<sect1 id="components.patches">
<title>patches/*</title>
- <para>このディレクトリーは、
- &man.patch.1;コマンドが使用するファイルを含んでい
- ます。このファイルは、配布ファイルのソースを&os;上で完全にコンパイルして
- 実行できるように変更するためのものです。これらのファイルは、アルファベット
- 順(シェルによる
- <quote>patches/patch-*</quote>
- 展開順)で適用されます。つまり<filename>patch-aa</filename>は
- <filename>patch-ab</filename>より前に適用されます。</para>
+ <para>多くのパッケージは、pkgsrc で対応している各種プラットフォーム上で、
+ まだ無修正では動きません。このため、そのようなパッケージを動くようにするために、
+ 多数の独自のパッチファイルが必要です。このパッチファイルは、
+ <filename>patches/</filename> ディレクトリーにあります。</para>
+
+ <para><emphasis>patch</emphasis> 相では、<varname>WRKSRC</varname>
+ 以下にファイルが展開された後に、展開されたファイルに対して、
+ このパッチファイルが<ulink
+ url="http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_13_03">アルファベット
+ 順</ulink>で適用されます。つまり<filename>patch-aa</filename>は
+ <filename>patch-ab</filename> などより前に適用されます。</para>
+
+<sect2 id="components.patch.structure">
+<title>個々のパッチファイルの構造</title>
<para>問題を避けるため、<filename>patch-*</filename>ファイルは
<command>diff -bu</command>フォーマットとし、かつ、曖昧
さなしで適用できるようにします。(曖昧さがあっても強制的にパッチを適用させる
- ため、<varname>PATCH_FUZZ_FACTOR=-F2</varname>を設定することができます)。なお、将来の変更が難
- しくなってしまうので、一つのパッチファイルに、複数のファイルへの変更を入れ
- るのは止めてください。</para>
-
- <para>同様に、一つのファイルへのパッチあては最大一回とし、複数のパッチを使って複
- 数回パッチをあててはいけません。もしファイルに複数のパッチが必要なら、それ
- は一つのファイルにまとめておきます。</para>
+ ため、<varname>PATCH_FUZZ_FACTOR=-F2</varname>を設定することができます)。
+ さらに、各パッチファイルは一つのファイルに対する修正だけを含むようにし、
+ また、一つのファイルを複数のパッチファイルによって修正するようなことはしないようにします。
+ こうすることで、将来の変更が簡単になります。</para>
+
+ <para>各パッチファイルは、以下のような構造となっています: 最初の行には
+ パッチそのものの RCS Id があります。2 行目は、見栄えをよくするため、
+ 空にします。これより後には、そのパッチによる各変更についてのコメントを書きます。
+ これには標準的な事例がいくつもあります。</para>
+
+ <itemizedlist>
+
+ <listitem><para>シェルスクリプト中の &man.test.1; 用の <literal>==</literal>
+ 演算子を <literal>=</literal> に置き換えるパッチには、
+ 同じ説明を省くために、<!-- xref linkend="test-eqeq"/ -->
+ への参照を含めるようにします。</para></listitem>
+
+ <listitem><para>一般に知られている脆弱性に対するパッチには、
+ その脆弱性の ID (CAN, CVE) を記すようにします。</para></listitem>
+
+ <listitem><para>ソースコードを変更するパッチには、
+ そのパッチを必要とするプラットフォームやその他の環境 (たとえばコンパイラー)
+ を記すようにします。</para></listitem>
+
+ </itemizedlist>
+
+ <para>以上のほか、あらゆる事例において、
+ そのアプリケーションのコードを理解している開発者がパッチを利用できるようにするため、
+ パッチにはコメントを書くようにします。上流の開発者に対しては特に注意が必要です。
+ たいていの場合、私たちの将来の作業を減らすために、
+ 上流の開発者にパッチを採用してもらいたいからです。</para>
+
+</sect2>
+<sect2 id="components.patches.caveats">
+<title>パッチファイルを作成する</title>
<para>一つ重要なこととして、&os; CVSツリーにチェックインした後に問題を引き起こ
すので、パッチファイルにRCS IDを含ませないように注意してください。
- この問題を避けるため、 <filename role="pkg">pkgtools/pkgdiff</filename> パッケージの
+ この問題を避けるため、 <filename
+ role="pkg">pkgtools/pkgdiff</filename> パッケージの
<command>pkgdiff</command>
- を使ってください。</para>
+ コマンドを使ってください。</para>
<para>さらに自動化するため、同パッケージの<command>mkpatches</command>を使ってパッチ一式を作ることを
おすすめします。あなたがやらねばならないことは、ファイルの編集前に
@@ -261,13 +296,17 @@
こうすることで、pkgsrc を使っていない利用者も幸せになれますし、
通常は、将来のバージョンでパッチを削除することができるようになります。</para>
+</sect2>
+<sect2 id="components.patches.sources">
+<title>パッチファイルの出どころ</title>
+
<para>pkgsrc の複数のパッケージが同じ distfile を使っているなどの理由で、
複数のパッケージの間でパッチを共有したい場合は、
<varname>PATCHDIR</varname> をパッチファイルのある場所へのパスに設定します。
たとえば以下のようにします。</para>
- <programlisting>
+<programlisting>
PATCHDIR= ${.CURDIR}/../xemacs/patches
- </programlisting>
+</programlisting>
<para>作者その他のメンテナーが配布しているパッチファイルは、
<varname>PATCHFILES</varname>
@@ -287,6 +326,7 @@
ます。このディレクトリーにあるファイルはすべてパッチファイルとして扱われ、
<emphasis>pkgsrcのパッチが適用された後に、このパッチが適用されます</emphasis>。</para>
+</sect2>
<sect2 id="components.patches.guidelines">
<title>パッチ作成の指針</title>
@@ -412,7 +452,7 @@
フィードバックされた修正をパッケージのコードから直接利用することができるようになります。</para>
<para>フィードバックをする方法は、一般的には、
- 前の節で説明したようにパッチをきれいに書き直し (pkgsrc で追加されたパッチは、
+ パッチをきれいに書き直し (pkgsrc で追加されたパッチは、
時にはクイックハックであることがあるからです)、
フィードバック先のプロジェクト用の適切な追跡システムに対してバグ報告をし、
変更が受け入れられるよう本家の作者とともに作業する、というものです。
Index: components.xml
===================================================================
RCS file: /cvsroot/pkgsrc/doc/guide/files/components.xml,v
retrieving revision 1.32
retrieving revision 1.34
diff -u -r1.32 -r1.34
--- components.xml 15 Dec 2006 13:22:14 -0000 1.32
+++ components.xml 11 Jan 2007 07:33:15 -0000 1.34
@@ -1,4 +1,4 @@
-<!-- $NetBSD: components.xml,v 1.32 2006/12/15 13:22:14 martti Exp $ -->
+<!-- $NetBSD: components.xml,v 1.34 2007/01/11 07:33:15 wiz Exp $ -->
<chapter id="components"> <?dbhtml filename="components.html"?>
<title>Package components - files, directories and contents</title>
@@ -211,32 +211,67 @@
<sect1 id="components.patches">
<title>patches/*</title>
- <para>This directory contains files that are used by the
- &man.patch.1; command to
- modify the sources as distributed in the distribution file into a form
- that will compile and run perfectly on &os;. The files are applied
- successively in alphabetic order (as returned by a shell
- <quote>patches/patch-*</quote> glob expansion), so
- <filename>patch-aa</filename> is applied before
+ <para>Many packages still don't work out-of-the box on the various
+ platforms that are supported by pkgsrc. Therefore, a number of custom
+ patch files are needed to make the package work. These patch files are
+ found in the <filename>patches/</filename> directory.</para>
+
+ <para>In the <emphasis>patch</emphasis> phase, these patches are
+ applied to the files in <varname>WRKSRC</varname> directory after
+ extracting them, in <ulink
+ url="http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_13_03">alphabetic
+ order</ulink>, so <filename>patch-aa</filename> is applied before
<filename>patch-ab</filename>, etc.</para>
+<sect2 id="components.patch.structure">
+<title>Structure of a single patch file</title>
+
<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
- 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>
-
- <para>Similar, a file should be patched at most once, not several times by
- several different patches. If a file needs several patches, they should
- be combined into one file.</para>
+ problems. (To force patches to apply with fuzz you can set
+ <varname>PATCH_FUZZ_FACTOR=-F2</varname>). Furthermore, each patch
+ should contain only changes for a single file, and no file should be
+ patched by more than one patch file. This helps to keep future
+ modifications simple.</para>
+
+ <para>Each patch file is structured as follows: In the first line,
+ there is the RCS Id of the patch itself. The second line should be
+ empty for aesthetic reasons. After that, there should be a comment for
+ each change that the patch does. There are a number of standard
+ cases:</para>
+
+ <itemizedlist>
+
+ <listitem><para>Patches that replace the <literal>==</literal>
+ operator for &man.test.1; with <literal>=</literal> in shell scripts
+ should contain a reference to <!-- xref linkend="test-eqeq"/ -->, to avoid
+ redundant explanations.</para></listitem>
+
+ <listitem><para>Patches for commonly known vulnerabilities should
+ mention the vulnerability ID (CAN, CVE).</para></listitem>
+
+ <listitem><para>Patches that change source code should mention the
+ platform and other environment (for example, the compiler) that the
+ patch is needed for.</para></listitem>
- <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
+ </itemizedlist>
+
+ <para>In all other cases, the patch should be commented so that any
+ developer who knows the code of the application can make some use of
+ the patch. Special care should be taken for the upstream developers,
+ since we generally want that they accept our patches, so we have less
+ work in the future.</para>
+
+</sect2>
+<sect2 id="components.patches.caveats">
+<title>Creating patch files</title>
+
+ <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
- <filename role="pkg">pkgtools/pkgdiff</filename> package to avoid
- these problems.</para>
+ <command>pkgdiff</command> command from the <filename
+ role="pkg">pkgtools/pkgdiff</filename> package to avoid these
+ problems.</para>
<para>For even more automation, we recommend using
<command>mkpatches</command> from the same package to make a
@@ -262,13 +297,17 @@
and usually makes it possible to remove the patch in future
version.</para>
+</sect2>
+<sect2 id="components.patches.sources">
+<title>Sources where the patch files come from</title>
+
<para>If you want to share patches between multiple packages
in pkgsrc, e.g. because they use the same distfiles, set
<varname>PATCHDIR</varname> to the path where the patch files
can be found, e.g.:</para>
- <programlisting>
+<programlisting>
PATCHDIR= ${.CURDIR}/../xemacs/patches
- </programlisting>
+</programlisting>
<para>Patch files that are distributed by the author or other
maintainers can be listed in
@@ -288,6 +327,7 @@
and <emphasis>they are applied after pkgsrc patches are
applied</emphasis>.</para>
+</sect2>
<sect2 id="components.patches.guidelines">
<title>Patching guidelines</title>
@@ -411,8 +451,8 @@
NetBSD. Furthermore, any user that gets newer distfiles will get
the fixes straight from the packaged code.</para>
- <para>This generally involves cleaning up the patches as described
- in the following section (because sometimes the patches that are
+ <para>This generally involves cleaning up the patches
+ (because sometimes the patches that are
added to pkgsrc are quick hacks), filling bug reports in the
appropriate trackers for the projects and working with the
mainstream authors to accept your changes. It is