[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

pkgsrc/doc/guide/files/components.xml: 1.26 -> 1.28



以下のページの更新をしました。ツッコミをお願いします。

pkgsrc/doc/guide/files/components.xml: 1.26 -> 1.28

> revision 1.28
> date: 2006/09/03 00:20:49;  author: wiz;  state: Exp;  lines: +2 -2
> Fix a typo.
> ----------------------------
> revision 1.27
> date: 2006/09/01 16:35:38;  author: jmmv;  state: Exp;  lines: +138 -7
> Add some more GNOME-specific packaging and porting information:
> - Document how to handle .desktop files.
> - Document how to handle icons for the hicolor theme.
> - Add a chapter detailing the GNOME meta packages, the packaging of new
>   applications and the updatee procedure.
> 
> Also add some documentation on how to better handle and create patches.

金曜日までに異議がなければ、 commit します。

以下、訳と原文それぞれの新旧の差分です。

--- components.xml.orig	2006-12-14 00:51:46.000000000 +0900
+++ components.xml	2006-12-14 00:51:46.000000000 +0900
@@ -1,6 +1,6 @@
-<!-- $NetBSD: components.xml,v 1.26 2006/07/24 10:32:36 rillig Exp $ -->
+<!-- $NetBSD: components.xml,v 1.28 2006/09/03 00:20:49 wiz Exp $ -->
 <!-- Based on english version: -->
-<!-- NetBSD: components.xml,v 1.26 2006/07/24 10:32:36 rillig Exp   -->
+<!-- NetBSD: components.xml,v 1.28 2006/09/03 00:20:49 wiz Exp   -->
 
 <chapter id="components"> <?dbhtml filename="components.html"?>
   <title>パッケージコンポーネント - ファイル、ディレクトリー、およびコンテンツ</title>
@@ -242,12 +242,6 @@
       イルのチェックサムを生成するようにしてください。<xref linkend="components.distinfo"/>を参照してくだ
       さい。</para>
 
-    <para>(たとえば、マニュアルページの場所を pkgsrc の流儀に合わせるようなものではなく)
-      distfile の問題を修正するパッチを追加した場合は、
-      そのパッチをバグ報告としてメンテナーに送ってください。こうすることで、
-      pkgsrc を使っていないパッケージ利用者が幸せになれますし、
-      通常は、将来のバージョンでパッチを削除することができるようになります。</para>
-
     <para>作者その他のメンテナーが配布しているパッチファイルは、
       <varname>$PATCHFILES</varname>
       に列挙することができます。 </para>
@@ -262,6 +256,144 @@
       るようにしたい場合は、そのパッチを<filename>$LOCALPATCHES/graphics/png/mypatch</filename>に置き
       ます。このディレクトリーにあるファイルはすべてパッチファイルとして扱われ、
       <emphasis>pkgsrcのパッチが適用された後に、このパッチが適用されます</emphasis>。</para>
+
+    <sect2 id="components.patches.guidelines">
+      <title>パッチ作成の指針</title>
+
+      <para>コードの移植性に関する問題を修正する場合は、
+      プリプロセッサーの細工を使ってオペレーティングシステムやプラットフォームを判別するようなことはしてはいけません。
+      そのような方法では、各 OS 固有性の詳細が適切に抽象化できないため、
+      他のオペレーティングシステムに対する移植性を損なってしまいます。</para>
+      
+      <para>一般的な決めごとは、
+      アプリケーションを構築しているオペレーティングシステムそのものを検査するのではなく、
+      必要としている特有の<emphasis>機能</emphasis>を検査する、というものです。
+      たとえば、kqueue は NetBSD において利用可能であると仮定して
+      <varname>__NetBSD__</varname> マクロを kqueue 対応の条件として使う、
+      ということはせずに、kqueue 自体を検出するようにするのです。
+      そしてこれは、一般的には
+      <command>configure</command> スクリプトにパッチを適用することになります。
+      ある OS が他の OS (たとえば kqueue を実装した Linux)
+      のインターフェースを採用してはいけない理由はまったくありませんが、
+      前述のようにオペレーティングシステムそのものを検査してしまうと、
+      そのような状況に対応することができません。</para>
+      
+      <para>もちろん、機能を検査することは、
+      一般的に、開発者側の負担が多くなります。しかし、
+      機能を検査するようにすれば、その結果はきれいな変更となり、
+      他の多くのプラットフォームで動作させられる可能性があります。
+      また、本家のソースに統合される可能性が高くなることはいうまでもありません。
+      <emphasis>正しくない限り動かない</emphasis>の哲学を忘れないでください。</para>
+
+      <para>典型的な例としては、以下のようなものがあります。</para>
+
+      <table id="patch-examples">
+	<title>パッチ適用例</title>
+
+	<tgroup cols="3">
+	  <thead>
+	    <row>
+	      <entry>場所</entry>
+	      <entry>誤</entry>
+	      <entry>正</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+	    <row>
+	      <entry>configure スクリプト</entry>
+	      <entry>
+		<programlisting>case ${target_os} in
+      netbsd*) have_kvm=yes ;;
+      *)       have_kvm=no  ;;
+  esac</programlisting>
+	      </entry>
+
+	      <entry>
+		<programlisting>AC_CHECK_LIB(kvm, kvm_open, have_kvm=yes, have_kvm=no)</programlisting>
+	      </entry>
+	    </row>
+
+	    <row>
+	      <entry>C ソースファイル</entry>
+	      <entry>
+		<programlisting>#if defined(__NetBSD__)
+  #  include &lt;sys/event.h&gt;
+  #endif</programlisting>
+	      </entry>
+	      <entry>
+		<programlisting>#if defined(HAVE_SYS_EVENT_H)
+  #  include &lt;sys/event.h&gt;
+  #endif</programlisting>
+	      </entry>
+	    </row>
+
+	    <row>
+	      <entry>C ソースファイル</entry>
+	      <entry><programlisting>int
+  monitor_file(...)
+  {
+  #if defined(__NetBSD__)
+      int fd = kqueue();
+      ...
+  #else
+      ...
+  #endif
+  }</programlisting>
+	      </entry>
+	      <entry>
+		<programlisting>int
+  monitor_file(...)
+  {
+  #if defined(HAVE_KQUEUE)
+      int fd = kqueue();
+      ...
+  #else
+      ...
+  #endif
+  }</programlisting>
+	      </entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+
+      <para>さらなる情報は、<emphasis>Making
+      packager-friendly software</emphasis> の記事 (<ulink
+      url="http://www.onlamp.com/pub/a/onlamp/2005/03/31/packaging.html">第
+      1 部</ulink>、<ulink
+      url="http://www.oreillynet.com/pub/a/onlamp/2005/04/28/packaging2.html">第
+      2 部</ulink>) をお読みください。この記事では、ソフトウェアをパッケージ化しやすくする方法について、
+      複数の点での詳細をまとめています。ここで述べられている提案は、いずれも、
+      私たちが pkgsrc の作業をした経験から集められたものですので、
+      パッチの作成に際しても役に立つかもしれません。</para>
+
+    </sect2>
+
+    <sect2 id="components.patches.feedback">
+      <title>作者へのフィードバック</title>
+
+      <para>常に、常に、<emphasis role="strong">常に</emphasis>、
+      パッケージに施したあらゆる<emphasis>移植性に関する修正</emphasis>や改良点を、
+      本家の開発者に還元するようにしてください。
+      彼らに移植性についての注意を喚起して、将来のバージョンが無修正で
+      NetBSD で構築できるようにするためには、そうするしかないのです。
+      また、将来のバージョンの配布ファイルの利用者は、
+      フィードバックされた修正をパッケージのコードから直接利用することができるようになります。</para>
+
+      <para>フィードバックをする方法は、一般的には、
+      前の節で説明したようにパッチをきれいに書き直し (pkgsrc で追加されたパッチは、
+      時にはクイックハックであることがあるからです)、
+      フィードバック先のプロジェクト用の適切な追跡システムに対してバグ報告をし、
+      変更が受け入れられるよう本家の作者とともに作業する、というものです。
+      フィードバックをすることで、pkgsrc のパッケージを単純なものとし、
+      さほど労力を割かずに将来の変更ができるようにするということが、
+      <emphasis>特に重要</emphasis>です。</para>
+
+      <para>フリーソフトウェアの理念をサポートして下さい。</para>
+
+    </sect2>
+
   </sect1>
 
   <sect1 id="other-mandatory-files">
Index: components.xml
===================================================================
RCS file: /cvsroot/pkgsrc/doc/guide/files/components.xml,v
retrieving revision 1.26
retrieving revision 1.28
diff -u -r1.26 -r1.28
--- components.xml	24 Jul 2006 10:32:36 -0000	1.26
+++ components.xml	3 Sep 2006 00:20:49 -0000	1.28
@@ -1,4 +1,4 @@
-<!-- $NetBSD: components.xml,v 1.26 2006/07/24 10:32:36 rillig Exp $ -->
+<!-- $NetBSD: components.xml,v 1.28 2006/09/03 00:20:49 wiz Exp $ -->
 
 <chapter id="components"> <?dbhtml filename="components.html"?>
   <title>Package components - files, directories and contents</title>
@@ -239,12 +239,6 @@
       for the patch files by using the <command>make makepatchsum</command>
       command, see <xref linkend="components.distinfo"/>.</para>
 
-    <para>When adding a patch that corrects a problem in the distfile (rather
-      than e.g. enforcing pkgsrc's view of where man pages should go), send
-      the patch as a bug report to the maintainer.  This benefits
-      non-pkgsrc users of the package, and usually enables removing
-      the patch in future version.</para>
-
     <para>Patch files that are distributed by the author or other
       maintainers can be listed in
       <varname>$PATCHFILES</varname>. </para>
@@ -261,6 +255,143 @@
       it in <filename>$LOCALPATCHES/graphics/png/mypatch</filename>. All
       files in the named directory are expected to be patch files, and
       <emphasis>they are applied after pkgsrc patches are applied</emphasis>.</para>
+
+    <sect2 id="components.patches.guidelines">
+      <title>Patching guidelines</title>
+
+      <para>When fixing a portability issue in the code do not use
+      preprocessor magic to check for the current operating system nor
+      platform.  Doing so hurts portability to other platforms because
+      the OS-specific details are not abstracted appropriately.</para>
+      
+      <para>The general rule to follow is: instead of checking for the
+      operating system the application is being built on, check for the
+      specific <emphasis>features</emphasis> you need.  For example,
+      instead of assuming that kqueue is available under NetBSD and
+      using the <varname>__NetBSD__</varname> macro to conditionalize
+      kqueue support, add a check that detects kqueue itself &mdash;
+      yes, this generally involves patching the
+      <command>configure</command> script.  There is absolutely nothing
+      that prevents some OSes from adopting interfaces from other OSes
+      (e.g. Linux implementing kqueue), something that the above checks
+      cannot take into account.</para>
+      
+      <para>Of course, checking for features generally involves more
+      work on the developer's side, but the resulting changes are
+      cleaner and there are chances they will work on many other
+      platforms.  Not to mention that there are higher chances of being
+      later integrated into the mainstream sources.  Remember:
+      <emphasis>It doesn't work unless it is right!</emphasis></para>
+
+      <para>Some typical examples:</para>
+
+      <table id="patch-examples">
+	<title>Patching examples</title>
+
+	<tgroup cols="3">
+	  <thead>
+	    <row>
+	      <entry>Where</entry>
+	      <entry>Incorrect</entry>
+	      <entry>Correct</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+	    <row>
+	      <entry>configure script</entry>
+	      <entry>
+		<programlisting>case ${target_os} in
+      netbsd*) have_kvm=yes ;;
+      *)       have_kvm=no  ;;
+  esac</programlisting>
+	      </entry>
+
+	      <entry>
+		<programlisting>AC_CHECK_LIB(kvm, kvm_open, have_kvm=yes, have_kvm=no)</programlisting>
+	      </entry>
+	    </row>
+
+	    <row>
+	      <entry>C source file</entry>
+	      <entry>
+		<programlisting>#if defined(__NetBSD__)
+  #  include &lt;sys/event.h&gt;
+  #endif</programlisting>
+	      </entry>
+	      <entry>
+		<programlisting>#if defined(HAVE_SYS_EVENT_H)
+  #  include &lt;sys/event.h&gt;
+  #endif</programlisting>
+	      </entry>
+	    </row>
+
+	    <row>
+	      <entry>C source file</entry>
+	      <entry><programlisting>int
+  monitor_file(...)
+  {
+  #if defined(__NetBSD__)
+      int fd = kqueue();
+      ...
+  #else
+      ...
+  #endif
+  }</programlisting>
+	      </entry>
+	      <entry>
+		<programlisting>int
+  monitor_file(...)
+  {
+  #if defined(HAVE_KQUEUE)
+      int fd = kqueue();
+      ...
+  #else
+      ...
+  #endif
+  }</programlisting>
+	      </entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+
+      <para>For more information, please read the <emphasis>Making
+      packager-friendly software</emphasis> article (<ulink
+      url="http://www.onlamp.com/pub/a/onlamp/2005/03/31/packaging.html">part
+      1</ulink>, <ulink
+      url="http://www.oreillynet.com/pub/a/onlamp/2005/04/28/packaging2.html">part
+      2</ulink>).  It summarizes multiple details on how to make
+      software easier to package; all the suggestions in it were
+      collected from our experience in pkgsrc work, so they are possibly
+      helpful when creating patches too.</para>
+
+    </sect2>
+
+    <sect2 id="components.patches.feedback">
+      <title>Feedback to the author</title>
+
+      <para>Always, always, <emphasis role="strong">always</emphasis>
+      feed back any <emphasis>portability fixes</emphasis> or
+      improvements you do to a package to the mainstream developers.
+      This is the only way to get their attention on portability issues
+      and to ensure that future versions can be built out-of-the box on
+      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
+      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
+      <emphasis>extremely important</emphasis> that you do it so that
+      the packages in pkgsrc are kept simple and thus further changes
+      can be done without much hassle.</para>
+
+      <para>Support the idea of free software!</para>
+
+    </sect2>
+
   </sect1>
 
   <sect1 id="other-mandatory-files">