4. ソースコード配布物を作成する¶
簡単な例 節で示したように、ソースコード配布物を作成するには 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 ) |
|
xztar |
xz 圧縮された tar ファイル (.tar.xz ) |
|
ztar |
compress 圧縮された tar ファイル (.tar.Z ) |
(4) |
tar |
tar ファイル (.tar ) |
バージョン 3.5 で変更: xztar
形式のサポートが追加されました。
注釈:
- Windows でのデフォルト形式です
- Unixでのデフォルト形式です
- 外部ユーティリティの zip か、
zipfile
モジュール (Python 1.6 からは標準 Python ライブラリの一部になっています) が必要です - compress プログラムが必要です。このフォーマットは廃止が検討されていて、将来のバージョンの Python では削除されるであろうことに注意してください。
tar
フォーマットのどれか (gztar
, bztar
, xztar
, ztar
, tar
) を利用する時、 Unix ではアーカイブ内の各メンバに設定される owner
と group
名を指定することができます。
例えば、アーカイブ内の全てのファイルの所有者を root にするには、次のようにします。
python setup.py sdist --owner=root --group=root
4.1. 配布するファイルを指定する¶
明確なファイルのリスト (またはファイルリストを生成する方法) を明示的に与えなかった場合、 sdist コマンドはソース配布物に以下のような最小のデフォルトのセットを含めます:
py_modules
とpackages
オプションに指定された Python ソースファイル全てext_modules
オプションとlibraries
オプションで挙げられている C ソースファイル全てscripts
オプションで指定されたスクリプト。 スクリプトをインストールする を参照してください。- テストスクリプトと思しきファイル全て:
test/test*.py
(現状では、Distutils はテストスクリプトをただソース配布物に含めるだけですが、将来は Python モジュール配布物に対するテスト標準ができるかもしれません) README.txt
(またはREADME
)、setup.py
(または setup スクリプトにしているもの) 、およびsetup.cfg
package_data
メタデータにマッチする全てのファイル。 パッケージデータをインストールする を参照してください。data_files
メタデータにマッチする全てのファイル。 追加のファイルをインストールする を参照してください。
上記のセットで十分なこともありますが、大抵他のファイルを配布物に含めたいと思うでしょう。普通は、 MANIFEST.in
と呼ばれる マニフェストテンプレート (manifest template) を使ってこれを行います。マニフェストテンプレートは、ソース配布物に含めるファイルの正確なリストであるマニフェストファイル MANIFEST
をどうやって作成するか指示しているリストです。 sdist コマンドはこのテンプレートを処理し、書かれた指示とファイルシステム上に見つかったファイルに基づいてマニフェストファイルを作成します。
自分用のマニフェストファイルを書きたいなら、その形式は簡単です: 一行あたり一つの通常ファイル (または通常ファイルに対するシンボリックリンク) だけを書きます。自分で MANIFEST
を提供する場合、全てを自分で指定しなければなりません: ただし、上で説明したデフォルトのファイルセットは、この中には含まれません。
バージョン 3.1 で変更: sdist は MANIFEST.in
もしくは setup.py
と更新時刻を比較せずに、生成されて既に存在している MANIFEST
を再生成します。
バージョン 3.1.3 で変更: MANIFEST
ファイルの先頭に、生成されたものであることを示すコメントが付きます。このコメントが無いファイルは上書きや削除はされません。
バージョン 3.2.2 で変更: 以前そうであったように、 MANIFEST.in
が無い場合、 sdist は MANIFEST
を読みに行きます。
マニフェストテンプレートには 1 行ごとに 1 つのコマンドがあり、それぞれのコマンドはソース配布物に含む、もしくは含まないファイルの集合を指定します。例として、再度 Distutils 自身のマニフェストテンプレートに戻りましょう:
include *.txt
recursive-include examples *.txt *.py
prune examples/sample?/build
その意味はかなり明白です: 配布物ルートの *.txt
のパターンに当て嵌まる全てのファイルと、 examples
ディレクトリ以下の *.txt
または *.py
のパターンに当て嵌まる全てのファイルを含み、 examples/sample?/build
のパターンに当て嵌まる全てのディレクトリを除外します。これらの処理は、標準で含むファイル一式が定まった 後に 行われ、マニフェストテンプレートに明示的に指示を書くことで、標準のファイル一式からファイルを除外することができます。 (もしくは、 --no-defaults
オプションを使って、標準のファイル一式の定義を全て無効にすることもできます。) マニフェストテンプレートの小言語では、他にもいくつかのコマンドが利用できます; ソース配布物を生成する: sdist コマンド を参照してください。
マニフェストテンプレート中のコマンドの順番には意味があります; 初期状態では、上で述べたようなデフォルトのファイルがあり、テンプレート中の各コマンドによって、逐次ファイルを追加したり除去したりしていいます。マニフェストテンプレートを完全に処理し終えたら、ソース配布物中に含めるべきでない以下のファイルをリストから除去します:
- Distutls の "build" (デフォルトの名前は
build/
) ツリー下にある全てのファイル RCS
,CVS
,.svn
,.hg
,.git
,.bzr
,_darcs
といった名前のディレクトリ下にある全てのファイル
こうして完全なファイルのリストができ、後で参照するためにマニフェストに書き込まれます。この内容は、ソース配布物のアーカイブを作成する際に使われます。
含めるファイルのデフォルトセットは --no-defaults
で無効化でき、標準で除外するセットは --no-prune
で無効化できます。
Distutils 自体のマニフェストテンプレートから、 sdist コマンドがどのようにして Distutils ソース配布物に含めるファイルのリストを作成するか見てみましょう:
distutils
ディレクトリ、およびdistutils/command
サブディレクトリの下にある全ての Python ソースファイルを含めます (これらの二つのディレクトリが、setup スクリプト下のpackages
オプションに記載されているからです — setup スクリプトを書く を参照してください)README.txt
,setup.py
, およびsetup.cfg
(標準のファイルセット) を含めますtest/test*.py
(標準のファイルセット) を含めます- 配布物ルート下の
*.txt
を含めます (この処理で、README.txt
がもう一度見つかりますが、こうした冗長性は後で刈り取られます) examples
下にあるサブツリー内で*.txt
または*.py
にマッチする全てのファイルを含めます- ディレクトリ名が
examples/sample?/build
にマッチするディレクトリ以下のサブツリー内にあるファイル全てを除外します— この操作によって、上の二つのステップでリストに含められたファイルが除外されることがあるので、マニフェストテンプレート内ではrecursive-include
コマンドの後にprune
コマンドを持ってくることが重要です build
ツリー全体、およびRCS
,CVS
,.svn
,.hg
,.git
,.bzr
,_darcs
ディレクトリ全てを除外します。
setup スクリプトと同様、マニフェストテンプレート中のディレクトリ名は常にスラッシュ区切りで表記します; Distutils は、こうしたディレクトリ名を注意深くプラットフォームでの標準的な表現に変換します。このため、マニフェストテンプレートは複数のオペレーティングシステムにわたって可搬性を持ちます。