簡単な例 節で示したように、ソースコード配布物を作成するには 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) |
bztar | bzip2 圧縮された tar ファイル (.tar.bz2) | |
ztar | compress 圧縮された tar ファイル (.tar.Z) | (4) |
tar | tar ファイル (.tar) |
注記:
tar フォーマットのどれか (gztar, bztar, ztar, tar) を Unix で利用する時、アーカイブ内の各メンバに設定される owner と group 名を指定することができます。
例えば、アーカイブ内の全てのファイルの所有者を root にするには、次のようにします。
python setup.py sdist --owner=root --group=root
明確なファイルのリスト (またはファイルリストを生成する方法) を明示的に与えなかった場合、 sdist コマンドはソース配布物に以下のような最小のデフォルトのセットを含めます:
上記のセットで十分なこともありますが、大抵他のファイルを配布物に含めたいと思うでしょう。普通は、 MANIFEST.in と呼ばれる マニフェストテンプレート (manifest template) を使ってこれを行います。マニフェストテンプレートは、ソース配布物に含めるファイルの正確なリストであるマニフェストファイル MANIFEST をどうやって作成するか指示しているリストです。 sdist コマンドはこのテンプレートを処理し、書かれた指示とファイルシステム上に見つかったファイルに基づいてマニフェストファイルを作成します。
自分用のマニフェストファイルを書きたいなら、その形式は簡単です: 一行あたり一つの通常ファイル (または通常ファイルに対するシンボリックリンク) だけを書きます。自分で MANIFEST を提供する場合、全てを自分で指定しなければなりません: ただし、上で説明したデフォルトのファイルセットは、この中には含まれません。
バージョン 2.7 で追加: MANIFEST のコメントで始まるファイルは、それが生成されたものであることを表します。 そうでないファイルは上書きされたり削除されたりしません。
シンタックスリファレンスは MANIFEST.in テンプレート を参照してください。
sdist コマンドが通常行う処理の流れは、以下のようになっています:
上の動作は二種類のオプションを使って変更できます。まず、標準の “include” および “exclude” セットを無効化するには --no-defaults および --no-prune を使います。
第2に、単にマニフェストを (再)生成したいだけで、ソース配布物は作成したくない場合があるかもしれません:
python setup.py sdist --manifest-only
-o は --manifest-only のショートカットです。
sdist コマンドがビルドする配布物に含めるファイルのリストを定義するために、プロジェクトに MANIFEST.in ファイルを追加することができます。
sdist が実行された時、 MANIFEST.in ファイルを探して、それを解釈して、パッケージに含めるファイルのリストを含んだ MANIFEST ファイルを生成します。
This mechanism can be used when the default list of files is not enough. (See 配布するファイルを指定する). この機構は、デフォルトのファイルリストが十分でないときに利用できます。 (配布するファイルを指定する を参照)
マニフェストテンプレートには一行あたり一つのコマンドがあります。各コマンドはソース配布物に入れたり配布物から除外したりするファイルのセットを指定します。例えば、Distutils 自体のマニフェストテンプレートを見てみましょう:
include *.txt
recursive-include examples *.txt *.py
prune examples/sample?/build
各行はかなり明確に意味を取れるはずです: 上の指定では、 *.txt にマッチする配布物ルート下の全てのファイル、 examples ディレクトリ下にある *.txt か *.py にマッチする全てのファイルを含め、 examples/sample?/build にマッチする全てのファイルを除外します。これらの処理はすべて、標準的に含められるファイルセットの評価よりも 後に 行われるので、マニフェストテンプレートに明示的に指示をしておけば、標準セット中のファイルも除外できます。 (--no-defaults オプションを設定して、標準セット自体を無効にもできます。)
マニフェストテンプレート中のコマンドの順番には意味があります; 初期状態では、上で述べたようなデフォルトのファイルがあり、テンプレート中の各コマンドによって、逐次ファイルを追加したり除去したりしていいます。マニフェストテンプレートを完全に処理し終えたら、ソース配布物中に含めるべきでない以下のファイルをリストから除去します:
こうして完全なファイルのリストができ、後で参照するためにマニフェストに書き込まれます。この内容は、ソース配布物のアーカイブを作成する際に使われます。
含めるファイルのデフォルトセットは --no-defaults で無効化でき、標準で除外するセットは --no-prune で無効化できます。
Distutils 自体のマニフェストテンプレートから、 sdist コマンドがどのようにして Distutils ソース配布物に含めるファイルのリストを作成するか見てみましょう:
setup スクリプトと同様、マニフェストテンプレート中のディレクトリ名は常にスラッシュ区切りで表記します; Distutils は、こうしたディレクトリ名を注意深くプラットフォームでの標準的な表現に変換します。このため、マニフェストテンプレートは複数のオペレーティングシステムにわたって可搬性を持ちます。
マニフェストテンプレートコマンド一覧:
コマンド | 説明 |
---|---|
include pat1 pat2 ... | リストされたパターンのどれかにマッチする全てのファイルを含める |
exclude pat1 pat2 ... | リストされたパターンのどれかにマッチする全てのファイルを除外する |
recursive-include dir pat1 pat2 ... | dir 配下の、リストされたパターンのどれかにマッチする全てのファイルを含める |
recursive-exclude dir pat1 pat2 ... | dir 配下の、リストされたパターンのどれかにマッチする全てのファイルを除外する |
global-include pat1 pat2 ... | ソースツリー内にある、リストされたパターンのどれかにマッチする全てのファイルを含める |
global-exclude pat1 pat2 ... | ソースツリー内にある、リストされたパターンのどれかにマッチする全てのファイルを除外する |
prune dir | dir 配下の全てのファイルを除外する |
graft dir | dir 配下の全てのファイルを含める |
ここで使うパターンは、 Unix スタイルの “glob” パターンです。 * は通常のファイル名文字の任意のシーケンスにマッチします。 ? は通常のファイル名文字の1文字にマッチします。 [range] は range に含まれる全ての文字にマッチします (例: a-z, a-zA-Z, a-f0-9_.) 通常のファイル名文字は、プラットフォーム依存になります。 Unix ではスラッシュ以外の全ての文字で、 Windows ではコロンとバックスラッシュ以外の全ての文字です。
バージョン 2.7 で変更: sdist は既存の生成された MANIFEST ファイルを MANIFEST.in や setup.py の変更時刻と比較すること無しに 再生成します。