簡単な例 節で示したように、ソースコード配布物を作成するには sdist コマンドを使います。最も単純な例では、
python setup.py sdist
のようにします (ここでは、 sdist に関するオプションを setup スクリプトや設定ファイル中で行っていないものと仮定します)。 sdist は、現在のプラットフォームでのデフォルトのアーカイブ形式でアーカイブを生成します。デフォルトの形式は Unixでは gzip で圧縮された tar ファイル形式 (.tar.gz) で、Windows では ZIP 形式です。
--formats オプションを使えば、好きなだけ圧縮形式を指定できます。例えば:
python setup.py sdist --formats=gztar,zip
は、gzip された tarball と zip ファイルを作成します。利用可能な形式は以下の通りです:
形式 | 説明 | 注記 |
---|---|---|
zip | zip ファイル (.zip) | (1),(3) |
gztar | gzip 圧縮された tar ファイル (.tar.gz) | (2),(4) |
bztar | bzip2 圧縮された tar ファイル (.tar.bz2) | (4) |
ztar | compress 圧縮された tar ファイル (.tar.Z) | (4) |
tar | tar ファイル (.tar) | (4) |
注記:
明確なファイルのリスト (またはファイルリストを生成する方法) を明示的に与えなかった場合、 sdist コマンドはソース配布物に以下のような最小のデフォルトのセットを含めます:
py_modules と packages オプションに指定された Python ソースファイル全て
ext_modules や libraries オプションに記載された C ソースファイル
** (C ライブラリソースの取得機構は現状ではうまく動きません – build_clib.py には、 get_source_files() メソッドがありません!) **
scripts オプションで指定されたスクリプト
テストスクリプトと思しきファイル全て: test/test*.py (現状では、Distutils はテストスクリプトをただソース配布物に含めるだけですが、将来は Python モジュール配布物に対するテスト標準ができるかもしれません)
README.txt (または README)、 setup.py (または setup スクリプトにしているもの) 、および setup.cfg
上記のセットで十分なこともありますが、大抵他のファイルを配布物に含めたいと思うでしょう。普通は、 MANIFEST.in と呼ばれる マニフェストテンプレート (manifest template) を使ってこれを行います。マニフェストテンプレートは、ソース配布物に 含めるファイルの正確なリストであるマニフェストファイル MANIFEST をどうやって作成するか指示しているリストです。 sdist コマンドはこのテンプレートを処理し、書かれた指示とファイルシステム上に見つかったファイルに基づいて マニフェストファイルを作成します。
自分用のマニフェストファイルを書きたいなら、その形式は簡単です: 一行あたり一つの通常ファイル (または通常ファイルに対するシンボリックリンク) だけを書きます。自分で MANIFEST を提供する場合、全てを自分で指定しなければなりません: ただし、上で説明したデフォルトのファイルセットは、この中には含まれません。
マニフェストテンプレートには一行あたり一つのコマンドがあります。各コマンドはソース配布物に入れたり配布物から除外したりするファイルのセットを指定します。 例えば、Distutils 自体のマニフェストテンプレートの話に戻ると:
include *.txt
recursive-include examples *.txt *.py
prune examples/sample?/build
各行はかなり明確に意味を取れるはずです: 上の指定では、 *.txt にマッチする配布物ルート下の全てのファイル、 examples ディレクトリ下にある *.txt か *.py にマッチする全てのファイルを含め、 examples/sample?/build にマッチする全てのファイルを除外します。これらの処理はすべて、標準的に含められるファイルセットの評価よりも 後に 行われるので、マニフェストテンプレートに明示的に指示をしておけば、標準セット中のファイルも除外できます。 (--no-defaults オプションを設定して、標準セット自体を無効にもできます。) 他にも、このマニフェストテンプレート記述のためのミニ言語にはいくつかのコマンドがあります: ソースコード配布物を作成する: sdist command 節を参照してください。
マニフェストテンプレート中のコマンドの順番には意味があります; 初期状態では、上で述べたようなデフォルトのファイルがあり、 テンプレート中の各コマンドによって、逐次ファイルを追加したり除去したりしていいます。マニフェストテンプレートを完全に 処理し終えたら、ソース配布物中に含めるべきでない以下のファイルをリストから除去します:
こうして完全なファイルのリストができ、後で参照するためにマニフェストに書き込まれます。この内容は、ソース配布物のアーカイブを作成する際に使われます。
含めるファイルのデフォルトセットは --no-defaults で無効化でき、標準で除外するセットは --no-prune で無効化できます。
Distutils 自体のマニフェストテンプレートから、 sdist コマンドがどのようにして Distutils ソース配布物に含めるファイルのリストを作成するか見てみましょう:
setup スクリプトと同様、マニフェストテンプレート中のディレクトリ名は常にスラッシュ区切りで表記します; Distutils は、こうしたディレクトリ 名を注意深くプラットフォームでの標準的な表現に変換します。このため、マニフェストテンプレートは複数のオペレーティングシステムにわたって可搬性を持ちます。
sdist コマンドが通常行う処理の流れは、以下のようになっています:
上の動作は二種類のオプションを使って修正できます。まず、標準の “include” および “exclude” セットを無効化するには --no-defaults および --no-prune を使います
第二に、マニフェストファイルの再生成を強制できます — 例えば、現在マニフェストテンプレート内に指定しているパターンにマッチする ファイルやディレクトリを追加したり削除したりすると、マニフェストを再生成しなくてはなりません:
python setup.py sdist --force-manifest
また、単にマニフェストを (再) 生成したいだけで、ソース配布物は作成したくない場合があるかもしれません:
python setup.py sdist --manifest-only
--manifest-only を行うと、 --force-manifest を呼び出します。 -o は --manifest-only のショートカット、 -f は --force-manifest のショートカットです。