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