4. ソースコード配布物を作成する
*******************************

注釈:

  このドキュメントは、
  https://setuptools.readthedocs.io/en/latest/setuptools.html にある
  "setuptools" のドキュメントが現時点でここにある関連情報を全て網羅す
  るまで、単独でここに載せておかれます。

簡単な例 節で示したように、ソースコード配布物を作成するには **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 ファ  | (2)           |
|             | イル (".tar.gz")          |               |
+-------------+---------------------------+---------------+
| "bztar"     | bzip2 圧縮された tar ファ | (5)           |
|             | イル (".tar.bz2")         |               |
+-------------+---------------------------+---------------+
| "xztar"     | xz 圧縮された tar ファイ  | (5)           |
|             | ル (".tar.xz")            |               |
+-------------+---------------------------+---------------+
| "ztar"      | compress 圧縮された tar   | (4),(5)       |
|             | ファイル (".tar.Z")       |               |
+-------------+---------------------------+---------------+
| "tar"       | tar ファイル (".tar")     | (5)           |
+-------------+---------------------------+---------------+

バージョン 3.5 で変更: "xztar" 形式のサポートが追加されました。

注釈:

1. Windows でのデフォルト形式です

2. Unixでのデフォルト形式です

3. 外部ユーティリティの **zip** か、 "zipfile" モジュール (Python 1.6
   からは標準 Python ライブラリの一部になっています) が必要です

4. **compress** プログラムが必要です。このフォーマットは廃止が検討され
   ていて、将来のバージョンの Python では削除されるであろうことに注意
   してください。

5. deprecated by PEP 527; PyPI only accepts ".zip" and ".tar.gz"
   files.

"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 ファイル ("README", "README.txt", "README.rst") のどれか
  、 "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" を読みに行きます。

バージョン 3.7 で変更: "README.rst" が distutils の標準 README のリス
トに含まれるようになりました。

マニフェストテンプレートには 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 ソース配布物に含めるファイルのリストを作成する
か見てみましょう:

1. "distutils" ディレクトリ、および "distutils/command" サブディレクト
   リの下にある全ての Python ソースファイルを含めます (これらの二つの
   ディレクトリが、setup スクリプト下の "packages" オプションに記載さ
   れているからです --- setup スクリプトを書く を参照してください)

2. "README.txt", "setup.py", および "setup.cfg" (標準のファイルセット)
   を含めます

3. "test/test*.py" (標準のファイルセット) を含めます

4. 配布物ルート下の "*.txt" を含めます (この処理で、 "README.txt" がも
   う一度見つかりますが、こうした冗長性は後で刈り取られます)

5. "examples" 下にあるサブツリー内で "*.txt" または "*.py" にマッチす
   る全てのファイルを含めます

6. ディレクトリ名が "examples/sample?/build" にマッチするディレクトリ
   以下のサブツリー内にあるファイル全てを除外します--- この操作によっ
   て、上の二つのステップでリストに含められたファイルが除外されること
   があるので、マニフェストテンプレート内では "recursive-include" コマ
   ンドの後に "prune" コマンドを持ってくることが重要です

7. "build" ツリー全体、および "RCS", "CVS", ".svn", ".hg", ".git",
   ".bzr", "_darcs" ディレクトリ全てを除外します。

setup スクリプトと同様、マニフェストテンプレート中のディレクトリ名は常
にスラッシュ区切りで表記します; Distutils は、こうしたディレクトリ名を
注意深くプラットフォームでの標準的な表現に変換します。このため、マニフ
ェストテンプレートは複数のオペレーティングシステムにわたって可搬性を持
ちます。


4.2. マニフェスト (manifest) 関連のオプション
=============================================

**sdist** コマンドが通常行う処理の流れは、以下のようになっています:

* マニフェストファイル (デフォルトでは "MANIFEST") が存在し、1行目に
  "MANIFEST.in" から生成されたことを示すコメントが無い場合は、変更を加
  えずにそのまま使用します

* マニフェストファイルが存在しないか、前回自動生成されていた場合は、
  "MANIFEST.in" を読み込み、マニフェストを作成します

* "MANIFEST" も "MANIFEST.in" もなければ、デフォルトのファイルセットだ
  けでできたマニフェストファイルを作成します

* (生成されたか、読み出された) "MANIFEST" 内にあるファイルのリストを使
  ってソース配布物アーカイブを作成します

上の動作は二種類のオプションを使って変更できます。まず、標準の
"include" および "exclude" セットを無効化するには "--no-defaults" およ
び "--no-prune"  を使います。

第2に、単にマニフェストを (再)生成したいだけで、ソース配布物は作成した
くない場合があるかもしれません:

   python setup.py sdist --manifest-only

"-o" は "--manifest-only" のショートカットです。
