LaTex用に更新.

[omake-japanese/omake_trans.git] / rules.rst

.. 8-rules

.. index::
   single: $*
   single: $@
   single: $^
   single: $+
   single: $<
.. _label8:

ビルドルール
==================================
.. Rules are used by OMake to specify how to build files. At its simplest, a rule has the following form.

OMakeで使われているルールは、どのようにしてファイルをビルドするのかについて指定しています。最も簡単な例は以下のような形です。 ::

    <target>: <dependencies>
        <commands>

.. The <target> is the name of a file to be built. The <dependencies> are a list of files that are needed before the <target> can be built. The <commands> are a list of indented lines specifying commands to build the target. For example, the following rule specifies how to compile a file hello.c.

``<target>`` ではビルドするファイル名を記述します。 ``<dependencies>`` では ``<target>`` をビルドする前に必要なファイルのリストを記述します。 ``<commands>`` はターゲットをビルドするためのコマンドを、インデントした状態で記述します。例えば、以下のルールではどのようにファイル ``hello.c`` をコンパイルするのかについて指定しています。 ::

    hello.o: hello.c
        $(CC) $(CFLAGS) -c -o hello.o hello.c

.. This rule states that the hello.o file depends on the hello.c file. If the hello.c file has changed, the command $(CC) $(CFLAGS) -c -o hello.o hello.c is to be executed to update the target file hello.o.

このルールでは、 ``hello.o`` ファイルは ``hello.c`` ファイルに依存しています。 ``hello.c`` ファイルが変更された場合、コマンド ``$(CC) $(CFLAGS) -c -o hello.o hello.c`` が実行されて、ターゲットファイル ``hello.o`` は更新されます。

.. A rule can have an arbitrary number of commands. The individual command lines are executed independently by the command shell. The commands do not have to begin with a tab, but they must be indented from the dependency line.

ルールの中には任意の数のコマンドを含めることができます。各々の独立したコマンドラインはコマンドシェルによって、独立した状態で実行されます。コマンドの最初にタブを含めることはできません。しかし、依存関係を指定している行からはインデントされなければなりません。

.. In addition to normal variables, the following special variables may be used in the body of a rule.
      * $*: the target name, without a suffix.
      * $@: the target name.
      * $^: a list of the sources, in alphabetical order, with duplicates removed.
      * $+: all the sources, in the original order.
      * $<: the first source. 

通常の変数に加えて、以下の特殊変数をルールの内容で使うことができます。

* ``$*`` : 拡張子を除いたターゲットの名前
* ``$@`` : ターゲットの名前
* ``$^`` : 依存ファイルのリストをアルファベット順に並べ、かつ重複した内容を削除したもの
* ``$+`` : 元の順番で並んでいる依存ファイルのリスト
* ``$<`` : 最初の依存ファイル

.. For example, the above hello.c rule may be simplified as follows.

例えば、上の ``hello.c`` ルールは以下のように簡略化されます。 ::

    hello.o: hello.c
        $(CC) $(CFLAGS) -c -o $@ $<

.. Unlike normal values, the variables in a rule body are expanded lazily, and binding is dynamic. The following function definition illustrates some of the issues.

通常の値とは異なり、ルール中の変数は遅延評価されて、かつ動的なスコーピングが行われます。以下の関数定義はこの性質のいくつかを端的に表しています。 ::

    CLibrary(name, files) =
        OFILES = $(addsuffix .o, $(files))

        $(name).a: $(OFILES)
            $(AR) cq $@ $(OFILES)

.. This function defines a rule to build a program called $(name) from a list of .o files. The files in the argument are specified without a suffix, so the first line of the function definition defines a variable OFILES that adds the .o suffix to each of the file names. The next step defines a rule to build a target library $(name).a from the $(OFILES) files. The expression $(AR) is evaluated when the function is called, and the value of the variable AR is taken from the caller's scope (see also the section on Scoping).

この関数は ``.o`` ファイルのリストから ``$(name)`` という名前のプログラムをビルドしています。引数のファイルは拡張子なしで指定されているので、まず最初の定義では各々のファイル名に拡張子 ``.o`` を加えた配列を、変数 ``OFILES`` に束縛しています。次のステップでは ``$(OFILES)`` からターゲットライブラリ ``$(name).a`` をビルドするためのルールを定義しています。 ``$(AR)`` は関数が呼び出されて、呼び出してるスコープから変数 ``AR`` が与えられた時点で評価されます(詳細はスコーピングのセクションを参照してください)。

.. index::
   single: ワイルドカード
.. _label8.1:

暗黙のルール
----------------------------------
.. Rules may also be implicit. That is, the files may be specified by wildcard patterns. The wildcard character is %. For example, the following rule specifies a default rule for building .o files.

ルールはまた暗黙的にすることもできます。これは、ファイルがワイルドカードパターンによって指定されることを示しています。ワイルドカードとしてOMakeでは ``%`` を使用します。例えば、以下のルールでは ``.o`` ファイルをビルドするための通常のルールを指定しています。 ::

    %.o: %.c
        $(CC) $(CFLAGS) -c -o $@ $*.c

.. This rule is a template for building an arbitrary .o file from a .c file.

このルールは任意の ``.c`` ファイルから ``.o`` ファイルをビルドするためのテンプレートとなっています。

.. By default, implicit rules are only used for the targets in the current directory. However subdirectories included via the .SUBDIRS rules inherit all the implicit rules that are in scope (see also the section on Scoping).

通常、暗黙のルールはカレントディレクトリ中のターゲットのみに用いられます。しかしながら、 ``.SUBDIRS`` ルールを経由したものも含むサブディレクトリには、スコープ中にある暗黙のルールがすべて継承されます(詳細はスコーピングのセクションを参照してください)。

.. _label8.2:

束縛された暗黙のルール
----------------------------------
.. Implicit rules may specify the set of files they apply to. The following syntax is used.

暗黙のルールのターゲットにはいくつかのファイルを指定することもできます。そのためには以下のような構文を用います。 ::

    <targets>: <pattern>: <dependencies>
        <commands>

.. For example, the following rule applies only to the files a.o and b.o.

例えば、以下のルールではファイル ``a.o`` と ``b.o`` のみにルールを適用しています。 ::

   a.o b.o: %.o: %.c
        $(CC) $(CFLAGS) -DSPECIAL -c $*.c

.. index::
   single: section
.. _label8.3:

section
----------------------------------
.. Frequently, the commands in a rule body are expressions to be evaluated by the shell. omake also allows expressions to be evaluated by omake itself.

ルールの内容に書かれているコマンドはシェルによって頻繁に評価されます。omakeはまた、omake自身も評価の対象に加えることもできます。

.. The syntax of these “computed rules” uses the section expression. The following rule uses the omake IO functions to produce the target hello.c.

これらの『ファイルを作るためのルール』を表現するためには ``section`` 表現を使います。以下のルールではターゲットの ``hello.c`` を生成するためにomakeのIO関数を用いています。 ::

    hello.c:
        section
            FP = fopen(hello.c, w)
            fprintln($(FP), $""#include <stdio.h> int main() { printf("Hello world\n"); }"")
            close($(FP))

.. This example uses the quotation $""..."" (see also Section B.1.6) to quote the text being printed. These quotes are not included in the output file. The fopen, fprintln, and close functions perform file IO as discussed in the IO section.

この例では出力するテキストをクオートするために、クオーテーション ``$""...""`` を用いています(詳細はB.1.6のセクションを参照してください)。これらのクオートは出力されたファイルには含まれていません。 ``fopen`` , ``fprintln`` , ``close`` 関数はIOセクションで評価するようにファイルのIOを実行します。

.. In addition, commands that are function calls, or special expressions, are interpreted correctly. Since the fprintln function can take a file directly, the above rule can be abbreviated as follows.

加えて、関数の呼び出しや他の特殊なコマンドはその場で正しく評価されます。また、 ``fprintln`` 関数はファイルを直接出力することもできるので、上のルールは下のような形に省略できます。 ::

    hello.c:
       fprintln($@, $""#include <stdio.h> int main() { printf("Hello world\n"); }"")

.. index::
   single: section rule
.. _label8.4:

section rule
----------------------------------
.. Rules can also be computed using the section rule form, where a rule body is expected instead of an expression. In the following rule, the file a.c is copied onto the hello.c file if it exists, otherwise hello.c is created from the file default.c.

また、ターゲットの依存関係がルールの内容で記述されるような場合、 ``section rule`` を使うことで計算することができます。以下のルールでは、ファイル ``a.c`` が存在していた場合は内容を ``hello.c`` にコピーし、そうでなければ ``hello.c`` は ``default.c`` から生成されます。 ::

    hello.c:
        section rule
           if $(target-exists a.c)
              hello.c: a.c
                 cat a.c > hello.c
           else
              hello.c: default.c
                 cp default.c hello.c

.. _label8.5:

特別な依存関係
----------------------------------

.. index::
   single: :exists:
.. _label8.5.1:

\:exists:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. In some cases, the contents of a dependency do not matter, only whether the file exists or not. In this case, the :exists: qualifier can be used for the dependency.

時々、依存しているファイルの内容ではなく、ファイルが存在しているのかどうかが重要となる場合もあるでしょう。 ``:exists:`` 修飾子はこのような依存関係を指定したい場合に用いられます。 ::

    foo.c: a.c :exists: .flag
       if $(test -e .flag)
           $(CP) a.c $@

.. index::
   single: :effects:
.. _label8.5.2:

\:effects:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. Some commands produce files by side-effect. For example, the latex(1) command produces a .aux file as a side-effect of producing a .dvi file. In this case, the :effects: qualifier can be used to list the side-effect explicitly. omake is careful to avoid simultaneously running programs that have overlapping side-effects.

コマンドの中には副産物として別のファイルを生み出すものもあるでしょう。例えば、 ``latex(1)`` コマンドは ``.dvi`` ファイルを生成する際、副産物として ``.aux`` ファイルを生成します。このような場合、 ``:effects:`` 修飾子はこのような副産物のファイルを明示的に指定したい場合に用いられます。omakeはこのファイルを上書きしないように、平行してプログラムを実行させないようにします。 ::

    paper.dvi: paper.tex :effects: paper.aux
        latex paper

.. index::
   single: :value:
.. _label8.5.3:

\:value:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. The :value: dependency is used to specify that the rule execution depends on the value of an expression. For example, the following rule

``:value:`` 依存関係は、ルールの実行がある式の値に依存していることを指定するために用いられます。例えば、以下のルールを見てください。 ::

    a: b c :value: $(X)
        ...

.. specifies that “a” should be recompiled if the value of $(X) changes (X does not have to be a filename). This is intended to allow greater control over dependencies.

上のルールでは、"a"が ``$(X)`` の値が変わった場合に再コンパイルされる必要があることを指定しています(Xがファイル名である必要はありません)。これはファイルや変数の依存関係をより精密にコントロールすることを意図しています。

.. In addition, it can be used instead of other kinds of dependencies. For example, the following rule:

加えて、これは他の依存関係の代わりに用いることができます。例えば、以下のルールは、その次のルールと等価です。 ::

    a: b :exists: c
        commands

::

    a: b :value: $(target-exists c)
        commands

.. Notes:
      * The values are arbitrary (they are not limited to variables)
      * The values are evaluated at rule expansion time, so expressions containing variables like $@, $^, etc are legal. 

.. note::
  * 任意の値をとることができます（指定する変数に制限はありません）。
  * 値はルールが展開されるときに評価されます。なので式には ``$@`` や ``#^`` のような変数も含めることができます。

.. index::
   single: .SCANNER
   single: digest()
   single: digest-in-path-optional()
.. _label8.6:

.SCANNER ルール
----------------------------------
.. Scanner rules define a way to specify automatic dependency scanning. A .SCANNER rule has the following form.

スキャナルールでは、自動的に依存関係の解析を行う方法について定義します。 ``.SCANNER`` ルールは以下のような形となります。 ::

    .SCANNER: target: dependencies
        commands

.. The rule is used to compute additional dependencies that might be defined in the source files for the specified target. The result of executing the scanner commands must be a sequence of dependencies in OMake format, printed to the standard output. For example, on GNU systems the gcc -MM foo.c produces dependencies for the file foo.c (based on #include information).

ルールは、指定されたターゲットのソースファイルに定義されている、追加の依存関係を計算するのに用いられます。 ``.SCANNER`` コマンドの実行結果は、OMakeのフォーマットで依存関係のシーケンスが標準の出力先に出力される必要があります。例えばGNUシステムでは、 ``gcc -MM foo.c`` はファイル ``foo.c`` の依存関係を生成するコマンドです(これは ``#include`` の情報を元にしています)。

.. We can use this to specify a scanner for C files that adds the scanned dependencies for the .o file. The following scanner specifies that dependencies for a file, say foo.o can be computed by running gcc -MM foo.c. Furthermore, foo.c is a dependency, so the scanner should be recomputed whenever the foo.c file changes.

私たちはこれを用いて、 ``.c`` ファイルから ``.o`` ファイルを生成するため、スキャンされた依存関係を既存の依存関係に追加することができます。以下のスキャナではファイルの依存関係を指定しており、仮に ``foo.o`` が指定されたとすると、 ``gcc -MM foo.c`` を実行することによって依存関係の解析が行われます。さらには、 ``foo.c`` は依存されているので、 ``foo.c`` が変更された場合はいつでもスキャナは再計算されます。 ::

    .SCANNER: %.o: %.c
        gcc -MM $<

.. Let's suppose that the command gcc -MM foo.c prints the following line.

コマンド ``gcc -MM foo.c`` は以下の行を出力するものとします。 ::

    foo.o: foo.h /usr/include/stdio.h

.. The result is that the files foo.h and /usr/include/stdio.h are considered to be dependencies of foo.o—that is, foo.o should be rebuilt if either of these files changes.

以上から、ファイル ``foo.h`` と ``/usr/include/stdio.h`` は ``foo.o`` に依存しているものと考えられます。これは、もしこれらのファイルのどれか一つが変更された場合、 ``foo.o`` はリビルドされるべきであることを示しています。

.. This works, to an extent. One nice feature is that the scanner will be re-run whenever the foo.c file changes. However, one problem is that dependencies in C are recursive. That is, if the file foo.h is modified, it might include other files, establishing further dependencies. What we need is to re-run the scanner if foo.h changes too.

これはある程度ですがうまく動きます。この機能の利点の一つとしては、 ``foo.c`` が変更された場合、いつでもスキャナが再解析を行ってくれるというのが挙げられます。しかしながらこれには問題があります。Cの依存関係は *再帰的* なのです。すなわち、もしファイル ``foo.h`` が修正されたとしたら、そのファイルは他のファイルを含んでいることで、さらなる依存関係が生じているのかもしれません。必要なのは ``foo.h`` の変更に応じて、再びスキャナを実行することです。

.. We can do this with a value dependency. The variable $& is defined as the dependency results from any previous scan. We can add these as dependencies using the digest function, which computes an MD5 digest of the files.

私たちはこの問題を『依存関係を示す値(value dependency)』を用いて解決しました。変数 ``$&`` は任意の前回のスキャンから、依存関係の結果を返す変数として定義されています。私たちはこれらの依存関係を、ファイルのMD5による要約を計算して返す ``digest`` 関数を用いて追加しました。 ::

    .SCANNER: %.o: %.c :value: $(digest $&)
        gcc -MM $<

.. Now, when the file foo.h changes, its digest will also change, and the scanner will be re-run because of the value dependency (since $& will include foo.h).

これで、ファイル ``foo.h`` が変更されたときには要約も変更されているのでスキャナは再計算されます。これは依存関係を示す値( ``$&`` には ``foo.h`` がインクルードされています)によるものです。

.. This still is not quite right. The problem is that the C compiler uses a search-path for include files. There may be several versions of the file foo.h, and the one that is chosen depends on the include path. What we need is to base the dependencies on the search path.

ですが、これはまだ完全に正しいというわけではありません。Cコンパイラはインクルードファイルのために *検索パス(search-path)* を使用しているのです。ファイル ``foo.h`` には何通りものバージョンが存在しており、そのうちの選んでいる一つがインクルードパスに依存しているのかもしれません。必要なのは検索パスの依存関係も含めることです。

.. The $(digest-in-path-optional ...) function computes the digest based on a search path, giving us a solution that works.

``$(digest-in-path-optional ...)`` 関数は検索パスを元にした要約を計算し、この問題に解決案を提示します。 ::

    .SCANNER: %.o: %.c :value: $(digest-in-path-optional $(INCLUDES), $&)
       gcc -MM $(addprefix -I, $(INCLUDES)) $<

.. The standard output of the scanner rules will be captured by OMake and is not allowed to contain any content that OMake will not be able to parse as a dependency. The output is allowed to contain dependency specifications for unrelated targets, however such dependencies will be ignored. The scanner rules are allowed to produce arbitrary output on the standard error channel — such output will be handled in the same way as the output of the ordinary rules (in other words, it will be presented to the user, when dictated by the --output-… options enabled).

スキャナルールの標準出力はOMakeによって捉えられるので、OMakeが依存関係を解析できない内容を含むことは許されません。まだ関連付けられていない依存関係について出力することは許されますが、このような依存関係は無視されます。スキャナルールでは標準エラーの出力先に任意の内容を出力することが許されています。このような出力は通常のルールの出力と同様に扱われます。(言い換えれば、これは --output-… オプションを有効にすることで、ユーザーに見せることのできる出力です。)

.. Additional examples of the .SCANNER rules can be found in Section 3.4.3.

``.SCANNER`` ルールについての追加例は ":ref:`label3.4.3`" で見つけることができます。

.. index::
   single: :scanner:
.. _label8.6.1:

スキャナの命名と :scanner: 依存関係
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. Sometimes it may be useful to specify explicitly which scanner should be used in a rule. For example, we might compile .c files with different options, or (heaven help us) we may be using both gcc and the Microsoft Visual C++ compiler cl. In general, the target of a .SCANNER is not tied to a particular target, and we may name it as we like.

スキャナがルール中で使われていることを明示的に指定するほうが有用である場合があります。例えば、私たちは ``.c`` ファイルを異なったオプションでコンパイルしたり、あるいは(天よ我らを助けて!) ``gcc`` と Microsoft Visual C++ コンパイラ ``cl`` の両方を使いたいとしましょう。通常、 ``.SCANNER`` のターゲットは特定のターゲットに結びついていないのですが、私たちはこれを好きなように命名することができます。 ::

    .SCANNER: scan-gcc-%.c: %.c :value: $(digest-in-path-optional $(INCLUDES), $&)
        gcc -MM $(addprefix -I, $(INCLUDES)) $<

    .SCANNER: scan-cl-%.c: %.c :value: $(digest-in-path-optional $(INCLUDES), $&)
        cl --scan-dependencies-or-something $(addprefix /I, $(INCLUDES)) $<

.. The next step is to define explicit scanner dependencies. The :scanner: dependency is used for this. In this case, the scanner dependencies are specified explicitly.

次のステップはスキャナの依存関係を明示的に定義することです。 ``:scanner:`` 依存関係はこのために用いられます。この場合、スキャナの依存関係は明示的に指定されます。 ::

    $(GCC_FILES): %.o: %.c :scanner: scan-gcc-%c
        gcc ...

    $(CL_FILES): %.obj: %.c :scanner: scan-cl-%c
        cl ...

.. Explicit :scanner: scanner specification may also be used to state that a single .SCANNER rule should be used to generate dependencies for more than one target. For example,

明示的な ``:scanner:`` スキャナの指定は、単体の ``.SCANNER`` ルールを複数のターゲットに向けて依存関係を生成することにも用いられます。例えば以下の例を見てみましょう。 ::

    .SCANNER: scan-all-c: $(GCC_FILES) :value: $(digest-in-path-optional $(INCLUDES), $&)
        gcc -MM $(addprefix -I, $(INCLUDES)) $(GCC_FILES)

    $(GCC_FILES): %.o: %.c :scanner: scan-all-c
        ...

.. The above has the advantage of only running gcc once and a disadvantage that when a single source file changes, all the files will end up being re-scanned.

上の例はgccが一回だけ呼び出されるという利点と、一つのソースファイルが変更された場合、すべてのファイルが再スキャンされてしまうという欠点の両方を持ち合わせています。

.. index::
   single: SCANNER_MODE
.. _label8.6.2:

ノート
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. In most cases, you won't need to define scanners of your own. The standard installation includes default scanners (both explicitly and implicitly named ones) for C, OCaml, and LATEX files.

多くの場合において、あなたは自分の手でスキャナを定義する必要はありません。OMakeにはC, OCaml, LaTeXファイルのためのスキャナ(しかも暗黙的、明示的に命名されたスキャナの両方)が標準で用意されています。

.. The SCANNER_MODE variable controls the usage of implicit scanner dependencies.

``SCANNER_MODE`` 変数は、暗黙のスキャナの依存関係の使用についてコントロールする変数です。

.. The explicit :scanner: dependencies reduce the chances of scanner mis-specifications. In large complicated projects it might be a good idea to set SCANNER_MODE to error and use only the named .SCANNER rules and explicit :scanner: specifications.

明示的に ``:scanner:`` 依存関係を指定することは、スキャナが間違って指定してしまう危険を減らします。巨大で複雑なプロジェクトでは ``SCANNER_MODE`` を ``error`` に設定することで、名前がある ``.SCANNER`` ルールと明示的な ``:scanner:`` 指定を使うようにしましょう。

.. index::
   single: .DEFAULT
.. _label8.7:

.DEFAULT
----------------------------------
.. The .DEFAULT target specifies a target to be built by default if omake is run without explicit targets. The following rule instructs omake to build the program hello by default

``.DEFAULT`` ターゲットは、omakeが明示的にターゲットを指定していないようなデフォルトの状態でビルドされるターゲットを指定するために用いられます。以下のルールでは ``hello`` プログラムがデフォルトの状態でビルドすることを指定しています。 ::

   .DEFAULT: hello

.. index::
   single: .SUBDIRS
.. _label8.8:

.SUBDIRS
----------------------------------
.. The .SUBDIRS target is used to specify a set of subdirectories that are part of the project. Each subdirectory should have its own OMakefile, which is evaluated in the context of the current environment.

``.SUBDIRS`` ターゲットはプロジェクトの一部であるサブディレクトリの集合を指定するために用いられます。各々のサブディレクトリには、サブディレクトリの内容をその環境下で評価するための ``OMakefile`` をそれぞれ有しているべきです。 ::

   .SUBDIRS: src doc tests

.. This rule specifies that the OMakefiles in each of the src, doc, and tests directories should be read.

このルールでは ``src`` , ``doc`` , ``test`` ディレクトリの中のOMakefileをそれぞれ読み込むことを指定しています。

.. In some cases, especially when the OMakefiles are very similar in a large number of subdirectories, it is inconvenient to have a separate OMakefile for each directory. If the .SUBDIRS rule has a body, the body is used instead of the OMakefile.

いくつかの場合─特に ``OMakefile`` の内容が似ている大量のサブディレクトリを持っているような場合─各々のディレクトリに分割して ``OMakefile`` を持たせるのは不便でしょう。もし ``.SUBDIRS`` ルールの中に内容を記述したとすると、その内容が ``OMakefile`` の代わりとして使われます。 ::

   .SUBDIRS: src1 src2 src3
      println(Subdirectory $(CWD))
      .DEFAULT: lib.a

.. In this case, the src1, src2, and src3 files do not need OMakefiles. Furthermore, if one exists, it is ignored. The following includes the file if it exists.

この場合、サブディレクトリ ``src1`` , ``src2`` , ``src3`` には ``OMakefile`` が必要ありません。さらには、たとえ ``OMakefile`` が存在していた場合でも、OMakeはそれを無視します。以下の例では ``OMakefile`` が含まれていた場合、そのファイルをインクルードするよう指定しています。 ::

   .SUBDIRS: src1 src2 src3
       if $(file-exists OMakefile)
          include OMakefile
       .DEFAULT: lib.a

.. index::
   single: .INCLUDE
.. _label8.9:

.INCLUDE
----------------------------------
.. The .INCLUDE target is like the include directive, but it specifies a rule to build the file if it does not exist.

``.INCLUDE`` ターゲットは ``include`` 文と似ていますが、 ``.INCLUDE`` ではたとえ指定されたファイルが存在していなくても、ビルドするためのルールを指定できます。 ::

   .INCLUDE: config
       echo "CONFIG_READ = true" > config

    echo CONFIG_READ is $(CONFIG_READ)

.. You may also specify dependencies to an .INCLUDE rule.

あなたはまた ``.INCLUDE`` ルールの依存関係を指定できます。 ::

   .INCLUDE: config: config.defaults
      cp config.defaults config

.. A word of caution is in order here. The usual policy is used for determining when the rule is out-of-date. The rule is executed if any of the following hold.
      * the target does not exist,
      * the rule has never been executed before,
      * any of the following have changed since the last time the rule was executed,
            o the target,
            o the dependencies,
            o the commands-text. 

順番どおりにターゲットと依存関係が記述されています。通常の場合ですと、この記法はルールがいつ期限切れになったのかどうかを決定するために用いられます。 ``.INCLUDE`` 内のルールは、以下の場合のどれかに当てはまったときに実行されます。

* ターゲットが存在しない場合
* 以前からずっとこのルールが実行されていなかった場合
* ルールが実行された最後の時間から現在までの間に、以下のうちどれかが変更されていた場合

  * ターゲット
  * 依存先
  * コマンド文

.. In some of the cases, this will mean that the rule is executed even if the target file already exists. If the target is a file that you expect to edit by hand (and therefore you don't want to overwrite it), you should make the rule evaluation conditional on whether the target already exists.

これは、たとえ既にターゲットファイルが存在していたとしても、ルールが実行される場合もあることを示しています。もしターゲットが、エディターなどで変更するような(それゆえ上書きされたくない)ファイルを指定する場合、あなたはルールの評価を、ターゲットが既に存在しているかどうかで条件分岐させるべきです。 ::

   .INCLUDE: config: config.defaults
       # わたしが注意深く手作業で変更したファイルを上書きさせません！
       if $(not $(file-exists config))
          cp config.defaults config

.. index::
   single: .PHONY
.. _label8.10:

.PHONY
----------------------------------
.. A “phony” target is a target that is not a real file, but exists to collect a set of dependencies. Phony targets are specified with the .PHONY rule. In the following example, the install target does not correspond to a file, but it corresponds to some commands that should be run whenever the install target is built (for example, by running omake install).

"phony" ターゲットは実際には存在しませんが、複数の依存関係を持っているようなターゲットです。Phony ターゲットは ``.PHONY`` ルールを用いて指定します。以下の例では、 ``install`` ターゲットは実際のファイルではありませんが、( ``omake install`` が実行されることによって) ``install`` ターゲットが生起された場合はいつでも、いくつかのコマンドが実行されます。 ::

   .PHONY: install

   install: myprogram.exe
      cp myprogram.exe /usr/bin

.. _label8.11:

スコープ規則
----------------------------------
.. As we have mentioned before, omake is a scoped language. This provides great flexibility—different parts of the project can define different configurations without interfering with one another (for example, one part of the project might be compiled with CFLAGS=-O3 and another with CFLAGS=-g).

以前私たちが注意したように、omakeは *スコープ化された* 言語です。これは非常に融通のきく─プロジェクトの異なるパートは別のパートを気にすることなく、異なった設定を定義することができる─ものとなっています。例えば、プロジェクトのあるパートには ``CFLAGS=-O3`` を持たせてコンパイルさせるが、別のパートには ``CFLAGS=-g`` を持たせるといった具合です。

.. But how is the scope for a target file selected? Suppose we are building a file dir/foo.o. omake uses the following rules to determine the scope.

しかし、どのようにしてターゲットファイルのスコープが選択されるのでしょうか？そこで、現在私たちはファイル ``dir/foo.o`` をビルドしているものとしましょう。omakeではスコープを決定するために、以下のルールを用います。

.. * First, if there is an explicit rule for building dir/foo.o (a rule with no wildcards), the context for that rule determines the scope for building the target.
   * Otherwise, the directory dir/ must be part of the project. This normally means that a configuration file dir/OMakefile exists (although, see the .SUBDIRS section for another way to specify the OMakefile). In this case, the scope of the target is the scope at the end of the dir/OMakefile. 

* まず、もし ``fir/foo.o`` をビルドするための明示的なルールが指定されていた(そしてそのルールはワイルドカードを用いていない)場合、そのルールに従って、ターゲットをビルドするためのスコープが決定されます。
* さもなければ、ディレクトリ ``dir/`` はプロジェクトの一部であるので、普通に考えて設定ファイル ``dir/OMakefile`` が存在するはずです(あるいは、 ``OMakefile`` を ``.SUBDIRS`` セクションを用いるなどのなにか別の方法で指定しているかもしれません)。この場合、ターゲットのスコープは ``dir/OMakefile`` の終わりのスコープです。

.. To illustrate rule scoping, let's go back to the example of a “Hello world” program with two files. Here is an example OMakefile (the two definitions of CFLAGS are for illustration).

このスコープ規則を確かめるために、2つのファイルから "Hello world" プログラムを作る例へと戻ってみましょう。これは ``OMakefile`` のサンプルです。( ``CFLAGS`` の2つの定義がスコープ規則の確認に用いられます) ::

    # 実行ファイルはデバッグオプションを用いてコンパイルされます
    CFLAGS = -g
    hello: hello_code.o hello_lib.o
       $(CC) $(CFLAGS) -o $@ $+

    # CFLAGSの再定義
    CFLAGS += -O3

.. In this project, the target hello is explicit. The scope of the hello target is the line beginning with hello:, where the value of CFLAGS is -g. The other two targets, hello_code.o and hello_lib.o do not appear as explicit targets, so their scope is at the end of the OMakefile, where the CFLAGS variable is defined to be -g -O3. That is, hello will be linked with CFLAGS=-g and the .o files will be compiled with CFLAGS=-g -O3.

このプロジェクトでは、ターゲット ``hello`` は *明示的* です。 ``hello`` ターゲットのスコープは ``hello:`` から始まる行なので、 ``CFLAGS`` の値は ``-g`` となります。別の2つのターゲット ``hello_code.o`` と ``hello_lib.o`` は明示的にターゲットが指定されていないため、これらのスコープは ``OMakefile`` の終わりで決定しますので、 ``CFLAGS`` の値は ``-g -O3`` となります。これは、 ``hello`` が ``CFLAGS=-g`` でリンクされて、 ``.o`` ファイルが ``CFLAGS=-g -O3`` でコンパイルされることを表しています。

.. We can change this behavior for any of the targets by specifying them as explicit targets. For example, suppose we wish to compile hello_lib.o with a preprocessor variable LIBRARY.

私たちは明示的にターゲットを指定することで、任意のターゲットのふるまいを変えることができます。例えば、私たちは ``hello_lib.o`` を、プリプロセッサ変数 ``LIBRARY`` を用いてコンパイルしたいものとしましょう。 ::

    # 実行ファイルはデバッグオプションを用いてコンパイルされます
    CFLAGS = -g
    hello: hello_code.o hello_lib.o
       $(CC) $(CFLAGS) -o $@ $+

    # hello_lib.o を CFLAGS = -g -DLIBRARY オプションでコンパイル
    section
        CFLAGS += -DLIBRARY
        hello_lib.o:

    # CFLAGSの再定義
    CFLAGS += -O3

.. In this case, hello_lib.o is also mentioned as an explicit target, in a scope where CFLAGS=-g -DLIBRARY. Since no rule body is specified, it is compiled using the usual implicit rule for building .o files (in a context where CFLAGS=-g -DLIBRARY).

この場合、 ``hello_lib.o`` の暗黙のターゲットが、 ``CFLAGS=-g -DLIBRARY`` のスコープ中で指定されています。これはルールの内容が指定されていないため、 ``.o`` ファイルは、通常の暗黙のルールを使って( ``CFLAGS=-g -DLIBRARY`` のオプションで)コンパイルされます。

.. index::
   single: 暗黙のルール
.. _label8.11.1:

暗黙のルールのスコーピング
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. Implicit rules (rules containing wildcard patterns) are not global, they follow the normal scoping convention. This allows different parts of a project to have different sets of implicit rules. If we like, we can modify the example above to provide a new implicit rule for building hello_lib.o.

暗黙のルール(ワイルドパターンを含む)は *グローバルではなく* 、通常のスコープ規則に従っています。これによって、異なるプロジェクトのパートは、異なる暗黙のルールの集合を持つことができるようになりました。もしやってみたいのであれば、私たちは上のサンプルを、以下のような新しい暗黙のルールに修正することができます。 ::

    # 実行ファイルはデバッグオプションを用いてコンパイルされます
    CFLAGS = -g
    hello: hello_code.o hello_lib.o
       $(CC) $(CFLAGS) -o $@ $+

    # hello_lib.o を CFLAGS = -g -DLIBRARY オプションでコンパイル
    section
        %.o: %.c
            $(CC) $(CFLAGS) -DLIBRARY -c $<
        hello_lib.o:

    # CFLAGSの再定義
    CFLAGS += -O3

.. In this case, the target hello_lib.o is built in a scope with a new implicit rule for building %.o files. The implicit rule adds the -DLIBRARY option. This implicit rule is defined only for the target hello_lib.o; the target hello_code.o is built as normal.

この場合、ターゲット ``hello_lib.o`` は、 ``%.o`` をビルドするための新しい暗黙のルールがあるスコープ中でビルドされます。この暗黙のルールでは ``-DLIBRARY`` オプションを加えています。この暗黙のルールはターゲット ``hello_lib.o`` だけに定義されるため、ターゲット ``hello_code.o`` は普通にビルドされます。

.. index::
   single: .SCANNER
   single: :scanner:
.. _label8.11.2:

.SCANNER ルールのスコーピング
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. Scanner rules are scoped the same way as normal rules. If the .SCANNER rule is explicit (containing no wildcard patterns), then the scope of the scan target is the same as the the rule. If the .SCANNER rule is implicit, then the environment is taken from the :scanner: dependency.

スキャナルールは通常のスコープ規則と同様にスコープされます。 ``.SCANNER`` ルールが明示的に指定されていた(ワイルドカードパターンを含まない)場合、スキャンターゲットのスコープはルールと同様に扱われます。 ``.SCANNER`` ルールが暗黙的に指定されていた場合、その環境は ``:scanner:`` 依存関係によって決定されます。 ::

    # 実行ファイルはデバッグオプションを用いてコンパイルされます
    CFLAGS = -g
    hello: hello_code.o hello_lib.o
       $(CC) $(CFLAGS) -o $@ $+

    # .c ファイルのスキャナ
    .SCANNER: scan-c-%.c: %.c
       $(CC) $(CFLAGS) -MM $<

    # hello_lib.o を CFLAGS = -g -DLIBRARY オプションでコンパイル
    section
        CFLAGS += -DLIBRARY
        hello_lib.o: hello_lib.c :scanner: scan-c-hello_lib.c
           $(CC) $(CFLAGS) -c $<

    # hello_code.c を CFLAGS = -g -O3 オプションでコンパイル
    section
        CFLAGS += -O3
        hello_code.o: hello_code.c :scanner: scan-c-hello_code.c
           $(CC) $(CFLAGS) -c $<

.. Again, this is for illustration—it is unlikely you would need to write a complicated configuration like this! In this case, the .SCANNER rule specifies that the C-compiler should be called with the -MM flag to compute dependencies. For the target hello_lib.o, the scanner is called with CFLAGS=-g -DLIBRARY, and for hello_code.o it is called with CFLAGS=-g -O3.

再びこの例が登場しましたーあなたは恐らく、このような複雑怪奇な設定を書きたいとは思っていないでしょう！この場合、 ``.SCANNER`` ルールでは、Cコンパイラが依存関係を計算するために ``-MM`` フラグを用いて呼び出すことを指定しています。ターゲット ``hello_lib.o`` には、スキャナは ``CFLAGS=-g -DLIBRARY`` が呼ばれ、 ``hello_code.o`` には、 ``CFLAGS=-g -O3`` が呼ばれます。

.. index::
   single: .PHONY
   single: .SUBDIRS
.. _label8.11.3:

.PHONY ターゲットのスコーピング
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. Phony targets (targets that do not correspond to files) are defined with a .PHONY: rule. Phony targets are scoped as usual. The following illustrates a common mistake, where the .PHONY target is declared after it is used.

Phonyターゲット(実際のファイルに相当しないターゲット)は ``.PHONY`` ルールを用いて定義されます。Phonyターゲットは普通にスコープされます。以下の例はよくある間違いで、 ``.PHONY`` ターゲットはそれが使われている *後で* 宣言されています。 ::

    # !!この例は正常に動きません!!
    all: hello

    hello: hello_code.o hello_lib.o
        $(CC) $(CFLAGS) -o $@ $+

    .PHONY: all

.. This doesn't work as expected because the .PHONY declaration occurs too late. The proper way to write this example is to place the .PHONY declaration first.

``.PHONY`` 宣言が非常に遅れてしまっているために、この例は期待している通りには動きません。正しくは ``.PHONY`` 宣言を最初に持っていきます。 ::

    # Phonyターゲットはそれが使われる前に宣言されなければなりません
    .PHONY: all

    all: hello

    hello: hello_code.o hello_lib.o
        $(CC) $(CFLAGS) -o $@ $+

.. Phony targets are passed to subdirectories. As a practical matter, it is wise to declare all .PHONY targets in your root OMakefile, before any .SUBDIRS. This will ensure that 1) they are considered as phony targets in each of the subdirectories, and 2) you can build them from the project root.

Phonyターゲットはサブディレクトリに渡されます。実用性から、すべての ``.PHONY`` ターゲットを ``.SUBDIRS`` が表れる前に、ルートの ``OMakefile`` に宣言することは賢い判断と言えるでしょう。これは以下の点を保証してくれます。

1. 各々のサブディレクトリにPhonyターゲットが渡される
2. プロジェクトのルートディレクトリからビルドすることができる

::

    .PHONY: all install clean

    .SUBDIRS: src lib clib

.. Note that when a .PHONY target is inherited by a subdirectory via a .SUBDIRS, a whole hierarchy of .PHONY targets (that are a part of the global one) is created, as described in Section 8.12.2 below.

.. note::
  ``.SUBDIRS`` を経由したサブディレクトリによって ``.PHONY`` ターゲットが継承されたときに、全体の ``.PHONY`` ターゲット(これはグローバルの一部分です)の階層構造が作られます。詳細は下のセクション ":ref:`label8.12.2`" を参照してください。

.. _label8.12:

サブディレクトリからOMakeを実行
----------------------------------------------
.. Running omake foo asks OMake to build the file foo in context of the whole project, even when running from a subdirectory of the project. Therefore, if bar/baz is a regular target (not a .PHONY one), then running omake bar/baz and running (cd bar; omake baz) are usually equivalent.

``omake foo`` を実行した場合、 *全体* のプロジェクトの文脈から ``foo`` ファイルに関連する部分だけをビルドします。たとえそれがプロジェクトのサブディレクトリから実行したとしてもです。それゆえ、もし ``bar/baz`` が通常のターゲット( ``.PHONY`` ターゲットではない)であるとすると、 ``omake bar/baz`` を実行することは ``(cd bar; omake baz)`` を実行することと等価です。

.. There are two noteworthy exceptions to the above rule: 

上のルールには、2つの注目に値する例外が存在します。

..    * If the subdirectory is not a part of the project (there is no .SUBDIRS) for it, then OMake will complain if you try to run it in that directory.
      * If a subdirectory contains an OMakeroot of its own, this would designate the subdirectory as a separate project (which is usually a bad idea and is not recommended). 

* サブディレクトリがプロジェクトの一部でなかった( ``.SUBDIRS`` に存在しない)場合、あなたがそのディレクトリから実行させようとすると、OMakeは文句を言うでしょう。
* サブディレクトリ自身に ``OMakeroot`` が含まれている場合、OMakeはサブディレクトリを別のプロジェクトとして解釈します。これはあまり良い考えではないので推奨しません。

.. index::
   single: .PHONY
.. _label8.12.1:

サブディレクトリのPhonyターゲット
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. Suppose you have a .PHONY: clean declared in your root OMakefile and both the root OMakefile and the OMakefile in some of the subdirectories contain clean: rules. In this case 

``.PHONY: clean`` がルートの ``OMakefile`` で宣言されており、さらにルートの ``OMakefile`` と、サブディレクトリのいくつかの ``OMakefile`` が ``clean:`` ルールを含んでいるものとします。この場合、

..    * Running omake clean in the root directory will execute all the rules (each in the appropriate directory);
      * Running omake clean in the subdirectory will execute just its local one, as well as the ones from the subdirectories of the current directory. 

* ``omake clean`` をルートのディレクトリで実行したときには、(適切なディレクトリの中にある各々の)すべての ``clean:`` ルールが実行されます。
* ``omake clean`` をサブディレクトリで実行したときには、カレントサブディレクトリの ``clean:`` ルールだけが実行されます。

.. The above equally applies to the built-in .PHONY targets, including .DEFAULT. Namely, if OMake is executed (without argument) in the root directory of a project, all the .DEFAULT targets in the project will be built. On the other hand, when OMake is executed (without argument) in a subdirectory, only the .DEFAULT targets defined in and under that subdirectory will be built.

上のルールは ``.DEFAULT`` を含んだ、ビルドインの ``.PHONY`` ターゲットに等しく適用されます。すなわち、もしOMakeがプロジェクトのルートディレクトリで(引数なしで)実行された場合、プロジェクト中のすべての ``.DEFAULT`` がビルドされます。一方で、サブディレクトリでOMakeが(引数なしで)実行された場合、サブディレクトリ中で定義された ``.DEFAULT`` ターゲットだけがビルドされます。

.. The following Section explains the underlying semantics that gives rise to the above behavior.

以下のセクションでは上のようなふるまいをもたらしている、基本的な概念について説明します。

.. _label8.12.2:

.PHONYターゲットの階層構造
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. When the the root OMakefile contains a .PHONY: clean directive, it creates: 

ルートの ``OMakefile`` が ``.PHONY:clean`` を含んでいた場合、OMakeは以下を生成します。

..    * A “global” phony target /.PHONY/clean (note the leading “/”);
      * A “relative” phony target attached to the current directory — .PHONY/clean (note the lack of the leading “/”);
      * A dependency /.PHONY/clean: .PHONY/clean. 

* "グローバル(global)"なPhonyターゲット ``/.PHONY/clean`` (先頭の "``/``" に注目してください)
* カレントディレクトリに所属している、"関連している(relative)"Phonyターゲット ``.PHONY/clean`` (先頭の "``/``" が欠けていることに注目してください)
* 依存関係 ``/.PHONY/clean: .PHONY/clean``

.. All the clean: ... rules in the root OMakefile following this .PHONY: clean declaration would be interpreted as rules for the .PHONY/clean target.

ルートの ``OMakefile`` では、 ``.PHONY: clean`` 宣言の後にくるすべての ``clean: ...`` ルールは、 ``.PHONY/clean`` ターゲットのルールとして解釈されます。

.. Now when OMake then comes across a .SUBDIRS: foo directive (when it is in scope of the above .PHONY: clean declaration), it does the following: 

それでは、次にOMakeは(上の ``.PHONY: clean`` 宣言のスコープ上で) ``.SUBDIRS: foo`` に遭遇したとしましょう。この場合、OMakeは以下の処理を行います。

..    * Creates a new .PHONY/foo/clean “relative” phony target;
      * Creates the dependency .PHONY/clean: .PHONY/foo/clean;
      * Processes the body of the .SUBDIRS: foo directive, or reads the foo/OMakefile file, if the body is empty. While doing that, it interprets its instructions relative to the foo directory. In particular, all the clean: ... rules will be taken to apply to .PHONY/foo/clean. 

* 新しい ``.PHONY/foo/clean`` Phonyターゲットを生成します。このターゲットは"関連している"Phonyターゲットです。
* 依存関係 ``.PHONY/clean: .PHONY/foo/clean`` を生成します。
* ``.SUBDIRS: foo`` の内容を処理するか、もし内容が空であった場合は ``foo/OMakefile`` を読み込みます。処理している間、これらの指示は ``foo`` ディレクトリに関連しているものと解釈します。特に、すべての ``clean: ...`` ルールは ``.PHONY/foo/clean`` に適用されます。

.. Now when you run omake clean in the root directory of the project, it is interpreted as omake .PHONY/clean (similar to how it happens with the normal targets), so both the rules for .PHONY/clean are executed and the rules for its dependency .PHONY/foo/clean. Running (cd foo; omake clean) is, as for normal targets, equivalent to running omake .PHONY/foo/clean and only those rules that apply to .PHONY/foo/clean will be executed.

あなたが ``omake clean`` をプロジェクトのルートディレクトリで実行した場合、これは ``omake .PHONY/clean`` として解釈され(通常のターゲットに関しても同様です)、 ``.PHONY/clean`` のルールと、その依存関係 ``.PHONY/foo/clean`` のルールの両方が実行されます。また、 ``(cd foo; omake clean)`` を実行することは、 ``omake .PHONY/foo/clean`` を実行することと等価であり、 ``.PHONY/foo/clean`` のルールだけが実行されます。これもまた、通常のターゲットに関して同様です。

.. index::
   single: absname()
   single: --absname
   single: OMakeFlags()
.. _label8.13:

ルール中でのパス名
----------------------------------
.. In rules, the targets and dependencies are first translated to file values (as in the file function). They are then translated to strings for the command line. This can cause some unexpected behavior. In the following example, the absname function is the absolute pathname for the file a, but the rule still prints the relative pathname.

ルール中では、ターゲットと依存先は最初に"ファイル"として変換されます(詳細は ":ref:`label10.1.1`" を参照してください)。これらはコマンドライン上で文字列として変換される値です。また、これによっていくつかの期待していないふるまいを起こすことがあります。以下の例では、 ``absname`` 関数はファイル ``a`` の絶対パスを返す関数ですが、それにも関わらずこのルールでは相対パスとして出力されています。 ::

    .PHONY: demo
    demo: $(absname a)
        echo $<

    # omakeのデモ
    a

.. There is arguably a good reason for this. On Win32 systems, the / character is viewed as an “option specifier.” The pathname separator is the \ character. OMake translates the filenames automatically so that things work as expected on both systems.

この振る舞いについては、議論の余地がある良い理由があります。Win32のシステム上では、 ``/`` という文字は『オプションの指定子』として判定されます。そして、パス名のセパレータには
``\`` が用いられています。OMakeはファイル名を自動的に変換することで、両方のシステムで期待通りの動きをするようにしてくれます。 ::

   demo: a/b
       echo $<

   # omakeのデモ(Unixのシステム上)
   a/b
   # omakeのデモ(Win32のシステム上)
   a\b

.. Sometimes you may wish that target strings to be passed literally to the commands in the rule. One way to do this is to specify them literally.

ときどき、あなたはターゲット名を、ルール中のコマンドに文字通り渡したいと思うことがあるかもしれません。これを解決する一つの方法は、変数を指定してあげることです。 ::

    SRC = a/b $(absname c/d)
    demo: $(SRC)
        echo $(SRC)

    # omakeのデモ(Win32のシステム上)
    a/b c:\...\c\d

.. Alternately, you might wish that filenames be automatically expanded to absolute pathnames. For example, this might be useful when parsing the OMake output to look for errors. For this, you can use the --absname option (Section A.3.20). If you call omake with the --absname option, all filenames will be expanded to absolute names.

ついでに、あなたはファイル名を自動的に絶対パスに展開してほしいと思うこともあるかもしれません。例えば、エラーを見るために、OMakeの出力を解析するような場合には有効でしょう。これを実現するために、あなたは ``--absname`` オプションを用いることができます(詳細は :ref:`labelA.3.20` を参照してください)。もしあなたが ``omake`` を ``--absname`` オプションで呼び出した場合、すべてのファイル名は絶対パスとして展開されます。 ::

    # omake --absname のデモ(Unixのシステム上)
    /home/.../a/b /home/.../c/d

.. Alternately, the --absname option is scoped. If you want to use it for only a few rules, you can use the OMakeFlags function to control how it is applied.

ついでに、 ``--absname`` オプションはスコープ化されています。もしあなたがこれを限られたルールでのみ用いたい場合は、 ``OMakeFlags`` 関数を使うことで、 ``--absname`` オプションを適用するかどうかをコントロールすることができます。 ::

   section
      OMakeFlags(--absname)
      demo: a
          echo $<

   # omakeデモ
   /home/.../a

.. N.B. The --absname option is currently an experimental feature.

.. warning::
  ``--absname`` オプションは現在、実験的な機能として搭載しています。