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