autoconf, configureの索引を追加. 自動設定->autoconfと分かりやすく.

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

.. 2-quickstart

.. _label2:

2. OMakeクイックスタートガイド
==================================

.. _label2.1:

2.1 概要
----------------------------------
.. omake is designed for building projects that might have source files in several directories. Projects are normally specified using an OMakefile in each of the project directories, and an OMakeroot file in the root directory of the project. The OMakeroot file specifies general build rules, and the OMakefiles specify the build parameters specific to each of the subdirectories. When omake runs, it walks the configuration tree, evaluating rules from all of the OMakefiles. The project is then built from the entire collection of build rules.

OMakeは複数のディレクトリにまたがって存在するソースファイルをビルドするために製作されたツールです。OMakeを使用したプロジェクトは通常、 ``OMakefile`` を各々のプロジェクトディレクトリに置き、 ``OMakeroot`` をプロジェクトのルートディレクトリに置きます。 ``OMakeroot`` には一般的なビルドルールを指定し、 ``OMakefiles`` にはそれぞれのサブディレクトリに固有のビルドパラメータを指定します。いったんOMakeを起動すると、OMakeはまず設定ファイルのあるディレクトリをスキャンし、すべての ``OMakefile`` を評価します。そしてプロジェクトは全体のビルドルールの集合としてビルドされます。

.. index::
   single: .SCANNER
.. _label2.1.1:

2.1.1 自動的な依存関係の解析
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. Dependency analysis has always been problematic with the make(1) program. omake addresses this by adding the .SCANNER target, which specifies a command to produce dependencies. For example, the following rule

従来のmake(1)プログラムでは以前から依存関係の解析が問題となっていました。OMakeではこの問題を、依存関係を生成するコマンドを指定した ``.SCANNER`` ターゲットを追加することで解決しました。たとえば、以下のルール ::

    .SCANNER: %.o: %.c
        $(CC) $(INCLUDE) -MM $<

.. is the standard way to generate dependencies for .c files. omake will automatically run the scanner when it needs to determine dependencies for a file.

は ``.c`` ファイルの依存関係を生成する常套手段です。OMakeはソースファイルの依存関係を知る必要がある時点で、自動的にソースファイルをスキャンし、依存関係を特定します。

.. index::
   single: MD5
   single: .omakedb
.. _label2.1.2:

2.1.2 ファイル内容から依存関係を解析
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. Dependency analysis in omake uses MD5 digests to determine whether files have changed. After each run, omake stores the dependency information in a file called .omakedb in the project root directory. When a rule is considered for execution, the command is not executed if the target, dependencies, and command sequence are unchanged since the last run of omake. As an optimization, omake does not recompute the digest for a file that has an unchanged modification time, size, and inode number.

どのファイルの依存関係が変更されたかを知るために、OMakeではMD5による要約を用いてチェックを行います。各々のディレクトリでOMakeが実行された後に、 OMakeは依存関係の情報をプロジェクトルートディレクトリの ``.omakedb`` ファイルに保存します。いったんOMakeが依存関係のルールファイルを保存したのであれば、OMakeが最後に実行された時点で、ターゲット、依存関係、ソースコードに関して変更がない場合、ビルドは実行されません。また最適化としてOMakeはMD5の再計算を、修正日時、サイズ、ノード番号に変更のないファイルに関しては実行しません。

.. index::
   single: make
   single: .PHONY
   single: .SUBDIRS
   single: .SUFFIXES
.. _label2.2:

2.2 既にmakeに慣れている人向けの注意事項
------------------------------------------
.. For users already familiar with the make(1) command, here is a list of differences to keep in mind when using omake.

既にmakeコマンドに慣れているユーザがomakeを使う際には、以下のmakeとomakeの違いを列挙したリストについて留意しておきましょう。

..  * In omake, you are much less likely to define build rules of your own. The system provides many standard functions (like StaticCLibrary and CProgram), described in Chapter 13, to specify these builds more simply.
    * Implicit rules using .SUFFIXES and the .suf1.suf2: are not supported. You should use wildcard patterns instead %.suf2: %.suf1.
    * Scoping is significant: you should define variables and .PHONY targets (see Section 8.10) before they are used.
    * Subdirectories are incorporated into a project using the .SUBDIRS: target (see Section 8.8). 

* omakeを用いると、あなたがビルドルールを自力で定義するよりもはるかに省力化できます。このシステムは多くのビルドイン関数を提供しています( ``StaticCLibrary`` や ``CProgram`` など)。第13章(:ref:`label13`)で説明した事項を用いると、これらのビルドはより簡単になります。
* ``.SUFFIXES`` や ``.suf1.suf2:`` などを用いた暗黙のルール(implicit rule)はサポートされていません。その代わりにあなたはワイルドカード ``%.suf2: %.suf1`` を用いるべきです。
* スコーピングは重要です。あなたは変数や ``.PHONY`` ターゲットを、使用する前に定義すべきです。(詳細は ":ref:`label8.10`" を参照してください。)
* サブディレクトリをプロジェクトに組み入れる際には、 ``.SUBDIRS:`` ターゲットを用います。(詳細は ":ref:`label8.8`" を参照してください。)

.. index::
   single: CProgram()
   single: OMakefile
   single: OMakeroot
   single: EXE
   single: CC
   single: CFLAGS
   single: .DEFAULT
.. _label2.3:

2.3 小さなCプログラムのビルド
--------------------------------
.. To start a new project, the easiest method is to change directories to the project root and use the command omake --install to install default OMakefiles.

新しいプロジェクトを作る際にもっとも簡単な方法は、カレントディレクトリをプロジェクトのルートディレクトリに変え、 ``omake --install`` とコマンドを入力してデフォルトの ``OMakefile`` と ``OMakeroot`` をインストールすることです。 ::

    $ cd ~/newproject
    $ omake --install
    *** omake: creating OMakeroot
    *** omake: creating OMakefile
    *** omake: project files OMakefile and OMakeroot have been installed
    *** omake: you should edit these files before continuing

.. The default OMakefile contains sections for building C and OCaml programs. For now, we'll build a simple C project.

デフォルトの ``OMakefile`` はCとOCamlのプログラムをビルドするためのセクションを含んでいます。さて、それではOMakeを用いて簡単なCプロジェクトをビルドしてみましょう。

.. Suppose we have a C file called hello_code.c containing the following code:

私たちは ``hello_code.c`` というCファイルを持っており、そのコードは以下であったとします。 ::

    #include <stdio.h>

    int main(int argc, char **argv)
    {
        printf("Hello world\n");
        return 0;
    }

.. To build the program a program hello from this file, we can use the CProgram function. The OMakefile contains just one line that specifies that the program hello is to be built from the source code in the hello_code.c file (note that file suffixes are not passed to these functions).

このファイルから ``hello`` というプログラムをビルドする場合、 ``CProgram`` という関数を使うことができます。 ``OMakefile`` に ``hello_code.c`` のソースコードから ``hello`` プログラムをビルドすることを指定するため、以下の一行を加えます(ファイルの拡張子はこれらの関数に渡していないことに注意してください)。 ::

    CProgram(hello, hello_code)

.. Now we can run omake to build the project. Note that the first time we run omake, it both scans the hello_code.c file for dependencies, and compiles it using the cc compiler. The status line printed at the end indicates how many files were scanned, how many were built, and how many MD5 digests were computed.

これで私たちはこのプロジェクトをビルドするために、OMakeを実行することができます。最初に私たちがOMakeを実行した時点で、OMakeは依存関係の解析に ``hello_code.c`` を解析し、 ``cc`` コンパイラを用いてコンパイルします。一番最後の行にはどれだけ多くのファイルが解析されて、どれだけ多くビルドされて、そしてどれだけ多くのMD5が計算されたのかが表示されます。 ::

    $ omake hello
    *** omake: reading OMakefiles
    *** omake: finished reading OMakefiles (0.0 sec)
    - scan . hello_code.o
    + cc -I. -MM hello_code.c
    - build . hello_code.o
    + cc -I. -c -o hello_code.o hello_code.c
    - build . hello
    + cc -o hello hello_code.o
    *** omake: done (0.5 sec, 1/6 scans, 2/6 rules, 5/22 digests)
    $ omake
    *** omake: reading OMakefiles
    *** omake: finished reading OMakefiles (0.1 sec)
    *** omake: done (0.1 sec, 0/4 scans, 0/4 rules, 0/9 digests)

.. If we want to change the compile options, we can redefine the CC and CFLAGS variables before the CProgram line. In this example, we will use the gcc compiler with the -g option. In addition, we will specify a .DEFAULT target to be built by default. The EXE variable is defined to be .exe on Win32 systems; it is empty otherwise.

私たちがコンパイルオプションを変更したいと思った場合、 ``CProgram`` と書いてある行の前に ``CC`` と ``CFLAGS`` 変数を再定義することで可能となります。たとえば、現在私たちは ``-g`` オプションで ``gcc`` コンパイラを用いたいとします。加えて、デフォルトでビルドするために ``.DEFAULT`` ターゲットを指定したい、さらにWin32システムで ``.exe`` と定義された ``EXE`` 変数を用いたいとします。これらの要望は以下のコードで実現できます。 ::

    CC = gcc
    CFLAGS += -g
    CProgram(hello, hello_code)
    .DEFAULT: hello$(EXE)

.. Here is the corresponding run for omake.

以下はomakeを実行させた場合の全体のコンソールです。 ::

    $ omake
    *** omake: reading OMakefiles
    *** omake: finished reading OMakefiles (0.0 sec)
    - scan . hello_code.o
    + gcc -g -I. -MM hello_code.c
    - build . hello_code.o
    + gcc -g -I. -c -o hello_code.o hello_code.c
    - build . hello
    + gcc -g -o hello hello_code.o
    *** omake: done (0.4 sec, 1/7 scans, 2/7 rules, 3/22 digests)

.. We can, of course, include multiple files in the program. Suppose we write a new file hello_helper.c. We would include this in the project as follows.

もちろん、プログラム中に複数のファイルをインクルードすることもできます。 ``hello_helper.c`` という新しいファイルを追加したとしましょう。以下のように ``OMakefile`` を変更することで対応できます。 ::

    CC = gcc
    CFLAGS += -g
    CProgram(hello, hello_code hello_helper)
    .DEFAULT: hello$(EXE)

.. index::
   single: StaticCLibrary()
.. _label2.4:

2.4  巨大なプロジェクト
-------------------------
.. As the project grows it is likely that we will want to build libraries of code. Libraries can be built using the StaticCLibrary function. Here is an example of an OMakefile with two libraries.

プロジェクトが成長するにつれて、コードからライブラリをビルドしたいと思うかもしれません。ライブラリは ``StaticCLibrary`` 関数を用いることでビルドすることができます。以下は二つのライブラリをビルドする際の ``OMakefile`` のサンプルです。 ::

    CC = gcc
    CFLAGS += -g

    FOO_FILES = foo_a foo_b
    BAR_FILES = bar_a bar_b bar_c

    StaticCLibrary(libfoo, $(FOO_FILES))
    StaticCLibrary(libbar, $(BAR_FILES))

    # helloプログラムは両方のライブラリを用いてリンクされます
    LIBS = libfoo libbar
    CProgram(hello, hello_code hello_helper)

    .DEFAULT: hello$(EXE)

.. index::
   single: INCLUDES
   single: section
   single: export
   single: StaticCLibraryInstall()
   single: if
.. _label2.5:

2.5  サブディレクトリ
--------------------------
.. As the project grows even further, it is a good idea to split it into several directories. Suppose we place the libfoo and libbar into subdirectories.

プロジェクトがさらに成長していく時点で、いくつかのディレクトリにコードファイルを分割することは良いアイデアです。現在私たちは ``libfoo`` と ``libbar`` をサブディレクトリに置いてあるものとしましょう。

.. In each subdirectory, we define an OMakefile for that directory. For example, here is an example OMakefile for the foo subdirectory.

まず、 ``OMakefile`` を各々のサブディレクトリ内に置きます。例えば、以下は ``foo/`` サブディレクトリ内の ``OMakefile`` のサンプルです。 ::

    INCLUDES += .. ../bar

    FOO_FILES = foo_a foo_b
    StaticCLibrary(libfoo, $(FOO_FILES))

.. Note the the INCLUDES variable is defined to include the other directories in the project.

``INCLUDES`` 変数はプロジェクトの他のディレクトリをインクルードするために定義されています。

.. Now, the next step is to link the subdirectories into the main project. The project OMakefile should be modified to include a .SUBDIRS: target.

さて、次のステップはメインプロジェクトの中にサブディレクトリをリンクさせます。プロジェクトの ``OMakefile`` を ``.SUBDIRS`` プロジェクトを含めるように修正します。 ::

    # プロジェクトの設定
    CC = gcc
    CFLAGS += -g

    # サブディレクトリ
    .SUBDIRS: foo bar

    # ライブラリはサブディレクトリの中に存在します
    LIBS = foo/libfoo bar/libbar

    CProgram(hello, hello_code hello_helper)

    .DEFAULT: hello$(EXE)

.. Note that the variables CC and CFLAGS are defined before the .SUBDIRS target. These variables remain defined in the subdirectories, so that libfoo and libbar use gcc -g.

変数 ``CC`` と ``CFLAGS`` は ``.SUBDIRS`` ターゲットの *前に* 定義されてあることに注目してください。これらの変数はサブディレクトリでも保持されていますので、 ``libfoo`` と ``libbar`` では ``gcc -g`` が使われます。

.. If the two directories are to be configured differently, we have two choices. The OMakefile in each subdirectory can be modified with its configuration (this is how it would normally be done). Alternatively, we can also place the change in the root OMakefile.

二つのディレクトリに異なる設定を用いる必要がある場合、二つの方法があります。一つ目は各々のサブディレクトリの ``OMakefile`` にそれぞれの設定を書く方法です(普通はこのようにして問題を解決します)。二つ目は、ルートの ``OMakefile`` を以下のコードに書き換える方法です。 ::

    # 通常のプロジェクト設定
    CC = gcc
    CFLAGS += -g

    # libfooは通常の設定を用います
    .SUBDIRS: foo

    # libbarは加えて最適化を行います
    CFLAGS += -O3
    .SUBDIRS: bar

    # メインプログラム
    LIBS = foo/libfoo bar/libbar
    CProgram(hello, hello_code hello_helper)

    .DEFAULT: hello$(EXE)

.. Note that the way we have specified it, the CFLAGS variable also contains the -O3 option for the CProgram, and hello_code.c and hello_helper.c file will both be compiled with the -O3 option. If we want to make the change truly local to libbar, we can put the bar subdirectory in its own scope using the section form.

``CFLAGS`` 変数にさらに ``-O3`` オプションを加えることで、 ``hello_code.c`` と ``hello_helper.c`` の両方は ``-O3`` オプションでコンパイルされます。
``libbar`` のみにオプションを変更させたい場合、 ``section`` 文を使用することで ``bar/`` サブディレクトリ内のみに変更を適用することができます。 ::

    # 通常のプロジェクト設定
    CC = gcc
    CFLAGS += -g

    # libfooは通常の設定を用います
    .SUBDIRS: foo

    # libbarは加えて最適化を行います
    section
        CFLAGS += -O3
        .SUBDIRS: bar

    # メインプログラムでは最適化を使用しません
    LIBS = foo/libfoo bar/libbar
    CProgram(hello, hello_code hello_helper)

    .DEFAULT: hello$(EXE)

.. Later, suppose we decide to port this project to Win32, and we discover that we need different compiler flags and an additional library.

後で、私たちがこのプロジェクトをWin32に移し、そして異なるコンパイラフラグや追加ライブラリが必要になることがわかったとしましょう。 ::

    # 通常のプロジェクト設定
    if $(equal $(OSTYPE), Win32)
        CC = cl /nologo
        CFLAGS += /DWIN32 /MT
        export
    else
        CC = gcc
        CFLAGS += -g
        export

    # libfooは通常の設定を用います
    .SUBDIRS: foo

    # libbarは加えて最適化を行います
    section
        CFLAGS += $(if $(equal $(OSTYPE), Win32), $(EMPTY), -O3)
        .SUBDIRS: bar

    # 通常のライブラリ
    LIBS = foo/libfoo bar/libbar

    # Win32上のみlibwin32を必要とします
    if $(equal $(OSTYPE), Win32)
       LIBS += win32/libwin32

       .SUBDIRS: win32
       export

    # メインプログラムでは最適化を使用しません
    CProgram(hello, hello_code hello_helper)

    .DEFAULT: hello$(EXE)

.. Note the use of the export directives to export the variable definitions from the if-statements. Variables in omake are scoped—variables in nested blocks (blocks with greater indentation), are not normally defined in outer blocks. The export directive specifies that the variable definitions in the nested blocks should be exported to their parent block.

``export`` によって ``if`` 文の中にある変数が外部にエクスポートされます。 *OMakeでの変数はスコープ化* されており、ネストされたブロック内の変数は通常、外部のブロックから使用することはできません。 ``export`` はネストされたブロック内の変数を、親のブロックに移す命令です。

.. note::
  訳注: 今回の例では ``$(OSTYPE)`` 変数を用いて場合分けを行っていますが、 ``$(CC)`` 変数に関しては省略することができます。なぜなら、 ``Unix`` 上では ``$(CC)`` は ``gcc`` , ``Win32`` 上では ``cl /nologo`` が自動的に束縛されるからです。
  
  大抵の場合において、このような設定変数は異なるプラットフォーム上においても正常に動作するよう設計されています(詳細は ":ref:`label13.5.2`" を参照してください)。もちろん、その他になにか追加オプションを指定したい場合には、このような場合分けが有効となるでしょう。

.. Finally, for this example, we decide to copy all libraries into a common lib directory. We first define a directory variable, and replace occurrences of the lib string with the variable.

最後に、私たちはすべてのライブラリを共通の ``lib/`` ディレクトリにコピーしたいものとします。私たちはまずはじめにディレクトリの変数を定め、そして ``lib`` の文字列を変数で置き換えます。 ::

    # 共用のlibディレクトリ
    LIB = $(dir lib)

    # phonyターゲットはライブラリのみビルドを行います
    .PHONY: makelibs

    # 通常のプロジェクト設定
    if $(equal $(OSTYPE), Win32)
        CC = cl /nologo
        CFLAGS += /DWIN32 /MT
        export
    else
        CC = gcc
        CFLAGS += -g
        export

    # libfooは通常の設定を用います
    .SUBDIRS: foo

    # libbarは加えて最適化を行います
    section
        CFLAGS += $(if $(equal $(OSTYPE), Win32), $(EMPTY), -O3)
        .SUBDIRS: bar

    # 通常のライブラリ
    LIBS = $(LIB)/libfoo $(LIB)/libbar

    # Win32上のみlibwin32を必要とします
    if $(equal $(OSTYPE), Win32)
       LIBS += $(LIB)/libwin32

       .SUBDIRS: win32
       export

    # メインプログラムでは最適化を使用しません
    CProgram(hello, hello_code hello_helper)

    .DEFAULT: hello$(EXE)

.. In each subdirectory, we modify the OMakefiles in the library directories to install them into the $(LIB) directory. Here is the relevant change to foo/OMakefile.

``$(LIB)`` ディレクトリの中にライブラリをインストールするため、ライブラリディレクトリ内の ``OMakefile`` を修正します。以下は新しく変更された ``foo/OMakefile`` です。 ::

    INCLUDES += .. ../bar

    FOO_FILES = foo_a foo_b
    StaticCLibraryInstall(makelib, $(LIB), libfoo, $(FOO_FILES))

.. Directory (and file names) evaluate to relative pathnames. Within the foo directory, the $(LIB) variable evaluates to ../lib.

ディレクトリ(そしてファイル名)は現在のパス名で評価されます。 ``foo/`` ディレクトリ内では、 ``$(LIB)`` 変数は ``../lib`` として評価されます。

.. As another example, instead of defining the INCLUDES variable separately in each subdirectory, we can define it in the toplevel as follows.

各々のサブディレクトリ内で ``INCLUDES`` 変数を個別に定義する代わりに、以下のようにトップレベルで定義することもできます。 ::

    INCLUDES = $(ROOT) $(dir foo bar win32)

.. In the foo directory, the INCLUDES variable will evaluate to the string .. . ../bar ../win32. In the bar directory, it would be .. ../foo . ../win32. In the root directory it would be . foo bar win32.

``foo/`` ディレクトリ内において ``INCLUDES`` 変数は文字列 ``.. . ../bar`` として評価されます。また ``bar/`` ディレクトリ内において、 ``INCLUDES`` 変数は文字列 ``.. ../foo . ../win32`` として評価されます。ルートディレクトリでは、 ``INCLUDES`` 変数は文字列 ``. foo bar win32`` として評価されます。

.. note::
  訳注: 今までの議論の中で「 *Win32プラットフォーム上でディレクトリのセパレータに/(スラッシュ)を指定していいのだろうか？\\(バックスラッシュ)を使わないといけないのでは？* 」と疑問に思った方も多いと思います。実は、この点に関しては心配いりません。omakeはたとえWin32上で ``/`` を使っていたとしても、実際の評価ではー非常に奇妙に思われるかもしれませんがー ``\`` が用いられるのです。同様に、セパレータに ``\`` を用いたとしてもUnixプラットフォーム上では ``/`` と変換されます。
  
  このように、ディレクトリのセパレータは ``/`` , ``\`` どちらを使っても、異なるプラットフォーム上で正常に動作します。ただし、 ``\`` はエスケープ文字として使用されることが多いため、思わぬ誤動作を引き起こすことがあるかもしれません。大抵の場合、ディレクトリのセパレータは ``/`` を使うことをおすすめします(詳細は ":ref:`label10.4`" を参照してください)。
  
.. _label2.6:

2.6  その他の考慮事項
--------------------------
.. omake also handles recursive subdirectories. For example, suppose the foo directory itself contains several subdirectories. The foo/OMakefile would then contain its own .SUBDIRS target, and each of its subdirectories would contain its own OMakefile.

OMakeはまたリソースのあるサブディレクトリも扱うことができます。例えば、先ほどの ``foo/`` ディレクトリの中に、さらにいくつかのサブディレクトリを保持しているような場合を考えてみましょう。 ``foo/OMakefile`` は ``foo/`` ディレクトリ自身の ``.SUBDIRS`` ターゲットを保持しており、また各々のサブディレクトリもまたサブディレクトリ自身の ``OMakefile`` を保持しています。

.. index::
   single: OCaml
.. _label2.7:

2.7 OCamlプログラムのビルド
----------------------------
.. By default, omake is also configured with functions for building OCaml programs. The functions for OCaml program use the OCaml prefix. For example, suppose we reconstruct the previous example in OCaml, and we have a file called hello_code.ml that contains the following code.

通常、OMakeはOCamlのプログラムをビルドするための関数群も持っています。OCamlプログラムのための関数群は接頭語として ``OCaml`` がつきます。例えば、前回のサンプルをOCamlで置き換えて、 ``hello_code.ml`` という以下のコードを含んだファイルを持っている場合を考えましょう。 ::

   open Printf

   let () = printf "Hello world\n"

.. An example OMakefile for this simple project would contain the following.

この簡単なプロジェクトのOMakefileのサンプルは以下になります。 ::

    # バイトコードコンパイラを使用
    BYTE_ENABLED = true
    NATIVE_ENABLED = false
    OCAMLCFLAGS += -g

    # プログラムをビルド
    OCamlProgram(hello, hello_code)
    .DEFAULT: hello.run

.. Next, suppose the we have two library subdirectories: the foo subdirectory is written in C, the bar directory is written in OCaml, and we need to use the standard OCaml Unix module.

次に、二つのライブラリのサブディレクトリを持っている場合を考えましょう。 ``foo/`` ディレクトリはCで書かれており、 ``bar/`` ディレクトリはOCamlで書かれています。そして私たちは標準的なOCamlのUNIXモジュールを使用したいといった場合です。 ::

    # 通常のプロジェクト設定
    if $(equal $(OSTYPE), Win32)
        CC = cl /nologo
        CFLAGS += /DWIN32 /MT
        export
    else
        CC = gcc
        CFLAGS += -g
        export

    # バイトコードコンパイラを使用
    BYTE_ENABLED = true
    NATIVE_ENABLED = false
    OCAMLCFLAGS += -g

    # ライブラリのサブディレクトリ
    INCLUDES += $(dir foo bar)
    OCAMLINCLUDES += $(dir foo bar)
    .SUBDIRS: foo bar

    # Cライブラリ
    LIBS = foo/libfoo

    # OCamlライブラリ
    OCAML_LIBS = bar/libbar

    # Unixモジュールも用います
    OCAML_OTHER_LIBS = unix

    # メインプログラム
    OCamlProgram(hello, hello_code hello_helper)

    .DEFAULT: hello

.. The foo/OMakefile would be configured as a C library.

``foo/OMakefile`` はCライブラリとして設定します。 ::

    FOO_FILES = foo_a foo_b
    StaticCLibrary(libfoo, $(FOO_FILES))

.. The bar/OMakefile would build an ML library.

また、 ``bar/OMakefile`` はMLライブラリとして設定します。 ::

   BAR_FILES = bar_a bar_b bar_c
   OCamlLibrary(libbar, $(BAR_FILES))

.. index::
   single: OMakefile
   single: OMakeroot
.. _label2.8:

2.8  OMakefileとOMakeroot
------------------------------------
.. OMake uses the OMakefile and OMakeroot files for configuring a project. The syntax of these files is the same, but their role is slightly different. For one thing, every project must have exactly one OMakeroot file in the project root directory. This file serves to identify the project root, and it contains code that sets up the project. In contrast, a multi-directory project will often have an OMakefile in each of the project subdirectories, specifying how to build the files in that subdirectory.

プロジェクトを設定する際、OMakeは ``OMakefile`` と ``OMakeroot`` の2つのファイルを使用します。これらのファイルの構文は同じですが、役割は全く異なります。さらに付け加えると、すべてのプロジェクトは ``OMakeroot`` ファイルをプロジェクトのルートディレクトリに必ず置かなければなりません。このファイルはこのディレクトリがプロジェクトのルートディレクトリであることを決め、さらにプロジェクトをセットアップするためのコードを含んでいます。対照的に、複数のディレクトリが存在するプロジェクトは、どのようにサブディレクトリ内のファイルをビルドするのかを設定した ``OMakefile`` を、各々のプロジェクトのサブディレクトリに置くことになります。

.. Normally, the OMakeroot file is boilerplate. The following listing is a typical example.

通常、 ``OMakeroot`` ファイルはほとんど変更する必要のない決まり文句です。以下のリストは ``OMakeroot`` ファイルの一部です。 ::

    include $(STDLIB)/build/Common
    include $(STDLIB)/build/C
    include $(STDLIB)/build/OCaml
    include $(STDLIB)/build/LaTeX

    # コマンドライン変数を再定義
    DefineCommandVars(.)

    # 現在のディレクトリをプロジェクトの一部として設定
    .SUBDIRS: .

.. The include lines include the standard configuration files needed for the project. The $(STDLIB) represents the omake library directory. The only required configuration file is Common. The others are optional; for example, the $(STDLIB)/build/OCaml file is needed only when the project contains programs written in OCaml.

``include`` が書かれている行では、プロジェクトに必要な、標準的な設定ファイルをインクルードしています。 ``$(STDLIB)`` 変数はOMakeライブラリのディレクトリを表します。OCamlが動作するために必須となる設定ファイルは ``Common`` だけで、その他の設定ファイルはなくても構いません。 ``$(STDLIB)/build/OCaml`` ファイルはプロジェクトがOCamlで書かれたプログラムを含んでいる場合のみ必要となります。

.. The DefineCommandVars function defines any variables specified on the command line (as arguments of the form VAR=<value>). The .SUBDIRS line specifies that the current directory is part of the project (so the OMakefile should be read).

``DefineCommandVars`` 関数は( ``VAR=<value>`` のような形で)コマンドライン上から指定された、いくつかの変数を定義します。 ``.SUBDIRS`` が書かれている行では現在のディレクトリがプロジェクトの一部であることを指定しています(よって同ディレクトリの ``OMakefile`` が読み込まれます)。

.. Normally, the OMakeroot file should be small and project-independent. Any project-specific configuration should be placed in the OMakefiles of the project.

通常、 ``OMakeroot`` ファイルはサイズが小さく、かつプロジェクトから独立しています。プロジェクト固有の設定はすべてプロジェクト上の ``OMakefile`` に設定すべきです。

.. index::
   single: vmount()
   single: 仮想的なマウント
.. _label2.9:

2.9 複数のバージョンのサポート
-----------------------------------
.. OMake version 0.9.6 introduced preliminary support for multiple, simultaneous versions of a project. Versioning uses the vmount(dir1, dir2) function, which defines a “virtual mount” of directory dir1 over directory dir2. A “virtual mount” is like a transparent mount in Unix, where the files from dir1 appear in the dir2 namespace, but new files are created in dir2. More precisely, the filename dir2/foo refers to: a) the file dir1/foo if it exists, or b) dir2/foo otherwise.

OMake バージョン 0.9.6では、複数の同じバージョンのプロジェクトや、予備として用いる複数のプロジェクトに関するサポートを導入しました。 ``vmount(dir1, dir2)`` 関数を用いることで、 ``dir1/`` ディレクトリを ``dir2/`` ディレクトリに『仮想的にマウント』することができます。『仮想的なマウント』はUnixにて、 ``dir1/`` ディレクトリ内のファイルを ``dir2/`` ディレクトリにマウントするが、新しいファイルは ``dir2/`` ディレクトリに作られるようなものです。さらに具体的には、ファイル ``dir2/foo`` は、 ``dir1/foo`` が存在している場合は ``dir1/foo`` に置き換わりますが、存在していない場合は ``dir2/foo`` が用いられます。

.. The vmount function makes it easy to specify multiple versions of a project. Suppose we have a project where the source files are in the directory src/, and we want to compile two versions, one with debugging support and one optimized. We create two directories, debug and opt, and mount the src directory over them.

``vmount`` 関数によってプロジェクト内の複数のバージョンをビルドすることが容易になりました。 ``src/`` ディレクトリ内にいくつかのソースファイルが入っており、これをデバッグサポートがついているバージョンと、最適化されたバージョンの2つにコンパイルする場合を考えてみましょう。まず ``debug/`` と ``opt/`` の2つのディレクトリを作成して、 ``src/`` ディレクトリをこれらのディレクトリにマウントします。 ::

    section
        CFLAGS += -g
        vmount(-l, src, debug)
        .SUBDIRS: debug

    section
        CFLAGS += -O3
        vmount(-l, src, opt)
        .SUBDIRS: opt

.. Here, we are using section blocks to define the scope of the vmount—you may not need them in your project.

ここで、 ``vmount`` 関数を必要としていないプロジェクトに適用させないために、私たちは ``section`` ブロックを用いて ``vmount`` のスコープ範囲を定義しました。

.. The -l option is optional. It specifies that files form the src directory should be linked into the target directories (or copied, if the system is Win32). The links are added as files are referenced. If no options are given, then files are not copied or linked, but filenames are translated to refer directly to the src/ files.

``-l`` オプションはなくても構いません。それを指定することで ``src/`` ディレクトリのファイルは、ターゲットとなるディレクトリにリンクされます(システムがWin32の場合、ファイルはコピーされます)。ファイルが関連付けられるようにファイルへのリンクが追加されます。何もオプションが与えられていない場合、ファイル名は直接 ``src/`` ディレクトリのファイル名に変換されます。

.. Now, when a file is referenced in the debug directory, it is linked from the src directory if it exists. For example, when the file debug/OMakefile is read, the src/OMakefile is linked into the debug/ directory.

``debug/`` ディレクトリ内のファイルが参照された時点で、もし ``src/`` ディレクトリにそのファイルが存在するならば、 ``debug/`` ディレクトリのファイルは ``src/`` のファイルにリンクされます。例えば、 ``debug/OMakefile`` が参照された場合、 ``src/OMakefile`` が ``debug/OMakefile`` としてリンクされます。

.. The vmount model is fairly transparent. The OMakefiles can be written as if referring to files in the src/ directory—they need not be aware of mounting. However, there are a few points to keep in mind.

``vmount`` 関数の動作はだいぶ透過的です。あなたは ``OMakefile`` をまるで ``src/`` ディレクトリ内のファイルが関連付けられているかのように書くことができ、マウントについて気にする必要はありません。しかしながら、以下に示すいくつかの注意点を頭に入れておきましょう。

.. _label2.10:

2.10  注意点
--------------------
.. When using the vmount function for versioning, it wise to keep the source files distinct from the compiled versions. For example, suppose the source directory contained a file src/foo.o. When mounted, the foo.o file will be the same in all versions, which is probably not what you want. It is better to keep the src/ directory pristine, containing no compiled code.

バージョン管理の目的で ``vmount`` 関数を用いた場合、コンパイルされたファイルをソースファイルから分離することをお勧めします。例えば、ソースディレクトリに ``src/foo.o`` ファイルが含まれている場合を考えましょう。もし ``src/foo.o`` がマウントされてしまったとすると、 ``foo.o`` ファイルはすべてのバージョンにおいて共通のファイルになってしまい、おそらくあなたが求めていた動作とは違うものになるでしょう。 ``src/`` ディレクトリにはソースコード以外何もない状態にして、コンパイルされたコードは含めないようにしましょう。

.. When using the vmount -l option, files are linked into the version directory only if they are referenced in the project. Functions that examine the filesystem (like $(ls ...)) may produce unexpected results. 

``vmount -l`` オプションを使用したときは、ソースファイルがプロジェクトから参照された場合のみ、バージョンディレクトリ内にリンクされます。ファイルシステムを用いる関数( ``$(ls ...)`` など)はあなたが期待していない動作を引き起こすことになります。