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のコマンドラインオプションで上書きできます
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) をサポートするまで、おそらくこの理想状態を達成することはないでしょう。 |