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) をサポートするま
    で、 おそらくこの理想状態を達成することはないでしょう。
