3. setup 設定ファイル (setup configuration file) を書く

時に、配布物をビルドする際に必要な全ての設定を あらかじめ 書ききれない状況が起きます: 例えば、ビルドを進めるために、ユーザに関する情報や、ユーザのシステムに関する情報を必要とするかもしれません。こうした情報が単純 — C ヘッダファイルやライブラリを検索するディレクトリのリストのように — であるかぎり、ユーザに設定ファイル (configuration file) setup.cfg を提供して編集してもらうのが、安上がりで簡単な特定方法になります。設定ファイルはまた、あらゆるコマンドにおけるオプションにデフォルト値を与えておき、インストール作業者がコマンドライン上や設定ファイルの編集でデフォルト設定を上書きできるようにします。

setup 設定ファイルは setup スクリプト —理想的にはインストール作業者から見えないもの [1] —と、作者の手を離れて、全てインストール作業者次第となる setup スクリプトのコマンドライン引数との間を橋渡しする中間層として有効です。実際、 setup.cfg (と、ターゲットシステム上にある、その他の Distutils 設定ファイル) は、 setup スクリプトの内容より後で、かつコマンドラインで上書きする前に処理されます。この仕様の結果、いくつかの利点が生まれます:

• インストール作業者は、作者が setup.py に設定した項目のいくつかを setup.cfg を変更して上書きできます
• setup.py では簡単に設定できないような、標準でないオプションのデフォルト値を設定できます
• インストール作業者は、 setup.cfg に書かれたどんな設定も setup.py のコマンドラインオプションで上書きできます

設定ファイルの基本的な構文は簡単なものです:

[command]
option=value
...

ここで、 command は Distutils コマンドのうちの一つ (例えば build_py, install) で、 option はそのコマンドでサポートされているオプションのうちの一つです。各コマンドには任意の数のオプションを設定でき、一つの設定ファイル中には任意の数のコマンドセクションを収められます。空白行は無視されます、 '#' 文字で開始して行末まで続くコメントも同様に無視されます。長いオプション設定値は、継続行をインデントするだけで複数行にわたって記述できます。

あるコマンドがサポートしているオプションのリストは、 --help オプションで調べられます。例えば以下のように。

> python setup.py --help build_ext
[...]
Options for 'build_ext' command:
  --build-lib (-b)     directory for compiled extension modules
  --build-temp (-t)    directory for temporary files (build by-products)
  --inplace (-i)       ignore build-lib and put compiled extensions into the
                       source directory alongside your pure Python modules
  --include-dirs (-I)  list of directories to search for header files
  --define (-D)        C preprocessor macros to define
  --undef (-U)         C preprocessor macros to undefine
  --swig-opts          list of SWIG command line options
[...]

Note that an option spelled --foo-bar on the command-line is spelled foo_bar in configuration files.

For example, say you want your extensions to be built "in-place"—that is, you have an extension pkg.ext, and you want the compiled extension file (ext.so on Unix, say) to be put in the same source directory as your pure Python modules pkg.mod1 and pkg.mod2. You can always use the --inplace option on the command-line to ensure this:

python setup.py build_ext --inplace

But this requires that you always specify the build_ext command explicitly, and remember to provide --inplace. An easier way is to "set and forget" this option, by encoding it in setup.cfg, the configuration file for this distribution:

[build_ext]
inplace=1

この設定は、明示的に build_ext を指定するかどうかに関わらず、モジュール配布物の全てのビルドに影響します。ソース配布物に setup.cfg を含めると、エンドユーザの手で行われるビルドにも影響します — このオプションの例に関しては setup.cfg を含めるのはおそらくよくないアイデアでしょう。というのは、拡張モジュールをインプレースでビルドすると常にインストールしたモジュール配布物を壊してしまうからです。とはいえ、ある特定の状況では、モジュールをインストールディレクトリの下に正しく構築できるので、機能としては有用だと考えられます。 (ただ、インストールディレクトリ上でのビルドを想定するような拡張モジュールの配布は、ほとんどの場合よくない考え方です。)

もう一つ、例があります: コマンドによっては、実行時にほとんど変更されないたくさんのオプションがあります; 例えば、 bdist_rpm には、RPM 配布物を作成する際に、"spec" ファイルを作成するために必要な情報を全て与えなければなりません。この情報には setup スクリプトから与えるものもあり、 (インストールされるファイルのリストのように) Distutils が自動的に生成するものもあります。しかし、こうした情報の中には bdist_rpm のオプションとして与えるものがあり、毎回実行するごとにコマンドライン上で指定するのが面倒です。そこで、以下のような内容が Distutils 自体の setup.cfg には入っています:

[bdist_rpm]
release = 1
packager = Greg Ward <gward@python.net>
doc_files = CHANGES.txt
            README.txt
            USAGE.txt
            doc/
            examples/

doc_files オプションは、単に空白で区切られた文字列で、ここでは可読性のために複数行をまたぐようにしています。

参考

"Python モジュールのインストール" の 設定ファイルの構文

設定ファイルに関する詳細情報は、システム管理者向けのこのマニュアルにあります。

注記

[1]	Distutils が自動設定機能 (auto-configuration) をサポートするまで、おそらくこの理想状態を達成することはないでしょう。