# 2 `distutils.ccompiler` -- CCompiler ベースクラス

このモジュールは `CCompiler`クラスの抽象ベースクラスを提供します。 `CCompiler`のインスタンスはプロジェクトにおける全てのコンパイルお よびリンクに使われます。 コンパイラのオプションを設定するためのメソッドが提供されます -- マク ロ定義、includeディレクトリ、リンクパス、ライブラリなど。

このモジュールは以下の関数を提供します。

`gen_lib_options`( | compiler, library_dirs, runtime_library_dirs, libraries)

  ライブラリを探索するディレクトリ、特定のライブラリとのリンクをするための リンカオプションを生成します。 libraries と library_dirs はそれぞれライブラリ名(ファイル 名ではありません!)のリストと、探索ディレクトリのリストです。 compilerで利用できるコマンドラインオプションのリスト(指定されたフォーマット文字列に依存します)を返します。

`gen_preprocess_options`( | macros, include_dirs)

  Cプリプロセッサオプション(-D, -U, -I)を生成します。これらは少なくとも2 つのコンパイラで利用可能です。典型的な Unix のコンパイラと、Visual C++です。 macrosは1または2要素のタプルで(name,)はnameマクロの削除 (-U)を意味し、 (name,value)はnameマクロをvalueとして 定義(-D)します。include_dirsはディレクトリ名のリストで、ヘッダファ イルのサーチパスに追加されます(-I)。 Unix のコンパイラと、Visual C++で利用できるコマンドラインオプショ ンのリストを返します。

`get_default_compiler`( | osname, platform)

  指定されたプラットフォームのデフォルトコンパイラを返します。

  問い合わせのosnameはPython標準のOS名(os.nameで返されるもの)のひとつであるべき で、platformはsys.platformで返される共通の値です。

  パラメータが指定されていない場合のデフォルト値は`os.name`と `sys.platform`です。

`new_compiler`( | plat=`None`, compiler=`None`, verbose=`0`, dry_run=`0`, force=`0`)

  指定されたプラットフォーム/コンパイラの組み合わせ向けに、 CCompilerサブクラスのインスタンスを生成するファクトリ関数です。 plat のデフォルト値は `os.name` (例: `'posix'`, `'nt'`), compiler)、 compilerのデフォルト値はプラトフォームのデフォルトコンパイラです。 現在は `'posix'`と`'nt'`だけがサポートされています、デフォルトのコンパイラは ``traditional Unix interface''(`UnixCCompiler`クラス) と、 Visual C++(`MSVCCompiler` クラス) です。 WindowsでUnixコンパイラオブジェクトを要求することも、UnixでMicrosoft コンパイラオブジェクトを要求することも可能です。compiler引数を与えると platは無視されます。

`show_compilers`( | )

  利用可能なコンパイラのリストを表示します(`build`, `build_ext`, `build_clib`の、--help-compilerオプションで使われます。)

クラス `CCompiler`( | [verbose=`0`, dry_run=`0`, force=`0`])

  抽象ベースクラス `CCompiler`は実際のコンパイラクラスで実装される必要のある インタフェースを定義しています。このクラスはコンパイラクラスで利用されるユーティリティメソッドも定義しています。

  コンパイラ抽象クラスの基本的な前提は、各インスタンスはあるプロジェクトを ビルドするときの全コンパイル/リンクで利用できるということです。 そこで、コンパイルとリンクステップで共通する属性 -- インクルードディレクトリ、マクロ定義、リンクするライブラリ など -- はコンパイラインスタンスの 属性になります。 どのように各ファイルが扱われるかを変更できるように、ほとんどの 属性はコンパイルごと、またはリンクごとに与えることができます。

  各サブクラスのコンストラクタは Compiler クラスのインスタンスを作ります。 フラグは verbose(冗長な出力を表示します)、 dry_run(実際にはそのステップを実行しません)、 そしてforce(依存関係を無視して全て再ビルドします)です。 これらのフラグは全てデフォルト値が`0`(無効)になっています。 `CCompiler`またはサブクラスを直接インスタンス化したくない場合には、 かわりに`distutils.CCompiler.new_compiler()`ファクトリ関数を利用してください。

  以下のメソッドで、Compilerクラスのインスタンスが使うコンパイラオプションを手動で変更できます。

  `add_include_dir`( | dir)

    dirをヘッダファイル探索ディレクトリのリストに追加します。 コンパイラは`add_include_dir()`を呼び出した順にディレクトリを 探索するよう指定されます。

  `set_include_dirs`( | dirs)

    探索されるディレクトリのリストを dirs (文字列のリスト)に設定します。 先に実行された `add_include_dir()`は上書きされます。 後で実行する`add_include_dir()`は`set_include_dirs()`の リストにディレクトリを追加します。これはコンパイラがデフォルトで探索する 標準インクルードディレクトリには影響しません。

  `add_library`( | libname)

    libnameをコンパイラオブジェクトによるリンク時に使われる ライブラリのリストに追加します。libnameはライブラリを含むファイル名ではなく、 ライブラリそのものの名前です: 実際のファイル名はリンカ、コンパイラ、または コンパイラクラス(プラットフォームに依存します)から推測されます。

    リンカは`add_library()`と`set_library()` で渡された順にライブラリをリンクしようとします。ライブラリ名が重なることは 問題ありません。リンカは指定された回数だけライブラリとリンクしようとします。

  `set_libraries`( | libnames)

    コンパイラオブジェクトによるリンク時に使われるライブラリのリストを libnames(文字列のリスト)に設定します。 これはリンカがデフォルトでリンクする標準のシステムライブラリには影響しません。

  `add_library_dir`( | dir)

    `add_library()` と `set_libraries()`で指定された ライブラリを探索するディレクトリのリストにdirを追加します。 リンカは`add_library_dir()`と `set_library_dirs()`で 指定された順にディレクトリを探索されます。

  `set_library_dirs`( | dirs)

    ライブラリを探索するディレクトリを dirs(文字列のリスト)に設定します。 これはリンカがデフォルトで探索する標準ライブラリ探索パスには影響しません。

  `add_runtime_library_dir`( | dir)

    実行時に共有ライブラリを探索するディレクトリのリストにdirを追加します。

  `set_runtime_library_dirs`( | dirs)

    実行時に共有ライブラリを探索するディレクトリのリストをdirに設定します。 これはランタイムリンカがデフォルトで利用する標準探索パスには影響しません。

  `define_macro`( | name[, value=`None`])

    このコンパイラオブジェクトで実行される全てのコンパイルで利用される プリプロセッサのマクロを定義します。省略可能なパラメータvalueは 文字列であるべきです。省略された場合は、マクロは特定の値をとらずに定義され、 具体的な結果は利用されるコンパイラに依存します。 (XXX 本当に? これについてANSIで言及されている?)

  `undefine_macro`( | name)

    このコンパイラオブジェクトで実行される全てのコンパイルで利用される プリプロセッサのマクロ定義を消します。同じマクロを`define_macro()`で 定義し、`undefine_macro()`で定義を削除した場合、後で呼び出されたものが 優先される(複数の再定義と削除を含みます)。 もしコンパイルごと(すなわち`compile()`の呼び出しごと)にマクロが再定義/削除 される場合も後で呼び出されたものが優先されます。

  `add_link_object`( | object)

    このコンパイラオブジェクトによる全てのリンクで利用される オブジェクトファイル(または類似のライブラリファイルや ``リソースコンパイラ''の出力)のリストにobjectを追加します。

  `set_link_objects`( | objects)

    このコンパイラオブジェクトによる全てのリンクで利用される オブジェクトファイル(または類似のもの)のリストをobjectsに設定します。 これはリンカがデフォルト利用する標準オブジェクトファイル(システムライブラリ など)には影響しません。

  以下のメソッドはコンパイラオプションの自動検出を実装しており、 GNU autoconfに似たいくつかの機能を提供します。

  `detect_language`( | sources)

    与えられたファイルまたはファイルのリストの言語を検出します。 インスタンス属性`language_map`(辞書)と、 `language_order` (リスト)を仕事に使います。

  `find_library_file`( | dirs, lib[, debug=`0`])

    指定されたディレクトリのリストから、スタティックまたは共有ライブラリファイル libを探し、そのファイルのフルパスを返します。 もしdebugが真なら、(現在のプラットフォームで意味があれば)デバッグ版を探します。 指定されたどのディレクトリでも lib が見つからなければ `None`を返します。

  `has_function`( | funcname [, includes=`None`, include_dirs=`None`, libraries=`None`, library_dirs=`None`])

    funcnameが現在のプラットフォームでサポートされているかどうかをブール値で返します。 省略可能引数は追加のインクルードファイルやパス、 ライブラリやパスを与えることでコンパイル環境を指定します。

  `library_dir_option`( | dir)

    dirをライブラリ探索ディレクトリに追加する コンパイラオプションを返します。

  `library_option`( | lib)

    共有ライブラリまたは実行ファイルにリンクされるライブラリ一覧にlibを追加する コンパイラオプションを返します。

  `runtime_library_dir_option`( | dir)

    ランタイムライブラリを検索するディレクトリのリストに dirを追加するコンパイラオプションを返します。

  `set_executables`( | **args)

    コンパイルのいろいろなステージで実行される実行ファイル(とその引数)を定 義します。コンパイラクラス(の 'executables' 属性)によって実行ファイル のセットは変わる可能性がありますが、ほとんどは以下のものを持っています:

    attribute | description
    --- | ---
    compiler | C/C++ コンパイラ
    linker_so | シェアードオブジェクト、ライブラリを作るために使う リンカ
    linker_exe | バイナリ実行可能ファイルを作るために使うリンカ
    archiver | 静的ライブラリを作るアーカイバ

    コマンドラインをもつプラットフォーム(Unix, DOS/Windows)では、それぞれ の文字列は実行ファイル名と(省略可能な)引数リストに分割されます。(文字 列の分割は Unix のシェルが行うものに似ています: 単語はスペースで区 切られますが、クォートとバックスラッシュでオーバーライドできます。 `distutils.util.split_quoted()`をごらんください。)

  以下のメソッドはビルドプロセスのステージを呼び出します。

  `compile`( | sources[, output_dir=`None`, macros=`None`, include_dirs=`None`, debug=`0`, extra_preargs=`None`, extra_postargs=`None`, depends=`None`])

    1つ以上のソースファイルをコンパイルします。オブジェクトファイルを生成 (たとえば .c ファイルを .oファイルに変換)します。

    sources はファイル名のリストである必要があります。おそらく C/C++ ファイルですが、実際にはコンパイラとコンパイラクラスで扱えるもの(例: `MSVCCompiler`はリソースファイルを sourcesにとることができ ます)なら何でも指定できます。 sourcesのソースファイルひとつずつ に対応するオブジェクトファイル名のリストを返します。実装に依存しますが、 全てのソースファイルがコンパイルされる必要はありません。しかし全ての対 応するオブジェクトファイル名が返ります。

    もし output_dirが指定されていれば、オブジェクトファイルはその下 に、オリジナルのパスを維持した状態で置かれます。 つまり、 foo/bar.cは通常コンパイルされてfoo/bar.oになります (Unix実装の場合)が、もしoutput_dirが buildであれば、 build/foo/bar.oになります。

    macrosは(もし指定されていれば)マクロ定義のリストである必要があり ます。 マクロ定義は(name, value)という形式の2要素のタプル、または (name,)という形式の1要素のタプルのどちらかです。前者はマクロを定 義します。もしvalueが`None`であれば、マクロは特定の値をもたないで 定義されます。1要素のタプルはマクロ定義を削除します。後で実行された定 義/再定義/削除が優先されます。

    include_dirsは(もし指定されていれば)文字列のリストである必要があ ります。このコンパイルだけで有効な、デフォルトのインクルードファイル の検索ディレクトリに追加するディレクトリ群を指定します。

    debugはブーリアン値です。もし真なら、コンパイラはデバッグシンボ ルをオブジェクトファイルに(または別ファイルに)出力します。

    extra_postargsとextra_postargsは実装依存です。 コマンドラインをもっているプラットフォーム(例 Unix, DOS/Windows)では、 おそらく文字列のリスト: コンパイラのコマンドライン引数の前/後に追加す るコマンドライン引数です。他のプラットフォームでは、実装クラスのドキュ メントを参照してください。どの場合でも、これらの引数は抽象コンパイラフ レームワークが期待に沿わない時の脱出口として意図されています。

    dependsは(もし指定されていれば)ターゲットが依存しているファイル 名のリストです。ソースファイルが依存しているファイルのどれかより古けれ ば、ソースファイルは再コンパイルされます。これは依存関係のトラッキング をサポートしていますが、荒い粒度でしか行われません。

    失敗すると`CompileError`を起こします。

  `create_static_lib`( | objects, output_libname[, output_dir=`None`, debug=`0`, target_lang=`None`])

    静的ライブラリファイルを作るために元ファイル群をリンクします。 「元ファイル群」はobjectsで指定されたオブジェクトファイルのリス トを基礎にしています。追加のオブジェクトファイルを `add_link_object()` および/または `set_link_objects()` で指定し、追加のライブラリを`add_library()` および/または `set_libraries()`で指定します。そしてlibrariesで指定され たライブラリです。

    output_libnameはライブラリ名で、ファイル名ではありません; ファイ ル名はライブラリ名から作られます。output_dirはライブラリファイル が起かれるディレクトリです。

    debugはブール値です。真なら、デバッグ情報がライブラリに含まれま す(ほとんどのプラットフォームではコンパイルステップで意味をもちます: debugフラグは一貫性のためにここにもあります。)。

    target_lang はオブジェクトがコンパイルされる対象になる言語です。 これはその言語特有のリンク時の処理を可能にします。

    失敗すると `LibError` を起こします。

  `link`( | target_desc, objects, output_filename[, output_dir=`None`, libraries=`None`, library_dirs=`None`, runtime_library_dirs=`None`, export_symbols=`None`, debug=`0`, extra_preargs=`None`, extra_postargs=`None`, build_temp=`None`, target_lang=`None`])

    実行ファイルまたは共有ライブラリファイルを作るために元ファイル群をリンクします。

    「元ファイル群」はobjectsで指定されたオブジェクトファイルのリス トを基礎にしています。output_filename はファイル名です。もし output_dirが指定されていれば、それに対する相対パスとして output_filenameは扱われます(必要ならばoutput_filename はディ レクトリ名を含むことができます。)。

    librariesはリンクするライブラリのリストです。 これはファイル名ではなくライブラリ名で指定します。プラットフォーム依存 の方式でファイル名に変換されます(例: foo はUnix では libfoo.a に、DOS/Windowsでは foo.lib になります。 )。ただしこれらはディレクト リ名を含むことができ、その場合はリンカは通常の場所全体を探すのではなく 特定のディレクトリを参照します。

    library_dirsはもし指定されるならば、修飾されていない(ディレクト リ名を含んでいない)ライブラリ名で指定されたライブラリを探索する ディレクトリのリストです。これはシステムのデフォルトより優先され、 `add_library_dir()` と/または `set_library_dirs()`に渡さ れます。runtime_library_dirsは共有ライブラリに埋め込まれるディレ クトリのリストで、実行時にそれが依存する共有ライブラリのパスを指定しま す(これはUnixでだけ意味があるかもしれません。)。

    export_symbolsは共有ライブラリがエクスポートするシンボルのリストです。 (これはWindowsだけで意味があるようです。)

    debugは `compile()` や `create_static_lib()`と同じですが、 少しだけ違いがあり、(`create_static_lib()`ではdebugフラグ は形式をあわせるために存在していたのに対して)ほとんどのプラットフォー ムで意識されます。

    extra_preargs と extra_postargs は `compile()` と同じですが、コンパイラではなくリンカへの引数として扱われます。

    target_langは指定されたオブジェクトがコンパイルされた対象言語で す。リンク時に言語特有の処理を行えるようにします。

    失敗すると `LinkError` が起きます。

  `link_executable`( | objects, output_progname[, output_dir=`None`, libraries=`None`, library_dirs=`None`, runtime_library_dirs=`None`, debug=`0`, extra_preargs=`None`, extra_postargs=`None`, target_lang=`None`])

    実行ファイルをリンクします。 output_prognameは実行ファイルの名前です。objectsはリンクさ れるオブジェクトのファイル名のリストです。他の引数は`link`メソッドと同 じです。

  `link_shared_lib`( | objects, output_libname[, output_dir=`None`, libraries=`None`, library_dirs=`None`, runtime_library_dirs=`None`, export_symbols=`None`, debug=`0`, extra_preargs=`None`, extra_postargs=`None`, build_temp=`None`, target_lang=`None`])

    共有ライブラリをリンクします。output_libnameは出力先のライブラリ 名です。objectsはリンクされるオブジェクトのファイル名のリストで す。他の引数は`link`メソッドと同じです。

  `link_shared_object`( | objects, output_filename[, output_dir=`None`, libraries=`None`, library_dirs=`None`, runtime_library_dirs=`None`, export_symbols=`None`, debug=`0`, extra_preargs=`None`, extra_postargs=`None`, build_temp=`None`, target_lang=`None`])

    共有オブジェクトをリンクします。output_filenameは出力先の共有オ ブジェクト名です。objectsはリンクされるオブジェクトのファイル名のリストで す。他の引数は`link`メソッドと同じです。

  `preprocess`( | source[, output_file=`None`, macros=`None`, include_dirs=`None`, extra_preargs=`None`, extra_postargs=`None`])

    sourceで指定されたひとつの C/C++ソースファイルをプリプロセスします。 出力先のファイルは output_fileか、もし output_fileが指定さ れていなければ stdout になります。 macroは`compile()`と同様にマクロ定義のリストで、 `define_macro()` や `undefine_macro()`によって引数になります。 include_dirsはデフォルトのリストに追加されるディレクトリ名のリス トで、`add_include_dir()`と同じ方法で扱われます。

    失敗すると `PreprocessError` が起きます。

  以下のユーティリティメソッドは具体的なサブクラスで使うために、 `CCompiler`クラスで定義されています。

  `executable_filename`( | basename[, strip_dir=`0`, output_dir=`''`])

    basenameで指定された実行ファイルのファイル名を返します。 Windows以外の典型的なプラットフォームではbasenameそのままが、Windowsで は .exeが追加されたものが返ります。

  `library_filename`( | libname[, lib_type=`'static'`, strip_dir=`0`, output_dir=`''`])

    現在のプラットフォームでのライブラリファイル名を返します。 Unixでlib_typeが`'static'`の場合、liblibname.aの 形式を返し、lib_type が `'dynamic'` の場合は liblibname.soの形式を返します。

  `object_filenames`( | source_filenames[, strip_dir=`0`, output_dir=`''`])

    指定されたソースファイルに対応するオブジェクトファイル名を返します。 source_filenames はファイル名のリストです。

  `shared_object_filename`( | basename[, strip_dir=`0`, output_dir=`''`])

    basenameに対応する共有オブジェクトファイルのファイル名を返します。

  `execute`( | func, args[, msg=`None`, level=`1`])

    `distutils.util.execute()`を呼びだします。このメソッドは ログを取り、dry_runフラグを考慮にいれて、 Python関数funcに引数argsを与えて呼びだします。

  `spawn`( | cmd)

    `distutils.util.spawn()`を呼び出します。これは指定したコマン ドを実行する外部プロセスを呼び出します。

  `mkpath`( | name[, mode=`511`])

    `distutils.dir_util.mkpath()`を呼び出します。これは 親ディレクトリ込みでディレクトリを作成します。

  `move_file`( | src, dst)

    `distutils.file_util.move_file()`を呼び出します。 src をdstにリネームします。

  `announce`( | msg[, level=`1`])

    `distutils.log.debug()`関数を使ってメッセージを書き出します。

  `warn`( | msg)

    警告メッセージmsgを標準エラー出力に書き出します。

  `debug_print`( | msg)

    もしこの `CCompiler`インスタンスで debugフラグが指定されて いればmsgを標準出力に出力し、そうでなければ何も出力しません。