[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
pkgsrc/doc/guide/files/fixes.xml: 1.61 -> 1.63
以下のページの更新をしました。ツッコミをお願いします。
pkgsrc/doc/guide/files/fixes.xml: 1.61 -> 1.63
> revision 1.63
> date: 2006/07/02 10:01:11; author: rillig; state: Exp; lines: +2 -2
> Added a missing word.
> ----------------------------
> revision 1.62
> date: 2006/07/01 23:48:16; author: rillig; state: Exp; lines: +70 -3
> Added documentation for the SUBST framework.
木曜日までに異議がなければ、 commit します。
以下、訳と原文それぞれの新旧の差分です。
--- fixes.xml.orig 2006-12-06 07:19:41.000000000 +0900
+++ fixes.xml 2006-12-06 07:19:41.000000000 +0900
@@ -1,6 +1,6 @@
-<!-- $NetBSD: fixes.xml,v 1.61 2006/07/01 12:51:30 rillig Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.63 2006/07/02 10:01:11 rillig Exp $ -->
<!-- Based on english version: -->
-<!-- NetBSD: fixes.xml,v 1.61 2006/07/01 12:51:30 rillig Exp -->
+<!-- NetBSD: fixes.xml,v 1.63 2006/07/02 10:01:11 rillig Exp -->
<chapter id="fixes"> <?dbhtml filename="fixes.html"?>
<title>パッケージを動くようにする</title>
@@ -47,7 +47,7 @@
</sect2>
<sect2 id="user-interaction">
- <title>パッケージ構築時のユーザーとの対話</title>
+ <title>ユーザーとの対話</title>
<para>時々、パッケージがユーザーとの対話を必要とする場合がありますが、そのような
状況は何通りもありえます:</para>
@@ -531,9 +531,75 @@
<para>依存するパッケージの ABI が変更された場合にも、
PKGREVISION を上げる必要があります。</para>
</sect2>
- </sect1>
+<sect2 id="fixes.subst">
+<title>パッケージのファイル中の各種テキストを置換する (SUBST の枠組)</title>
+
+ <para>複数のファイルに含まれる同じテキストを置換したい場合や、
+ テキストの置換方法を変化させたい場合には、パッチだけでは実現できません。
+ そこで SUBST の枠組の出番です。この枠組では、
+ ファイル内のテキストを置換するために簡単に使えるインターフェースを用意しています。
+ たとえば以下のように使います。</para>
+
+<programlisting>
+ SUBST_CLASSES+= fix-paths
+ SUBST_STAGE.fix-paths= pre-configure
+ SUBST_MESSAGE.fix-paths= Fixing absolute paths.
+ SUBST_FILES.fix-paths= src/*.c
+ SUBST_FILES.fix-paths+= scripts/*.sh
+ SUBST_SED.fix-paths= -e 's,"/usr/local,"${PREFIX},g'
+ SUBST_SED.fix-paths+= -e 's,"/var/log,"${VARBASE}/log,g'
+</programlisting>
+
+ <para><varname>SUBST_CLASSES</varname> は、ここで定義する
+ SUBST の塊を区別するための識別子を並べたリストです。
+ SUBST の枠組は pkgsrc で多用されているので、この変数には常に
+ <literal>+=</literal> 演算子を使うことが重要です。
+ そうしないと、一部の置換がおこなわれなくなることがあります。</para>
+
+ <para>各 SUBST の塊の残りの変数は、
+ 最初の行の識別子 (この例では <literal>fix-paths</literal>)
+ を使ってパラメーター化されています。
+ これらは、関数呼び出しの引数とみなすことができます。</para>
+
+ <para><varname>SUBST_STAGE.*</varname> は、
+ この置換をどの期におこなうかを指定します。
+ 実際に使われるものは限られていますが、相の名前と
+ <literal>pre-</literal>, <literal>do-</literal>,
+ <literal>post-</literal> のあらゆる組合せを使うことができます。
+ もっともよく使われるのは <literal>post-patch</literal> と
+ <literal>pre-configure</literal> です。このふたつのうち、
+ <literal>pre-configure</literal> を使うと、
+ <command>bmake patch</command> を実行することで、
+ パッチを適用したほかは一切変更されていない状態にすることができるため、
+ こちらのほうが好まれます。このことは、
+ 新しいパッチを作成するためにパッケージのデバッグをする際に、
+ 特に便利です。これと同様に、<literal>pre-install</literal>
+ よりも <literal>post-build</literal> のほうが好まれます。
+ これは、一般的に install 相は極力簡素なものにするほうがよいからです。
+ <literal>post-build</literal> を使った場合、
+ 後にインストールされるものと同じファイルが作業ディレクトリーにできあがるので、
+ 正しく置換がおこなわれたかを確認することができます。</para>
+
+ <para><varname>SUBST_MESSAGE.*</varname> は、
+ 置換がおこなわれる直前に表示するテキストで、省略可能です。</para>
+
+ <para><varname>SUBST_FILES.*</varname> は、置換の対象となるファイルを、
+ シェルのグロブパターンで指定したものを並べたリストです。
+ このパターンは、<varname>WRKSRC</varname>
+ ディレクトリーからの相対位置として解釈されます。</para>
+
+ <para><varname>SUBST_SED.*</varname> は置換の内容を
+ &man.sed.1; への引数の形で指定したものを並べたリストです。
+ 各 sed コマンドの前には <literal>-e</literal> をつけて、
+ SUBST の塊全体が一様に見えるようにします。</para>
+
+ <para>以上のほかにも変数がいくつかありますが、
+ それらはほとんど使われないものなので、
+ <filename>mk/subst.mk</filename> ファイル内でのみ文書化されています。</para>
+</sect2>
+</sect1>
<sect1 id="fixes.fetch">
<title><emphasis>fetch</emphasis> 相での問題を修正する</title>
Index: fixes.xml
===================================================================
RCS file: /cvsroot/pkgsrc/doc/guide/files/fixes.xml,v
retrieving revision 1.61
retrieving revision 1.63
diff -u -r1.61 -r1.63
--- fixes.xml 1 Jul 2006 12:51:30 -0000 1.61
+++ fixes.xml 2 Jul 2006 10:01:11 -0000 1.63
@@ -1,4 +1,4 @@
-<!-- $NetBSD: fixes.xml,v 1.61 2006/07/01 12:51:30 rillig Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.63 2006/07/02 10:01:11 rillig Exp $ -->
<chapter id="fixes"> <?dbhtml filename="fixes.html"?>
<title>Making your package work</title>
@@ -46,7 +46,7 @@
</sect2>
<sect2 id="user-interaction">
- <title>User interaction when building the package</title>
+ <title>User interaction</title>
<para>Occasionally, packages require interaction from the user, and this can be
in a number of ways:</para>
@@ -559,9 +559,76 @@
<para>PKGREVISION must also be incremented when dependencies have ABI
changes.</para>
</sect2>
- </sect1>
+<sect2 id="fixes.subst">
+<title>Substituting variable text in the package files (the SUBST framework)</title>
+
+ <para>When you want to replace the same text in multiple files
+ or when the replacement text varies, patches alone cannot help.
+ This is where the SUBST framework comes in. It provides an
+ easy-to-use interface for replacing text in files.
+ Example:</para>
+
+<programlisting>
+ SUBST_CLASSES+= fix-paths
+ SUBST_STAGE.fix-paths= pre-configure
+ SUBST_MESSAGE.fix-paths= Fixing absolute paths.
+ SUBST_FILES.fix-paths= src/*.c
+ SUBST_FILES.fix-paths+= scripts/*.sh
+ SUBST_SED.fix-paths= -e 's,"/usr/local,"${PREFIX},g'
+ SUBST_SED.fix-paths+= -e 's,"/var/log,"${VARBASE}/log,g'
+</programlisting>
+
+ <para><varname>SUBST_CLASSES</varname> is a list of identifiers
+ that are used to identify the different SUBST blocks that are
+ defined. The SUBST framework is heavily used by pkgsrc, so it is
+ important to always use the <literal>+=</literal> operator with
+ this variable. Otherwise some substitutions may be
+ skipped.</para>
+
+ <para>The remaining variables of each SUBST block are
+ parameterized with the identifier from the first line
+ (<literal>fix-paths</literal> in this case.) They can be seen as
+ parameters to a function call.</para>
+
+ <para><varname>SUBST_STAGE.*</varname> specifies the stage at
+ which the replacement will take place. All combinations of
+ <literal>pre-</literal>, <literal>do-</literal> and
+ <literal>post-</literal> together with a phase name are
+ possible, though only few are actually used. Most commonly used
+ are <literal>post-patch</literal> and
+ <literal>pre-configure</literal>. Of these two,
+ <literal>pre-configure</literal> should be preferred because
+ then it is possible to run <command>bmake patch</command> and
+ have the state after applying the patches but before making any
+ other changes. This is especially useful when you are debugging
+ a package in order to create new patches for it. Similarly,
+ <literal>post-build</literal> is preferred over
+ <literal>pre-install</literal>, because the install phase should
+ generally be kept as simple as possible. When you use
+ <literal>post-build</literal>, you have the same files in the
+ working directory that will be installed later, so you can check
+ if the substitution has succeeded.</para>
+
+ <para><varname>SUBST_MESSAGE.*</varname> is an optional text
+ that is printed just before the substitution is done.</para>
+
+ <para><varname>SUBST_FILES.*</varname> is the list of shell
+ globbing patterns that specifies the files in which the
+ substitution will take place. The patterns are interpreted
+ relatively to the <varname>WRKSRC</varname> directory.</para>
+
+ <para><varname>SUBST_SED.*</varname> is a list of arguments to
+ &man.sed.1; that specify the actual substitution. Every sed
+ command should be prefixed with <literal>-e</literal>, so that
+ all SUBST blocks look uniform.</para>
+
+ <para>There are some more variables, but they are so seldomly
+ used that they are only documented in the
+ <filename>mk/subst.mk</filename> file.</para>
+</sect2>
+</sect1>
<sect1 id="fixes.fetch">
<title>Fixing problems in the <emphasis>fetch</emphasis> phase</title>