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

注釈:

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

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

設定ファイル "setup.cfg" は設定スクリプト "setup.py" --- 理想的にはイ
ンストール作業者が内容を知らなくてもよいもの [1]--- と、完全にインスト
ール作業者の都合で決まるスクリプトのコマンドライン引数との間に存在する
有用な中間層です。 実際、 "setup.cfg" (および対象のシステム上に存在す
るその他の Distutils 設定ファイル) は、設定スクリプトの内容が処理され
た後、コマンドライン引数が解析される前に処理されます。 この動作により
、いくつかの利点が生まれます:

* インストール作業者は、作者が "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
   [...]

コマンドライン上で "--foo-bar" と綴るオプションは、設定ファイル上では
"foo_bar" と綴るので注意してください。

例えば、拡張モジュールを "その場 (in-place)" でビルドしたい --- すなわ
ち、配布物が拡張モジュール "pkg.ext" を含み、コンパイルされた拡張モジ
ュールファイル (Unix の場合は "ext.so") を pure Python モジュール
"pkg.mod1" および "pkg.mod2" と同じソースディレクトリに配置したいとし
ます。 "その場 (in-place)" でのビルドを確実に行いたい場合は、 "--
inplace" オプションが有用です。

   python setup.py build_ext --inplace

しかしこの場合、必ず明示的に **build_ext** コマンドを設定し、かつ "--
inplace" オプションを忘れずに指定しなければなりません。これを確実に行
う簡単な方法は、このディストリビューションの "setup.cfg" 設定ファイル
に 以下のように書いておくことで、設定を "自動化 (set and forget)" する
ことです:

   [build_ext]
   inplace=1

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

もう一つの例: コマンドによってはあまり変更されることのない多くのオプシ
ョンを持つ場合があります; たとえば、 **bdist_rpm** はRPMディストリビュ
ーションを作成するための "spec" ファイルを生成するために必要な全ての情
報を必要とします。そのような情報のうちいくつかは設定スクリプト
"setup.py" で与えたり、 (インストールされるファイルリストのように)
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) をサポートするまで、
    おそらくこの理想状態を達成することはないでしょう。
