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