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

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

The setup configuration file is a useful middle-ground between the
setup script---which, ideally, would be opaque to installers [1]---and
the command-line to the setup script, which is outside of your control
and entirely up to the installer.  In fact, "setup.cfg" (and any other
Distutils configuration files present on the target system) are
processed after the contents of the setup script, but before the
command-line.  This has  several useful consequences:

* インストール作業者は、作者が "setup.py" に設定した項目のいくつかを
  "setup.cfg" を変更して上書きできます

* "setup.py" では簡単に設定できないような、標準でないオプションのデ
  フ ォルト値を設定できます

* インストール作業者は、 "setup.cfg" に書かれたどんな設定も
  "setup.py" のコマンドラインオプションで上書きできます

The basic syntax of the configuration file is simple:

   [command]
   option=value
   ...

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

You can find out the list of options supported by a particular command
with the universal "--help" option, e.g.

   $ 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" を含めるのはおそらくよくないアイデア
でしょう。というのは、拡張モジュールをインプレースでビルドすると常にイ
ンストールしたモジュール配布物を壊してしまうからです。とはいえ、ある特
定の状況では、モジュールをインストールディレクトリの下に正しく構築でき
るので、機能としては有用だと考えられます。 (ただ、インストールディレク
トリ上でのビルドを想定するような拡張モジュールの配布は、ほとんどの場合
よくない考え方です。)

Another example: certain commands take a lot of options that don't
change from run to run; for example, **bdist_rpm** needs to know
everything required to generate a "spec" file for creating an RPM
distribution.  Some of this information comes from the setup script,
and some is automatically generated by the Distutils (such as the list
of files installed).  But some of it has to be supplied as options to
**bdist_rpm**, which would be very tedious to do on the command-line
for every run.  Hence, here is a snippet from the Distutils' own
"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) をサポートするま
    で、 おそらくこの理想状態を達成することはないでしょう。
