# 9. API リファレンス

参考

setuptools で新規追加または変更された setup.py の引数

  `setuptools` プロジェクトは `setup` 関数や他の API に新しい機能を追加したり、異なる Python バージョンの間で API に一貫性を持たせているため、 `distutils` の代替として推奨されています。

注釈

このドキュメントは、 https://setuptools.readthedocs.io/en/latest/setuptools.html にある `setuptools` のドキュメントが現時点でここにある関連情報を全て網羅するまで、単独でここに載せておかれます。

## 9.1. `distutils.core` --- Distutils のコア機能

Distutilsを使うためにインストールする必要がある唯一のモジュールが `distutils.core` モジュールです。 `setup()` 関数 (セットアップスクリプトから呼び出されます)を提供します。間接的に `distutils.dist.Distribution` クラスと `distutils.cmd.Command` クラスを提供します。

distutils.core.setup(arguments)

  全てを実行する基本的な関数で、Distutilsでできるほとんどのことを実行します。

  setup関数はたくさんの引数をとります。以下のテーブルにまとめます。

  引数名 | value | type
  --- | --- | ---
  name | パッケージの名前 | 文字列
  version | パッケージのバージョン番号。 `distutils.version` を参照 | 文字列
  description | 1行で書いたパッケージ解説 | 文字列
  long_description | パッケージの長い解説 | 文字列
  author | パッケージ作者の名前 | 文字列
  author_email | パッケージ作者のemailアドレス | 文字列
  maintainer | 作者と違う場合の、現在のメンテナーの名前です。 maintainer 引数が与えられた場合、 distutils は `PKG-INFO` で作者として使用します | 文字列
  maintainer_email | 現在のメンテナのemailアドレス(パッケージ作者と異なる場合) | 文字列
  url | パッケージのURL(ホームページ) | 文字列
  download_url | パッケージダウンロード用URL | 文字列
  packages | distutilsが操作するPythonパッケージのリスト | 文字列のリスト
  py_modules | distutilsが操作するPythonモジュールのリスト | 文字列のリスト
  scripts | ビルドおよびインストールする単体スクリプトファイルのリスト | 文字列のリスト
  ext_modules | ビルドする拡張モジュール | `distutils.core.Extension` のインスタンスのリスト
  classifiers | パッケージのカテゴリのリスト | 文字列のリスト。有効な classifier のリストは PyPI を参照。
  distclass | 使用する `Distribution` クラス | `distutils.core.Distribution` のサブクラス
  script_name | setup.pyスクリプトの名前 - デフォルトでは `sys.argv[0]` | 文字列
  script_args | setup スクリプトの引数 | 文字列のリスト
  options | セットアップスクリプトのデフォルト引数 | 辞書
  license | パッケージのライセンス | 文字列
  keywords | 説明用メタデータ。 PEP 314 を参照してください | 文字列のリスト、またはカンマ区切り文字列
  platforms |  | 文字列のリスト、またはカンマ区切り文字列
  cmdclass | コマンド名から `Command` サブクラスへのマッピング | 辞書
  data_files | インストールするデータファイルのリスト | リスト
  package_dir | パッケージからディレクトリ名へのマッピング | 辞書

distutils.core.run_setup(script_name[, script_args=None, stop_after='run'])

  制御された環境でセットアップスクリプトを実行し、いろいろなものを操作する `distutils.dist.Distribution` クラスのインスタンスを返します。これはディストリビューションのメタデータ(キーワード引数 script として関数 `setup()` に渡される)を参照したり、設定ファイルやコマンドラインの内容を調べる時に便利です。

  script は `exec()` で読み込まれるファイルです。 `sys.argv[0]` は、呼び出しのために script_name と置換されます。 script_args は文字列のリストです。もし提供されていた場合、 `sys.argv[1:]` は、呼び出しのために script_args で置換されます。

  stop_after はいつ動作を停止するか関数 `setup()` に伝えます。とりうる値は:

  value | description
  --- | ---
  init | `Distribution` インスタンスを作成し、キーワード引数を `setup()` に渡したあとに停止する。
  config | 設定ファイルをパーズしたあと停止する(そしてそのデータは `Distribution` インスタンスに保存される)。
  commandline | コマンドライン (`sys.argv[1:]` または script_args) がパーズされたあとに停止する (そしてそのデータは `Distribution` インスタンスに保存される)。
  run | 全てのコマンドを実行したあとに停止する(関数 `setup()` を通常の方法で呼び出した場合と同じ)。デフォルト値。

これに加えて、 `distutils.core` モジュールは他のモジュールにあるいくつかのクラスを公開しています。

- `distutils.extension` から `Extension`

- `distutils.cmd` から `Command`

- `distutils.dist` から `Distribution`

それぞれの簡単な説明を以下に記します。完全な説明についてはそれぞれのモジュールをごらんください。

class distutils.core.Extension

  Extension クラスは、セットアップスクリプト中で C または C++ 拡張モジュールを表します。 コンストラクタで以下のキーワード引数をとります:

  引数名 | value | type
  --- | --- | ---
  name | 拡張のフルネーム(パッケージを含む) --- ファイル名やパス名では なく 、Pythonのピリオド区切りの名前 | 文字列
  sources | ソースファイル名のリスト。配布物ルートディレクトリ (setupスクリプトのある場所) からの相対パス、プラットフォーム独立のため Unix 形式(スラッシュで区切る)で記述します。ソースファイルは C, C++, SWIG (.i)、特定プラットフォーム用のリソースファイル、その他 build_ext コマンドがソースファイルだと認識するどの形式でもありえます。 | 文字列のリスト
  include_dirs | C/C++ヘッダファイルを検索するディレクトリのリスト(プラットフォーム独立のため Unix 形式で記述する) | 文字列のリスト
  define_macros | 定義するマクロのリスト; それぞれのマクロは2要素のタプル `(name, value)` で定義されます。 value には定義しようとしている文字列、または内容なしで定義する場合は `None` (ソースコード中で `#define FOO` と書く、または Unix Cコンパイラのコマンドラインで `-DFOO` を指定するのと等価です) を指定します | タプルのリスト
  undef_macros | 定義を消すマクロのリスト | 文字列のリスト
  library_dirs | リンク時にC/C++ライブラリを検索するディレクトリのリスト | 文字列のリスト
  libraries | リンクするライブラリ名のリスト (ファイル名やパスではない) | 文字列のリスト
  runtime_library_dirs | 実行時(shared extensionでは、拡張が読み込まれる時)に C/C++ライブラリを探索するディレクトリのリスト | 文字列のリスト
  extra_objects | 追加でリンクするファイル('sources'に対応するコードが含まれていないファイル、バイナリ形式のリソースファイルなど)のリスト | 文字列のリスト
  extra_compile_args | 'sources'のソースをコンパイルする時に追加するプラットフォーム特有またはコンパイラ特有の情報コマンドラインを利用できるプラットホームとコンパイラでは、これは通常コマンドライン引数のリストですが、他のプラットホームでも、それは何かに使えます。 | 文字列のリスト
  extra_link_args | オブジェクトファイルをリンクして拡張(または新しいPythonインタプリタ)を作る時に追加するプラットフォーム特有またはコンパイラ特有の情報 'extra_compile_args'に似た実装です。 | 文字列のリスト
  export_symbols | shared extensionからエクスポートされるシンボルのリスト。全てのプラットフォームでは使われず、 Python拡張(典型的には `init` + extension_name という1つのシンボルだけエクスポートする)に一般的に必要なものでもない。 | 文字列のリスト
  depends | 拡張が依存するファイルのリスト | 文字列のリスト
  language | 拡張の言語 (例: `'c'`, `'c++'`, `'objc'`)。指定しなければソースの拡張子で検出される。 | 文字列
  optional | 拡張で起きたビルド失敗によってビルドプロセスを中断せず、単にその拡張を無視して処理を進めるように指定します。 | ブール値

  バージョン 3.8 で変更: Android と Cygwin を除き、 Unix では C 拡張モジュールは libpython とリンクされなくなりました。

class distutils.core.Distribution

  `Distribution` はPythonソフトウェアパッケージをどのようにビルド、インストール、パッケージするかを定義する。

  Distribution のコンストラクタが取りうるキーワード引数のリストに関しては、 `setup()` 関数を見てください。 `setup()` は Distribution のインスタンスを作ります。

  バージョン 3.7 で変更: `classifiers`, `keywords`, `platforms` のフィールドがリストもしくは文字列で指定されていなかった場合、 `Distribution` が警告を出すようになりました。

class distutils.core.Command

  `Command` クラス(そのサブクラスのインスタンス)はdistutilsのあるコマンドを実装します。

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

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

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

distutils.ccompiler.gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)

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

distutils.ccompiler.gen_preprocess_options(macros, include_dirs)

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

distutils.ccompiler.get_default_compiler(osname, platform)

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

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

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

distutils.ccompiler.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 は無視されます。

distutils.ccompiler.show_compilers()

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

class distutils.ccompiler.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_libraries()` で渡された順にライブラリをリンクしようとします。ライブラリ名が重なることは問題ありません。リンカは指定された回数だけライブラリとリンクしようとします。

  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)

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

  define_macro(name[, value=None])

    このコンパイラオブジェクトで実行される全てのコンパイルで利用されるプリプロセッサのマクロ定義を行います。オプション引数 value は文字列でなければなりません; それが指定されない場合は、特定の値を持たないマクロが定義され、実際の値は使っているコンパイラに依存します。

  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' 属性)によって実行ファイルのセットは変わる可能性がありますが、ほとんどは以下のものを持っています:

    属性 | 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_preargs と 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 になります。 macros は `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 を標準出力に出力し、そうでなければ何も出力しません。

## 9.3. `distutils.unixccompiler` --- Unix C コンパイラ

このモジュールは `UnixCCompiler` クラスを提供します。 `CCompiler` クラスのサブクラスで、典型的なUnixスタイルのコマンドラインCコンパイラを扱います:

- マクロは `-Dname[=value]` で定義されます

- マクロは `-Uname` で削除されます

- インクルードファイルの探索ディレクトリは `-Idir` で指定されます

- ライブラリは `-llib` で指定されます

- ライブラリの探索ディレクトリは `-Ldir` で指定されます

- コンパイルは cc (またはそれに似た) 実行ファイルに、 `-c` オプションをつけて実行します: `.c` を `.o` にコンパイルします

- 静的ライブラリは ar コマンドで処理されます (ranlib を使うかもしれません)

- 共有ライブラリのリンクは cc `-shared` で処理されます

## 9.4. `distutils.msvccompiler` --- Microsoft コンパイラ

このモジュールは `MSVCCompiler` クラスを提供します。抽象クラス `CCompiler` の具象クラスでMicrosoft Visual Studio向けのものです。一般的に、拡張モジュールはPythonをコンパイルしたのと同じコンパイラでコンパイルする必要があります。Python 2.3 やそれ以前では、コンパイラはVisual Studio 6でした。 Python 2.4 と Python 2.5 では、コンパイラは Visual Studio .NET 2003 です。

`MSVCCompiler` は大体正しいコンパイラ、リンカその他を選びます。この選択を上書きするためには、環境変数 DISTUTILS_USE_SDK と MSSdk の両方を設定する必要があります。 MSSdk は現在の環境をセットアップした `SetEnv.Cmd` スクリプト、もしくは環境変数がSDKをインストールした時に登録されたものであることを示します。 DISTUTILS_USE_SDK はdistutilsのユーザーが明示的に `MSVCCompiler` が選んだコンパイラを上書きすることを示します。

## 9.5. `distutils.bcppcompiler` --- Borland コンパイラ

このモジュールは `BorlandCCompiler` クラスを提供します。抽象クラス `CCompiler` の具象クラスでBorland C++ コンパイラ向けです。

## 9.6. `distutils.cygwincompiler` --- Cygwin コンパイラ

このモジュールは `CygwinCCompiler` クラスを提供します。 `UnixCCompiler` のサブクラスで Cygwinに移植されたWindows用の GNU C コンパイラ向けです。さらに Mingw32CCompiler クラスを含んでおり、これは mingw32 向けに移植された GCC (cygwinの no-cygwin モードと同じ)向けです。

## 9.7. `distutils.archive_util` --- アーカイブユーティリティ

このモジュールはアーカイブファイル(tarやzip)を作成する関数を提供します。

distutils.archive_util.make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])

  アーカイブファイル(例: `zip` や `tar`)を作成します。 base_name は作成するファイル名からフォーマットの拡張子を除いたものです。 format はアーカイブのフォーマットで `zip`, `tar`, `gztar`, `bztar`, `xztar`, `ztar` のいずれかです。 root_dir はアーカイブのルートディレクトリになるディレクトリです: つまりアーカイブを作成する前に root_dir に `chdir` します。 base_dir はアーカイブの起点となるディレクトリです: つまり base_dir はアーカイブ中の全ファイルおよびディレクトリの前につくディレクトリ名です。 root_dir と base_dir はともにカレントディレクトリがデフォルト値です。アーカイブファイル名を返します。

  バージョン 3.5 で変更: `xztar` 形式のサポートが追加されました。

distutils.archive_util.make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])

  base_dir 以下の全ファイルから、 tar ファイルを作成 (オプションで圧縮) します。 compress は `'gzip'` (デフォルト), `'xz'`, `'compress'`, `'bzip2'` または `None` である必要があります。 `'compress'` メソッドについては、 compress で指定される圧縮ユーティリティにパスが通っている必要があるので、おそらくこれは Unix だけで有効でしょう。出力 tar ファイルは `base_dir.tar` という名前になり、圧縮によって拡張子が付きます(`.gz`, `.bz2`, `.xz` または `.Z`)。出力ファイル名が返ります。

  バージョン 3.5 で変更: `xz` 形式のサポートが追加されました。

distutils.archive_util.make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])

  base_dir 以下の全ファイルから、zipファイルを作成します。出力されるzipファイルは base_name + `.zip` という名前になります。 `zipfile` Pythonモジュール(利用可能なら)またはInfoZIP `zip` ユーティリティ(インストールされていてパスが通っているなら)を使います。もしどちらも利用できなければ、 `DistutilsExecError` が起きます。出力zipファイル名が返ります。

## 9.8. `distutils.dep_util` --- 依存関係のチェック

このモジュールはシンプルなタイムスタンプを元にしたファイルやファイル群の依存関係を処理する関数を提供します。さらに、それらの依存関係解析を元にした関数を提供します。

distutils.dep_util.newer(source, target)

  source が存在して、 target より最近変更されている、または source が存在して、 target が存在していない場合は真を返します。両方が存在していて、 target のほうが source より新しいか同じ場合には偽を返します。 source が存在しない場合には `DistutilsFileError` を起こします。

distutils.dep_util.newer_pairwise(sources, targets)

  ふたつのファイル名リストを並列に探索して、それぞれのソースが対応するターゲットより新しいかをテストします。 `newer()` の意味でターゲットよりソースが新しいペアのリスト(sources, targets)を返します。

distutils.dep_util.newer_group(sources, target[, missing='error'])

  target が、 sources にリストアップされたどれかのファイルより古ければ真を返します。 言い換えれば、 target が存在して sources にある全てのファイルより新しいなら偽を返し、そうでなければ真を返します。 missing はソースファイルが存在しなかった時の振る舞いを決定します。デフォルト(`'error'`)は `os.stat()` 関数の内部で発生した `OSError` 例外を投げます。 `'ignore'` の場合は、単に存在しないソースファイルを無視します。 `'newer'` の場合は、存在しないソースファイルについては target が古いとみなします(これは "dry-run" モードで便利です: 入力がないのでコマンドは実行できませんが実際に実行しようとしていないので問題になりません)。

## 9.9. `distutils.dir_util` --- ディレクトリツリーの操作

このモジュールはディレクトリとディレクトリツリーを操作する関数を提供します。

distutils.dir_util.mkpath(name[, mode=0o777, verbose=0, dry_run=0])

  ディレクトリと、必要な親ディレクトリを作成します。もしディレクトリが既に存在している(name が空文字列の場合、カレントディレクトリを示すのでもちろん存在しています)場合、何もしません。ディレクトリを作成できなかった場合(例: ディレクトリと同じ名前のファイルが既に存在していた)、 `DistutilsFileError` を起こします。もし verbose が真なら、それぞれのmkdirについて1行、標準出力に出力します。実際に作成されたディレクトリのリストを返します。

distutils.dir_util.create_tree(base_dir, files[, mode=0o777, verbose=0, dry_run=0])

  files を置くために必要な空ディレクトリを base_dir 以下に作成します。 base_dir ディレクトリは存在している必要はありません。 files はファイル名のリストで base_dir からの相対パスとして扱われます。 base_dir + files のディレクトリ部分が(既に存在していなければ)作成されます。 mode, verbose と dry_run フラグは `mkpath()` と同じです。

distutils.dir_util.copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])

  src ディレクトリツリー全体を dst にコピーします。 src と dst はどちらもディレクトリ名である必要があります。もし src がディレクトリでなければ、 `DistutilsFileError` を起こします。もし dst が存在しなければ、 `mkpath()` で作成されます。実行結果は、 src 以下の全てのファイルが dst にコピーされ、 src 以下の全てのディレクトリが dst に再帰的にコピーされます。コピーされた(またはされるはず)のファイルのリストを返します。返り値は update または dry_run に影響されません: src 以下の全ファイルを単に dst 以下に改名したリストが返されます。

  preserve_mode と preserve_times は `distutils.file_util.copy_file()` のものと同じです; それらは通常のファイルにのみ適用され、ディレクトリには適用されません。 preserve_symlinks が真の場合、シンボリックリンクはシンボリックリンクとしてコピーされます (サポートするプラットフォームでは!); そうでない (デフォルトの) 場合、シンボリックリンクの対象がコピーされます。 update と verbose は `copy_file()` のものと同じです。

  Files in src that begin with `.nfs` are skipped (more information on these files is available in answer D2 of the NFS FAQ page).

  バージョン 3.3.1 で変更: NFS ファイルは無視されます。

distutils.dir_util.remove_tree(directory[, verbose=0, dry_run=0])

  再帰的に directory とその下の全ファイルを削除します。エラーは無視されます (verbose が真の時は `sys.stdout` に出力されます)。

## 9.10. `distutils.file_util` --- 1ファイルの操作

このモジュールはそれぞれのファイルを操作するユーティリティ関数を提供します。

distutils.file_util.copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])

  ファイル src を dst にコピーします。 dst がディレクトリの場合、 src はそこへ同じ名前でコピーされます; そうでない場合は、ファイル名として扱われます。(もしファイルが存在するなら、容赦無く上書きされます。) preserve_mode が (デフォルト値の) 真の場合、ファイルのモード (タイプやパーミッション、その他プラットフォームがサポートするもの) もコピーされます。 preserve_times が (デフォルト値の) 真の場合、最終更新、最終アクセス時刻もコピーされます。update が真の場合、 src は dst が存在しない場合か、dst が存在して src より古い場合にだけコピーします。

  link は値を `'hard'` または `'sym'` に設定することでコピーのかわりにハードリンク(`os.link()` を使います)またはシンボリックリンク(`os.symlink()` を使います)を許可します。 `None` (デフォルト)の時には、ファイルはコピーされます。 link をサポートしていないシステムで有効にしないでください。 `copy_file()` はハードリンク、シンボリックリンクが可能かチェックしていません。ファイルの内容をコピーするために `_copy_file_contents()` を利用しています。

  `(dest_name, copied)` のタプルを返します: dest_name は出力ファイルの実際の名前、 copied はファイルがコピーされた(dry_run が真の時にはコピーされることになった)場合には真です。

distutils.file_util.move_file(src, dst[, verbose, dry_run])

  ファイル src を dst に移動します。もし dst がディレクトリなら、ファイルはそのディレクトリに同じ名前で移動されます。そうでなければ、 src は dst に単にリネームされます。新しいファイルの名前を返します。

  警告

  Unix ではデバイスをまたがる移動は `copy_file()` を利用して扱っています。他のシステムではどうでしょう？

distutils.file_util.write_file(filename, contents)

  filename を作成し、 contents (行末文字がない文字列のシーケンス)を書き込みます。

## 9.11. `distutils.util` --- その他のユーティリティ関数

このモジュールは他のユーティリティモジュールにあわないものを提供しています。

distutils.util.get_platform()

  現在のプラットフォームを示す文字列を返します。 これはプラットフォーム依存のビルドディレクトリやプラットフォーム依存の配布物を区別するために使われます。 典型的には、('os.uname()' のように) OSの名前とバージョン、アーキテクチャを含みますが、厳密にはOSに依存します。 例えば Linux ではカーネルのバージョンはそれほど重要ではありません。

  返される値の例:

  - `linux-i586`

  - `linux-alpha`

  - `solaris-2.6-sun4u`

  POSIX でないプラットフォームでは、今のところ単に `sys.platform` が返されます。

  macOS システムでは、 OS バージョンは、現在のOSバージョンではなく、実行するバイナリの最小バージョンを表しています。 (これは、Python をビルドするときの `MACOSX_DEPLOYMENT_TARGET` の値です。)

  macOS のユニバーサルバイナリビルドでは、アーキテクチャの値は現在のプロセッサではなく、ユニバーサルバイナリの状態を表しています。32bit ユニバーサルバイナリではアーキテクチャは `fat` で、64bit ユニバーサルバイナリではアーキテクチャは `fat64` で、4-way ユニバーサルバイナリではアーキテクチャは `universal` になります。Python 2.7 と Python 3.2 から 3-way ユニバーサルバイナリ (ppc, i386, x86_64) には `fat3` が i386 と x86_64 ユニバーサルバイナリには `intel` が使われるようになりました

  macOS で返される値の例:

  - `macosx-10.3-ppc`

  - `macosx-10.3-fat`

  - `macosx-10.5-universal`

  - `macosx-10.6-intel`

  AIX の場合、 Python 3.9 以降のバージョンでは "aix" に続く追加のフィールド (`'-'` で連結されます) として AIX のバージョン、リリースおよびテクノロジー・レベル (第1フィールド)、ビルド作成日 (第2フィールド)、ビットサイズ (第3フィールド) を含む文字列を返します。 Python 3.8 以前のバージョンでは追加のフィールドとして AIX のバージョンとリリース の1つだけを含む文字列を返していました。

  AIX における戻り値の例:

  - `aix-5307-0747-32` # AIX `oslevel -s`: 5300-07-00-0000 の32ビットビルド

  - `aix-7105-1731-64` # AIX `oslevel -s`: 7100-05-01-1731 の64ビットビルド

  - `aix-7.2` # Python 3.8 以前のレガシー形式

  バージョン 3.9 で変更: AIX プラットフォームの文字列形式はバージョンとリリース情報に加えて、テクノロジー・レベル、ビルド作成日、および ABI のビットサイズを含むようになりました。

distutils.util.convert_path(pathname)

  'pathname' をファイルシステムで利用できる名前にして返します。すなわち、'/'で分割し、現在のディレクトリセパレータで接続しなおします。セットアップスクリプト中のファイル名はUnixスタイルで提供され、実際に利用する前に変換する必要があるため、この関数が必要になります。もし pathname の最初または最後がスラッシュの場合、Unix的でないシステムでは `ValueError` が起きます。

distutils.util.change_root(new_root, pathname)

  pathname の前に new_root を追加したものを返します。もし pathname が相対パスなら、 `os.path.join(new_root,pathname)` と等価です。そうでなければ、 pathname を相対パスに変換したあと接続します。これはDOS/Windows ではトリッキーな作業になります。

distutils.util.check_environ()

  'os.environ'に、ユーザがconfigファイル、コマンドラインオプションなどで利用できることを保証している環境変数があることを確認します。現在は以下のものが含まれています:

  - `HOME` - ユーザのホームディレクトリ (Unix のみ)

  - `PLAT` - ハードウェアとOSを含む現在のプラットフォームの説明。 (`get_platform()` を参照)

distutils.util.subst_vars(s, local_vars)

  shell/Perlスタイルの変数置換を s について行います。全ての `$` に名前が続いたものは変数とみなされ、辞書 local_vars でみつかった値に置換されます。 local_vars で見つからなかった場合には `os.environ` で置換されます。 os.environ は最初にある値を含んでいることをチェックされます: `check_environ()` を参照。 local_vars or `os.environ` のどちらにも値が見つからなかった場合、 `ValueError` を起こします。

  これは完全な文字列挿入関数ではないことに注意してください。 `$variable` の名前には大小英字、数字、アンダーバーだけを含むことができます。 { } や ( ) を使った引用形式は利用できません。

distutils.util.split_quoted(s)

  文字列をUnixのシェルのようなルール(引用符やバックスラッシュの扱い)で分割します。つまり、バックスラッシュでエスケープされるか、引用符で囲まれていなければ各語はスペースで区切られます。一重引用符と二重引用符は同じ意味です。引用符もバックスラッシュでエスケープできます。 2文字でのエスケープシーケンスに使われているバックスラッシュは削除され、エスケープされていた文字だけが残ります。引用符は文字列から削除されます。語のリストが返ります。

distutils.util.execute(func, args[, msg=None, verbose=0, dry_run=0])

  外部に影響するいくつかのアクション(たとえば、ファイルシステムへの書き込み)を実行します。そのようなアクションは dry_run フラグで無効にする必要があるので特別です。この関数はその繁雑な処理を行います。関数と引数のタプル、(実行する「アクション」をはっきりさせるための)表示に使われる任意のメッセージを渡してください。

distutils.util.strtobool(val)

  真偽値をあらわす文字列を真(1)または偽(0)に変換します。

  真の値は `y`, `yes`, `t`, `true`, `on` そして `1` です。偽の値は `n`, `no`, `f`, `false`, `off` そして `0` です。 val が上のどれでもない時は `ValueError` を起こします。

distutils.util.byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])

  Python ソースファイル群をバイトコンパイルして `__pycache__` サブディレクトリ内に `.pyc` ファイルを出力します。(PEP 3147 と PEP 488 を参照) py_files はコンパイルするファイルのリストです; `.py` で終わらないファイルは単にスキップされます。 optimize は次のうちの 1 つでなければなりません:

  - `0` - 最適化しない

  - `1` - 通常の最適化 (`python -O` のように)

  - `2` - さらに最適化 (`python -OO` のように)

  もし force が真なら、全てのファイルがタイムスタンプに関係なく再コンパイルされます。

  バイトコード ファイルにエンコードされるソースファイル名は、デフォルトでは py_files が使われます。これを prefix と basedir で変更することができます。 prefix はそれぞれのソースファイル名から削除される文字列で、 base_dir は(prefix を削除したあと)先頭に追加されるディレクトリ名です。任意に prefix と base_dir のどちらか、両方を与える(与えない)ことができます。

  もし dry_run が真なら、ファイルシステムに影響することは何もされません。

  バイトコンパイルは現在のインタプリタプロセスによって標準の `py_compile` モジュールを使って直接行われるか、テンポラリスクリプトを書いて間接的に行われます。通常は `byte_compile()` に直接かそうでないかをまかせます (詳細についてはソースをごらんください)。 direct フラグは関節モードで作成されたスクリプトで使用されます。何をやっているか理解していない時は `None` のままにしておいてください。

  バージョン 3.2.3 で変更: カレントディレクトリにタグなしでファイルを作る代わりに、 `__pycache__` サブディレクトリに `import magic tag` を使ってその名前で `.pyc` ファイルを作成します。

  バージョン 3.5 で変更: PEP 488 に従って `.pyc` ファイルを作成します。

distutils.util.rfc822_escape(header)

  RFC 822 ヘッダに含められるよう加工した header を返します。改行のあとには8つのスペースが追加されます。この関数は文字列に他の変更はしません。

## 9.12. `distutils.dist` --- Distribution クラス

このモジュールは、ビルド/インストール/配布するモジュールディストリビューションを表す `Distribution` クラスを提供します。

## 9.13. `distutils.extension` --- Extension クラス

このモジュールは `Extension` クラスを提供します。 C/C++拡張モジュールをセットアップスクリプトで表すために使われます。

## 9.14. `distutils.debug` --- Distutils デバッグモード

このモジュールはDEBUGフラグを提供します。

## 9.15. `distutils.errors` --- Distutils 例外

distutilsのモジュールで使用される例外を提供します。 distutilsのモジュールは標準的な例外を起こします。特に、 SystemExit はエンドユーザによる失敗(コマンドライン引数の間違いなど)で起きます。

このモジュールは `from ... import *` で安全に使用することができます。このモジュールは `Distutils` ではじまり、 `Error` で終わるシンボルしかexportしません。

## 9.16. `distutils.fancy_getopt` --- 標準 getopt モジュールのラッパ

このモジュールは以下の機能を標準の `getopt` モジュールに追加するラッパを提供します:

- 短いオプションと長いオプションを関連づけます

- オプションはヘルプ文字列なので、 `fancy_getopt()` に完全な利用方法サマリを作らせることもできます

- オプションは渡されたオブジェクトの属性を設定します。

- 真偽値をとるオプションは "負のエイリアス" を持ちます。--- たとえば `--quiet` の "負のエイリアス" が `--verbose` の場合、コマンドラインで `--quiet` を指定すると verbose は偽になります。

distutils.fancy_getopt.fancy_getopt(options, negative_opt, object, args)

  ラッパ関数。 options は `FancyGetopt` のコンストラクタで説明されている `(long_option, short_option, help_string)` の3要素タプルのリストです。 negative_opt はオプション名からオプション名のマッピングになっている辞書で、キー、値のどちらも options リストに含まれている必要があります。 object は値を保存するオブジェクト(`FancyGetopt` クラスの `getopt()` メソッドを参照してください)です。 args は引数のリストです。 args として `None` を渡すと、 `sys.argv[1:]` が使われます。

distutils.fancy_getopt.wrap_text(text, width)

  text を width 以下の幅で折り返します。

class distutils.fancy_getopt.FancyGetopt([option_table=None])

  option_table は 3つ組タプルのリストです。 `(long_option, short_option, help_string)`

  もしオプションが引数を持つなら、 long_option に `'='` を追加する必要があります。 short_option は一文字のみで、 `':'` はどの場合にも不要です。 long_option に対応する short_option がない場合、 short_option は `None` にしてください。全てのオプションタプルは長い形式のオプションを持つ必要があります。

`FancyGetopt` クラスは以下のメソッドを提供します:

FancyGetopt.getopt([args=None, object=None])

  argsのコマンドラインオプションを解析します。 object に属性として保存します。

  もし args が `None` もしくは与えられない場合には、 `sys.argv[1:]` を使います。もし object が `None` もしくは与えられない場合には、新しく `OptionDummy` インスタンスを作成し、オプションの値を保存したのち `(args, object)` のタプルを返します。もし object が提供されていれば、その場で変更され、 `getopt()` は args のみを返します。どちらのケースでも、返された args は渡された args リスト(これは変更されません)の変更されたコピーです。

FancyGetopt.get_option_order()

  直前に実行された `getopt()` が処理した `(option, value)` タプルのリストを返します。 `getopt()` がまだ呼ばれていない場合には `RuntimeError` を起こします。

FancyGetopt.generate_help([header=None])

  この `FancyGetopt` オブジェクトのオプションテーブルからヘルプテキスト(出力の一行に対応する文字列のリスト)を生成します。

  もし与えられていれば、 header をヘルプの先頭に出力します。

## 9.17. `distutils.filelist` --- FileList クラス

このモジュールはファイルシステムを見て、ファイルのリストを構築するために使われる `FileList` クラスを提供します。

## 9.18. `distutils.log` --- シンプルな PEP 282 形式のロギング

## 9.19. `distutils.spawn` --- サブプロセスの生成

このモジュールは `spawn()` 関数を提供します。これは様々なプラットフォーム依存の他プログラムをサブプロセスとして実行する関数に対するフロントエンドになっています。与えられた実行ファイルの名前からパスを探索する `find_executable()` 関数も提供しています。

## 9.20. `distutils.sysconfig` --- システム設定情報

バージョン 3.10 で非推奨: `distutils.sysconfig` has been merged into `sysconfig`.

`distutils.sysconfig` モジュールでは、 Python の低水準の設定情報へのアクセス手段を提供しています。アクセスできる設定情報変数は、プラットフォームと設定自体に大きく左右されます。また、特定の変数は、使っているバージョンの Python のビルドプロセスに左右されます; こうした変数は、 Unix システムでは、 `Makefile` や Python と一緒にインストールされる設定ヘッダから探し出されます。設定ファイルのヘッダは、2.2 以降のバージョンでは `pyconfig.h` 、それ以前のバージョンでは `config.h` です。

他にも、 `distutils` パッケージの別の部分を操作する上で便利な関数がいくつか提供されています。

distutils.sysconfig.PREFIX

  `os.path.normpath(sys.prefix)` の返り値です。

distutils.sysconfig.EXEC_PREFIX

  `os.path.normpath(sys.exec_prefix)` の返り値です。

distutils.sysconfig.get_config_var(name)

  ある一つの設定変数に対する値を返します。 `get_config_vars().get(name)` と同じです。

distutils.sysconfig.get_config_vars(...)

  定義されている変数のセットを返します。引数を指定しなければ、設定変数名を変数の値に対応付けるマップ型を返します。引数を指定する場合、引数の各値は文字列でなければならず、戻り値は引数に関連付けられた各設定変数の値からなるシーケンスになります。引数に指定した名前の設定変数に値がない場合、その変数に対する戻り値には `None` が入ります。

distutils.sysconfig.get_config_h_filename()

  設定ヘッダのフルパス名を返します。 Unixの場合、このヘッダファイルは configure スクリプトによって生成されるヘッダファイル名です; 他のプラットフォームでは、ヘッダは Python ソース配布物中で直接与えられています。ファイルはプラットフォーム固有のテキストファイルです。

distutils.sysconfig.get_makefile_filename()

  Python をビルドする際に用いる `Makefile` のフルパスを返します。 Unixの場合、このファイルは configure スクリプトによって生成されます; 他のプラットフォームでは、この関数の返す値の意味は様々です。有意なファイル名を返す場合、ファイルはプラットフォーム固有のテキストファイル形式です。この関数は POSIX プラットフォームでのみ有用です。

The following functions are deprecated together with this module and they have no direct replacement.

distutils.sysconfig.get_python_inc([plat_specific[, prefix]])

  C インクルードファイルディレクトリについて、一般的なディレクトリ名か、プラットフォーム依存のディレクトリ名のいずれかを返します。 plat_specific が真であれば、プラットフォーム依存のインクルードディレクトリ名を返します; plat_specific が偽か、省略された場合には、プラットフォームに依存しないディレクトリを返します。 prefix が指定されていれば、 `PREFIX` の代わりに用いられます。また、 plat_specific が真の場合、 `EXEC_PREFIX` の代わりに用いられます。

distutils.sysconfig.get_python_lib([plat_specific[, standard_lib[, prefix]]])

  ライブラリディレクトリについて、一般的なディレクトリ名か、プラットフォーム依存のディレクトリ名のいずれかを返します。 plat_specific が真であれば、プラットフォーム依存のライブラリディレクトリ名を返します; plat_specific が偽か、省略された場合には、プラットフォームに依存しないディレクトリを返します。 prefix が指定されていれば、 `PREFIX` の代わりに用いられます。また、 plat_specific が真の場合、 `EXEC_PREFIX` の代わりに用いられます。 standard_lib が真であれば、サードパーティ製の拡張モジュールをインストールするディレクトリの代わりに、標準ライブラリのディレクトリを返します。

以下の関数は、 `distutils` パッケージ内の使用だけを前提にしています。

distutils.sysconfig.customize_compiler(compiler)

  `distutils.ccompiler.CCompiler` インスタンスに対して、プラットフォーム固有のカスタマイズを行います。

  この関数は現在のところ、Unix だけで必要ですが、将来の互換性を考慮して一貫して常に呼び出されます。この関数は様々な Unix の変種ごとに異なる情報や、Python の `Makefile` に書かれた情報をインスタンスに挿入します。この情報には、選択されたコンパイラやコンパイラ/リンカのオプション、そして共有オブジェクトを扱うためにリンカに指定する拡張子が含まれます。

この関数はもっと特殊用途向けで、Python 自体のビルドプロセスでのみ使われるべきです。

distutils.sysconfig.set_python_build()

  `distutils.sysconfig` モジュールに、モジュールが Python のビルドプロセスの一部として使われることを知らせます。これによって、ファイルコピー先を示す相対位置が大幅に変更され、インストール済みの Python ではなく、ビルド作業領域にファイルが置かれるようになります。

## 9.21. `distutils.text_file` --- TextFile クラス

このモジュールは `TextFile` クラスを提供します。これはテキストファイルへのインターフェースを提供し、コメントの削除、空行の無視、バックスラッシュでの行の連結を任意に行えます。

class distutils.text_file.TextFile([filename=None, file=None, **options])

  このクラスはファイルのようなオブジェクトを提供します。これは行指向のテキストファイルを処理する時に共通して必要となる処理を行います: (`#` がコメント文字なら)コメントの削除、空行のスキップ、 (行末のバックスラッシュでの)改行のエスケープによる行の連結、先頭/末尾の空白文字の削除。これらは全て独立して任意に設定できます。

  クラスは `warn()` メソッドを提供しており、物理行つきの警告メッセージを生成することができます。この物理行は論理行が複数の物理行にまたがっていても大丈夫です。また `unreadline()` メソッドが一行先読みを実装するために提供されています。

  `TextFile` のインスタンスは filename, file,またはその両方をとって作成されます。両方が `None` の場合 `RuntimeError` が起きます。 filename は文字列、 file はファイルオブジェクト(または `readline()` と `close()` のメソッドを提供する何か) である必要があります。 `TextFile` が生成する警告メッセージに含めることができるので、 filename を与えることが推奨されます、もし file が提供されなければ、 `TextFile` は組み込みの `open()` を利用して自分で作成します。

  オプションは全て真偽値で、 `readline()` で返される値に影響します。

  オプション名 | description | default
  --- | --- | ---
  strip_comments | バックスラッシュでエスケープされていない限り、`'#'` から行末までと、`'#'` の先にある空白文字の並びを削除します | true
  lstrip_ws | 行を返す前に先頭の空白文字の並びを削除します。 | false
  rstrip_ws | 行を返す前に行末の空白文字(改行文字を含みます!)の並びを削除します。 | true
  skip_blanks | コメントと空白を除いた*あとで*内容がない行をスキップします。 (もし lstrip_ws と rstrip_ws がともに偽なら、空白文字だけの行があるかもしれません。これは skip_blanks が真でない限りスキップされません。) | true
  join_lines | もしコメントと空白文字を削除したあとで、バックスラッシュが最後の改行文字でない文字なら、次の行を接続して一つの論理行とします: N行の連続した行がバックスラッシュで終わる場合、N+1 行の物理行が1行の論理行として扱われます。 | false
  collapse_join | 前の行と接続するとき、行頭の空白文字を削除します。 `(join_lines and not lstrip_ws)` の時だけ意味をもちます。 | false

  rstrip_ws は行末の改行を削除するので、 `readline()` のセマンティクスが組み込みファイルオブジェクトの `readline()` メソッドとは変わってしまいます! 特に、 rstrip_ws が真で skip_blanks が偽のとき、 `readline()` はファイルの終端で `None` を返し、空文字列を返したときは空行(または全て空白文字の行)です。

  open(filename)

    新しいファイル filename を開きます。これはコンストラクタ引数の file と filename を上書きします。

  close()

    現在のファイルを閉じ、(ファイル名や現在の行番号を含め)現在のファイルについての情報を全て消します。

  warn(msg[, line=None])

    標準エラー出力に現在のファイルの論理行に結びついた警告メッセージを出力します。もし現在の論理行が複数の物理行に対応するなら、警告メッセージは以下のように全体を参照します: `"lines 3-5"` 。もし line が与えられていれば、現在の行番号を上書きします; 物理行のレンジをあらわすリストまたはタプル、もしくはある物理行をあらわす整数のどれでも与えられます。

  readline()

    現在のファイル(または `unreadline()` で"unread"を直前に行っていればバッファ)から論理行を1行読み込んで返します。もし join_lines オプションが真なら、このメソッドは複数の物理行を読み込んで接続した文字列を返します。現在の行番号を更新します。そのため `readline()` のあとに `warn()` を呼ぶと丁度読んだ行についての警告を出します。 rstrip_ws が真で、 strip_blanks が偽のとき空文字列が返るので、ファイルの終端では `None` を返します。

  readlines()

    現在のファイルで残っている全ての論理行のリストを読み込んで返します。行番号を、ファイルの最後の行に更新します。

  unreadline(line)

    line (文字列)を次の `readline()` 用に、内部バッファにpushします。行の先読みを必要とするパーサを実装する時に便利です。 `unreadline()` で"unread"された行は `readline()` で読み込む際に再度処理(空白の除去など)されません。もし `unreadline()` を、 `readline()` を呼ぶ前に複数回実行すると、最後にunreadした行から返されます。

## 9.22. `distutils.version` --- バージョン番号クラス

## 9.23. `distutils.cmd` --- Distutils コマンドの抽象クラス

このモジュールは抽象ベースクラス `Command` を提供します。

class distutils.cmd.Command(dist)

  コマンドクラスを定義するための抽象ベースクラス --- distutilsの「働きバチ」 --- です。コマンドクラスは options とよばれるローカル変数を持ったサブルーチンと考えることができます。オプションは `initialize_options()` で宣言され、 `finalize_options()` で定義さ(最終的な値を与えら)れます。どちらも全てのコマンドクラスで実装する必要があります。この2つの区別は必要です。なぜならオプションの値は外部(コマンドライン、設定ファイルなど)から来るかもしれず、他のオプションに依存しているオプションは外部の影響を処理した後で計算される必要があるからです。そのため `finalize_options()` が存在します。サブルーチンの本体は全ての処理をオプションの値にもとづいて行う `run()` メソッドで、これも全てのコマンドクラスで実装される必要があります。

  このクラスのコンストラクタは、 `Distribution` インスタンス dist 1 つを引数に取ります。

## 9.24. 新しいDistutilsコマンドの作成

このセクションではDistutilsの新しいコマンドを作成する手順の概要をしめします。

新しいコマンドは `distutils.command` パッケージ中のモジュールに作られます。 `command_template` というディレクトリにサンプルのテンプレートがあります。このファイルを実装しようとしているコマンドと同名の新しいモジュールにコピーしてください。このモジュールはモジュール(とコマンド)と同じ名前のクラスを実装する必要があります。そのため、 `peel_banana` コマンド(ユーザは `setup.py peel_banana` と実行できます)を実装する際には、 `command_template` を `distutils/command/peel_banana.py` にコピーし、 `distutils.cmd.Command` のサブクラス `peel_banana` クラスを実装するように編集してください。

`Command` のサブクラスは以下のメソッドを実装する必要があります。

Command.initialize_options()

  このコマンドがサポートする全てのオプションのデフォルト値を設定します。これらのデフォルトは他のコマンドやセットアップスクリプト、設定ファイル、コマンドラインによって上書きされるかもしれません。そのためオプション間の依存関係を記述するには適切な場所ではありません。一般的に `initialize_options()` は単に `self.foo = None` のような定義だけを行います。

Command.finalize_options()

  このコマンドがサポートする全てのオプションの最終的な値を設定します。これは可能な限り遅く呼び出されます。つまりコマンドラインや他のコマンドによるオプションの代入のあとに呼び出されます。そのため、オプション間の依存関係を記述するのに適した場所です。もし foo が bar に依存しており、かつまだ foo が `initialize_options()` で定義された値のままなら、 foo を bar から代入しても安全です。

Command.run()

  コマンドの本体です。実行するべきアクションを実装しています。 `initialize_options()` で初期化され、他のコマンドされ、セットアップスクリプト、コマンドライン、設定ファイルでカスタマイズされ、 `finalize_options()` で設定されたオプションがアクションを制御します。端末への出力とファイルシステムとのやりとりは全て `run()` が行います。

Command.sub_commands

  sub_commands はコマンドの"ファミリー"を定式化したものです。たとえば `install` はサブコマンド `install_lib` `install_headers` などの親です。コマンドファミリーの親は sub_commands をクラス属性として持ちます。 sub_commands は2要素のタプル `(command_name, predicate)` のリストで、 command_name は文字列、 predicate は関数か文字列か `None` です。 predicate はには親コマンドのメソッドで、現在の状況がコマンド実行にふさわしいかどうか判断するものを指定します。 (例えば `install_headers` はインストールするべき Cヘッダファイルがある時だけ有効です。) もし predicate が None なら、そのコマンドは常に有効になります。

  sub_commands は通常クラスの 最後 で定義されます。これは predicate は bound されていないメソッドになるので、全て先に定義されている必要があるためです。標準的な例は install コマンドです。

## 9.25. `distutils.command` --- Distutils 各コマンド

## 9.26. `distutils.command.bdist` --- バイナリインストーラの構築

## 9.27. `distutils.command.bdist_packager` --- パッケージの抽象ベースクラス

## 9.28. `distutils.command.bdist_dumb` --- "ダム"インストーラを構築

## 9.29. `distutils.command.bdist_rpm` --- Redhat RPMとSRPM形式のバイナリディストリビューションを構築

## 9.30. `distutils.command.sdist` --- ソース配布物の構築

## 9.31. `distutils.command.build` --- パッケージ中の全ファイルを構築

## 9.32. `distutils.command.build_clib` --- パッケージ中のCライブラリを構築

## 9.33. `distutils.command.build_ext` --- パッケージ中の拡張を構築

## 9.34. `distutils.command.build_py` --- パッケージ中の.py/.pyc ファイルを構築

class distutils.command.build_py.build_py

class distutils.command.build_py.build_py_2to3

  インストールされる各 .py ファイル上で 2to3 変換ライブラリをさらに実行する build_py の代替実装。Python 2.x と 3.x の両方で動くことを意図した配布物において setup.py ファイルの中でこれを使用するためには、setup.py に次のように付け加えてください:

      try:
          from distutils.command.build_py import build_py_2to3 as build_py
      except ImportError:
          from distutils.command.build_py import build_py

  そして:

      cmdclass = {'build_py': build_py}

  を setup() の呼び出しに追加してください。

## 9.35. `distutils.command.build_scripts` --- パッケージ中のスクリプトを構築

## 9.36. `distutils.command.clean` --- パッケージのビルドエリアを消去

このコマンドは build とそのサブコマンドによって作られた、中間コンパイルオブジェクトファイルのような一時ファイルを削除します。 `--all` オプションとともに使うと、 build ディレクトリ全体を削除します。

in place でビルドしたモジュールは、それは build ディレクトリにいないので、削除されません。

## 9.37. `distutils.command.config` --- パッケージの設定

## 9.38. `distutils.command.install` --- パッケージのインストール

## 9.39. `distutils.command.install_data` --- パッケージ中のデータファイルをインストール

## 9.40. `distutils.command.install_headers` --- パッケージから C/C++ ヘッダファイルをインストール

## 9.41. `distutils.command.install_lib` --- パッケージからライブラリファイルをインストール

## 9.42. `distutils.command.install_scripts` --- パッケージからスクリプトファイルをインストール

## 9.43. `distutils.command.register` --- モジュールをPython Package Indexに登録する

`register` コマンドはパッケージをPython Package Index に登録します。この詳細は PEP 301 に記述されています。

## 9.44. `distutils.command.check` --- パッケージのメタデータをチェックする

`check` コマンドは、パッケージのメタデータに対していくつかのテストを行ないます。例えば、すべての必要なメタデータが `setup()` 関数に渡された引数として提供されることを確認します。