[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
pkgsrc/doc/guide/files/build.xml: 1.11 -> 1.12

Subject: pkgsrc/doc/guide/files/build.xml: 1.11 -> 1.12
From: kano@na.rim.or.jp (OKANO Takayoshi)
To: www-changes-ja@jp.NetBSD.org
Date: Tue, 17 Oct 2006 00:50:08 +0900 (JST)
Message-Id: <200610161550.AAA45196@shell.rim.or.jp>
Delivered-To: mailing list www-changes-ja@jp.netbsd.org
Mailing-List: contact www-changes-ja-help@jp.netbsd.org; run by ezmlm-idx
以下のページの更新をしました。ツッコミをお願いします。

pkgsrc/doc/guide/files/build.xml: 1.11 -> 1.12

> revision 1.12
> date: 2005/11/03 16:43:59;  author: rillig;  state: Exp;  lines: +82 -55
> Wrote an introduction and converted the itemize list of main targets
> into sections. These sections are still very incomplete.

今回追加された部分では、
fetch, checksum, extract, patch, configure, build,... を phase
pre-, do-, post- がついたものを stage
と呼んでいます。

訳語はどーしましょう。
# それぞれ、「相」「期」としましたが、わけがわからん
## 原文の他の部分でも、両者をはっきり区別してるわけではないっぽいです

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

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

--- build.xml.orig	2006-10-17 00:41:41.000000000 +0900
+++ build.xml	2006-10-17 00:41:41.000000000 +0900
@@ -1,9 +1,22 @@
-<!-- $NetBSD: build.xml,v 1.11 2005/10/23 11:25:58 rillig Exp $ -->
+<!-- $NetBSD: build.xml,v 1.12 2005/11/03 16:43:59 rillig Exp $ -->
 <!-- Based on english version: -->
-<!-- NetBSD: build.xml,v 1.11 2005/10/23 11:25:58 rillig Exp   -->
+<!-- NetBSD: build.xml,v 1.12 2005/11/03 16:43:59 rillig Exp   -->
 
 <chapter id="build">
-  <title>構築の手順</title>
+<title>構築の手順</title>
+
+<sect1 id="build.intro">
+<title>序</title>
+
+<para>本章では、パッケージがどのように構築されるかについて、詳しく説明します。
+パッケージの構築は、複数の<emphasis>相 (phase)</emphasis> (たとえば、<varname>fetch</varname>,
+<varname>build</varname>, <varname>install</varname>) にわかれており、
+そのすべてを以下の各節で説明します。それぞれの段階は、<varname>pre-</varname>,
+<varname>do-</varname>, <varname>post-</varname>
+のいずれかが stage 名の前についた、いわゆる<emphasis>期 (stage)</emphasis>
+にわかれます。(たとえば、
+<varname>pre-configure</varname>, <varname>post-build</varname> などです。)
+実際に何かがおこなわれるのは、ほとんどが <varname>do-*</varname> 期においてです。</para>
 
   <para>プログラムを構築するための基本的な手順は常に同じです。最初に、プログラムの
     ソースファイル(<emphasis>distfile</emphasis>)をローカルシステムへ持ってきて展開します。&os;
@@ -13,6 +26,8 @@
     によって実行される手順です。この手順は、中心となるMakefile、
     <filename>pkgsrc/mk/bsd.pkg.mk</filename>の中で一連のターゲットとして実装されています</para>
 
+</sect1>
+
   <sect1 id="build.prefix">
     <title>プログラムの場所</title>
 
@@ -127,16 +142,21 @@
     </itemizedlist>
   </sect1>
 
-  <sect1 id="main-targets">
-    <title>主なターゲット</title>
+<sect1 id="build.running">
+<title>相の実行</title>
 
-    <para><filename>bsd.pkg.mk</filename>で定義された、構築手順で使用される主なターゲットについて述べます。</para>
+<para><command>make phase</command> (<emphasis>phase</emphasis> は相の名前) と打てば、
+その相を実行することができます。
+こうすると、その相のために必要な相をすべて自動的に実行します。
+相を指定しない場合は <varname>build</varname> 相になります。つまり、
+あるパッケージのディレクトリーで、引数なしで <command>make</command>
+を実行すると、パッケージが構築されますが、インストールはされません。</para>
 
-    <variablelist>
-      <varlistentry>
-	<term>fetch</term>
+</sect1>
+
+<sect1 id="build.fetch">
+<title><emphasis>fetch</emphasis> 相</title>
 
-	<listitem>
 	  <para>これは、変数<varname>DISTFILES</varname>と<varname>PATCHFILES</varname> (パッケージのMakefileで定義された)で指
 	    定されたファイルが、ローカルシステムの<filename>/usr/pkgsrc/distfiles</filename>に存在するか
 	    どうかをチェックします。もし、存在しなければ、そのファイルを以下のような
@@ -152,25 +172,23 @@
 	    みます。そして、最後に<varname>MASTER_SITE_BACKUP</varname>の値を試みます。最初のもの以
 	    外の順序は、<varname>MASTER_SORT_AWK</varname>か<varname>MASTER_SORT_REGEX</varname>を設定して、ユーザー
 	    が入れ換えることができます。</para>
-	</listitem>
-      </varlistentry>
 
-      <varlistentry>
-	<term>checksum</term>
+</sect1>
+
+<sect1 id="build.checksum">
+<title><emphasis>checksum</emphasis> 相</title>
 
-	<listitem>
 	  <para>distfileを取得した後に、チェックサムを生成し、distinfoファイルに保存され
 	    たチェックサムと比較します。もし、チェックサムが一致しなければ、構築は中
 	    断されます。これはパッケージ作成時と同じdistfileが、構築に使用されている
 	    こと、つまり、悪意や一次配布サイトでの意図的な差し替えやネットワークの損
 	    失によってdistfileが変更されていないことを保証するためです。</para>
-	</listitem>
-      </varlistentry>
 
-      <varlistentry>
-	<term>extract</term>
+</sect1>
+
+<sect1 id="build.extract">
+<title><emphasis>extract</emphasis> 相</title>
 
-	<listitem>
 	  <para>distfileがローカルシステム上に存在している場合、
 	    通常、それらは圧縮アーカイブフォーマットで保存されているので、
 	    展開する必要があります。もっとも一般なフォーマットは
@@ -208,13 +226,12 @@
     EXTRACT_BEFORE_ARGS=
     EXTRACT_AFTER_ARGS=     |sh
 </programlisting>
-	</listitem>
-      </varlistentry>
 
-      <varlistentry>
-	<term>patch</term>
+</sect1>
+
+<sect1 id="build.patch">
+<title><emphasis>patch</emphasis> 相</title>
 
-	<listitem>
 	  <para>展開の後で、<varname>PATCHFILES</varname>で指定されたパッチとパッケージのpatchesサブディレ
 	    クトリーに存在するパッチ、さらに、$LOCALPATCHES/$PKGPATH (たとえば 
 	    <filename>/usr/local/patches/graphics/png</filename>)に存在するパッチのすべてが適用されます。
@@ -227,13 +244,26 @@
 	    特別な引数が渡されます。パッチを修正(再作成)して、きれいに適用できるよう
 	    にしてください。そうする理由は、曖昧さがあるパッチが一見うまく適用できても、実は誤った場
 	    所に適用されていて、深刻な問題を起こす可能性があるからです。</para>
-	</listitem>
-      </varlistentry>
 
-      <varlistentry>
-	<term>configure</term>
+</sect1>
+
+<sect1 id="build.tools">
+<title><emphasis>tools</emphasis> 相</title>
+
+<para>[TODO]</para>
+
+</sect1>
+
+<sect1 id="build.wrapper">
+<title><emphasis>wrapper</emphasis> 相</title>
+
+<para>[TODO]</para>
+
+</sect1>
+
+<sect1 id="build.configure">
+<title><emphasis>configure</emphasis> 相</title>
 
-	<listitem>
 	  <para>ほとんどのソフトウェアは、&os;で利用できるヘッダーファイル、システムコー
 	    ル、およびライブラリールーチンについての情報を必要とします。これはコンフィ
 	    ギュレーションとして知られているプロセスであり、通常、自動化されています。
@@ -258,13 +288,11 @@
 	    あれば、<varname>USE_IMAKE</varname>を<quote>YES</quote>に設定することにより、適切な手順が実行されます。
 	    (もし、<varname>$X11PREFIX</varname>にインストールされるパッケージが欲しいだけで、xmkmfを実
 	    行したくない場合、かわりに<varname>USE_X11BASE</varname>を使用してください!)</para>
-	</listitem>
-      </varlistentry>
 
-      <varlistentry>
-	<term>build</term>
+</sect1>
 
-	<listitem>
+<sect1 id="build.build">
+<title><emphasis>build</emphasis> 相</title>
 	  <para>コンフィギュレーションが終ったら、<varname>$MAKEFILE</varname>の中で、構築のターゲットとし
 	    て<varname>$BUILD_TARGET</varname>を指定し<varname>$MAKE_PROGRAM</varname>を起動することにより、ソフト
 	    ウェアを構築することができます。もし、<varname>USE_TOOLS</varname> に <quote>gmake</quote> が含まれていれば、デフォ
@@ -272,35 +300,34 @@
 	    <varname>MAKEFILE</varname>にはデフォルトで<quote>Makefile</quote>が設定されます。そして、<varname>BUILD_TARGET</varname>のデフォ
 	    ルトは<quote>all</quote>です。デフォルトの構築手順を変更するために、パッケージの Makefile でこれらの変数を設定
 	    することができます。</para>
-	</listitem>
-      </varlistentry>
 
-      <varlistentry>
-	<term>install</term>
 
-	<listitem>
+</sect1>
+
+<sect1 id="build.test">
+<title><emphasis>test</emphasis> 相</title>
+
+<para>[TODO]</para>
+
+</sect1>
+
+<sect1 id="build.install">
+<title><emphasis>install</emphasis> 相</title>
+
 	  <para>構築の段階が完了すると、ユーザーが構築されたプログラムやファイルを使えるようにするため、ソフトウェアをパブリックなディレ
 	    クトリーにインストールする必要があります。buildターゲットと同様に、
 	    <varname>$MAKE_PROGRAM</varname>が<varname>$MAKEFILE</varname>中で起動されます。ただし、<varname>$INSTALL_TARGET</varname>が指定
 	    されます。この変数のデフォルトは<quote>install</quote>です。(もし<varname>USE_IMAKE</varname>が設定さ
 	    れていれば、<quote>install.man</quote>も追加されます)。</para>
-	</listitem>
-      </varlistentry>
-    </variablelist>
 
-    <para>もし、ターゲットが指定されなければ、デフォルトは<quote>build</quote>です。手順の途中の
-      ターゲットが指定された場合、それ以前のすべての手順が実行されます。例えば
-      <command>make build</command>は、以下と同等のことを実行します。</para>
+</sect1>
 
-<programlisting>
-    make fetch
-    make checksum
-    make extract
-    make patch
-    make configure
-    make build
-</programlisting>
-  </sect1>
+<sect1 id="build.package">
+<title><emphasis>package</emphasis> 相</title>
+
+<para>[TODO]</para>
+
+</sect1>
 
   <sect1 id="build.helpful-targets">
     <title>他の役に立つターゲット</title>
Index: build.xml
===================================================================
RCS file: /cvsroot/pkgsrc/doc/guide/files/build.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- build.xml	23 Oct 2005 11:25:58 -0000	1.11
+++ build.xml	3 Nov 2005 16:43:59 -0000	1.12
@@ -1,7 +1,21 @@
-<!-- $NetBSD: build.xml,v 1.11 2005/10/23 11:25:58 rillig Exp $ -->
+<!-- $NetBSD: build.xml,v 1.12 2005/11/03 16:43:59 rillig Exp $ -->
 
 <chapter id="build">
-  <title>The build process</title>
+<title>The build process</title>
+
+<sect1 id="build.intro">
+<title>Introduction</title>
+
+<para>This chapter gives a detailed description on how a package is
+built. Building a package is separated into different
+<emphasis>phases</emphasis> (for example <varname>fetch</varname>,
+<varname>build</varname>, <varname>install</varname>), all of which are
+described in the following sections. Each phase is splitted into
+so-called <emphasis>stages</emphasis>, which take the name of the
+containing stage, prefixed by one of <varname>pre-</varname>,
+<varname>do-</varname> or <varname>post-</varname>. (Examples are
+<varname>pre-configure</varname>, <varname>post-build</varname>.) Most
+of the actual work is done in the <varname>do-*</varname> stages.</para>
 
   <para>The basic steps for building a program are always the same.  First the
     program's source (<emphasis>distfile</emphasis>) must be brought to the
@@ -12,6 +26,8 @@
     the &os; package system, which is implemented as a series of targets
     in a central Makefile, <filename>pkgsrc/mk/bsd.pkg.mk</filename>.</para>
 
+</sect1>
+
   <sect1 id="build.prefix">
     <title>Program location</title>
 
@@ -132,17 +148,21 @@
     </itemizedlist>
   </sect1>
 
-  <sect1 id="main-targets">
-    <title>Main targets</title>
+<sect1 id="build.running">
+<title>Running a phase</title>
 
-    <para>The main targets used during the build process defined in
-      <filename>bsd.pkg.mk</filename> are:</para>
+<para>You can run a particular phase by typing <command>make
+phase</command>, where <emphasis>phase</emphasis> is the name of the
+phase. This will automatically run all phases that are required for this
+phase. The default phase is <varname>build</varname>, that is, when you
+run <command>make</command> without parameters in a package directory,
+the package will be built, but not installed.</para>
 
-    <variablelist>
-      <varlistentry>
-	<term>fetch</term>
+</sect1>
+
+<sect1 id="build.fetch">
+<title>The <emphasis>fetch</emphasis> phase</title>
 
-	<listitem>
 	  <para>This will check if the file(s) given in the variables
 	    <varname>DISTFILES</varname> and <varname>PATCHFILES</varname> (as
 	    defined in the package's Makefile) are present on the
@@ -163,26 +183,24 @@
 	    first can be optionally sorted by the user, via setting either
 	    <varname>MASTER_SORT_AWK</varname> or
 	    <varname>MASTER_SORT_REGEX</varname>.</para>
-	</listitem>
-      </varlistentry>
 
-      <varlistentry>
-	<term>checksum</term>
+</sect1>
+
+<sect1 id="build.checksum">
+<title>The <emphasis>checksum</emphasis> phase</title>
 
-	<listitem>
 	  <para>After the distfile(s) are fetched, their checksum is generated and
 	    compared with the checksums stored in the distinfo file. If the
 	    checksums don't match, the build is aborted. This is to ensure the same
 	    distfile is used for building, and that the distfile wasn't changed,
 	    e.g. by some malign force, deliberately changed distfiles on the master
 	    distribution site or network lossage.</para>
-	</listitem>
-      </varlistentry>
 
-      <varlistentry>
-	<term>extract</term>
+</sect1>
+
+<sect1 id="build.extract">
+<title>The <emphasis>extract</emphasis> phase</title>
 
-	<listitem>
 	  <para>When the distfiles are present on the local system,
 	    they need to be extracted, as they are usually in the form
 	    of some compressed archive format, most commonly
@@ -220,13 +238,12 @@
     EXTRACT_BEFORE_ARGS=
     EXTRACT_AFTER_ARGS=     |sh
 </programlisting>
-	</listitem>
-      </varlistentry>
 
-      <varlistentry>
-	<term>patch</term>
+</sect1>
+
+<sect1 id="build.patch">
+<title>The <emphasis>patch</emphasis> phase</title>
 
-	<listitem>
 	  <para>After extraction, all the patches named by the
 	    <varname>PATCHFILES</varname>, those present in the patches
 	    subdirectory of the package as well as in $LOCALPATCHES/$PKGPATH (e.g.
@@ -243,13 +260,26 @@
 	    so that they apply cleanly. The rationale behind this is that
 	    patches that don't apply cleanly may end up being applied in the wrong
 	    place, and cause severe harm there.</para>
-	</listitem>
-      </varlistentry>
 
-      <varlistentry>
-	<term>configure</term>
+</sect1>
+
+<sect1 id="build.tools">
+<title>The <emphasis>tools</emphasis> phase</title>
+
+<para>[TODO]</para>
+
+</sect1>
+
+<sect1 id="build.wrapper">
+<title>The <emphasis>wrapper</emphasis> phase</title>
+
+<para>[TODO]</para>
+
+</sect1>
+
+<sect1 id="build.configure">
+<title>The <emphasis>configure</emphasis> phase</title>
 
-	<listitem>
 	  <para>Most pieces of software need information on the header files,
 	    system calls, and library routines which are available in &os;.
 	    This is the process known as configuration, and is usually
@@ -280,13 +310,12 @@
 	    <quote>YES</quote>. (If you only want the package installed in
 	    <varname>$X11PREFIX</varname> but xmkmf not being run, set
 	    <varname>USE_X11BASE</varname> instead!)</para>
-	</listitem>
-      </varlistentry>
 
-      <varlistentry>
-	<term>build</term>
+</sect1>
+
+<sect1 id="build.build">
+<title>The <emphasis>build</emphasis> phase</title>
 
-	<listitem>
 	  <para>Once configuration has taken place, the software will be built 
 	    by invoking <varname>$MAKE_PROGRAM</varname> on
 	    <varname>$MAKEFILE</varname> with <varname>$BUILD_TARGET</varname> as
@@ -297,13 +326,19 @@
 	    defaults to <quote>all</quote>.  Any of these variables
 	    can be set in the package's Makefile to change the default
 	    build process.</para> 
-	</listitem>
-      </varlistentry>
 
-      <varlistentry>
-	<term>install</term>
+</sect1>
+
+<sect1 id="build.test">
+<title>The <emphasis>test</emphasis> phase</title>
+
+<para>[TODO]</para>
+
+</sect1>
+
+<sect1 id="build.install">
+<title>The <emphasis>install</emphasis> phase</title>
 
-	<listitem>
 	  <para>Once the build stage has completed, the final step is to install
 	    the software in public directories, so users can access
 	    the programs and files.  As in the
@@ -312,23 +347,15 @@
 	    <varname>$INSTALL_TARGET</varname> instead, the latter defaulting to
 	    <quote>install</quote> (plus <quote>install.man</quote>, if
 	    <varname>USE_IMAKE</varname> is set).</para>
-	</listitem>
-      </varlistentry>
-    </variablelist>
 
-    <para>If no target is specified, the default is <quote>build</quote>.
-      If a subsequent stage is requested, all prior stages are made: e.g.
-      <command>make build</command> will also perform the equivalent of:</para>
+</sect1>
 
-<programlisting>
-    make fetch
-    make checksum
-    make extract
-    make patch
-    make configure
-    make build
-</programlisting>
-  </sect1>
+<sect1 id="build.package">
+<title>The <emphasis>package</emphasis> phase</title>
+
+<para>[TODO]</para>
+
+</sect1>
 
   <sect1 id="build.helpful-targets">
     <title>Other helpful targets</title>
Prev by Date: CVS commit: htdocs
Next by Date: pkgsrc/doc/guide/files/platforms.xml: 1.15 -> 1.22
Prev by thread: Documentation/network/pf.xml: 1.5 -> 1.6
Next by thread: pkgsrc/doc/guide/files/platforms.xml: 1.15 -> 1.22
Index(es):
- Date
- Thread