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 ファ  | (2)       |
|             | イル (".tar.gz")          |           |
+-------------+---------------------------+-----------+
| "bztar"     | bzip2 圧縮された tar ファ |           |
|             | イル (".tar.bz2")         |           |
+-------------+---------------------------+-----------+
| "ztar"      | compress 圧縮された tar   | (4)       |
|             | ファイル (".tar.Z")       |           |
+-------------+---------------------------+-----------+
| "tar"       | tar ファイル (".tar")     |           |
+-------------+---------------------------+-----------+

注釈:

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

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

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

4. **compress** プログラムが必要です。

"tar" フォーマットのどれか ("gztar", "bztar", "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" を提供する場合、全てを自分で指定しな
ければなりません: ただし、上で説明したデフォルトのファイルセットは、こ
の中には含まれません。

バージョン 2.7 で変更: **sdist** は "MANIFEST.in" もしくは "setup.py"
と更新時刻を比較せずに、生成されて既に存在している "MANIFEST" を再生成
します。

バージョン 2.7.1 で変更: "MANIFEST" ファイルの先頭に、生成されたもので
あることを示すコメントが付きます。このコメントが無いファイルは上書きや
削除はされません。

バージョン 2.7.3 で変更: 2.7 以前でそうしていたように、 "MANIFEST.in"
が無い場合、 **sdist** は "MANIFEST" を読みに行きます。

シンタックスリファレンスは MANIFEST.in テンプレート を参照してください
。


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" のショートカットです。


4.3. MANIFEST.in テンプレート
=============================

**sdist** コマンドがビルドする配布物に含めるファイルのリストを定義する
ために、プロジェクトに "MANIFEST.in" ファイルを追加することができます
。

**sdist** が実行された時、 "MANIFEST.in" ファイルを探して、それを解釈
して、パッケージに含めるファイルのリストを含んだ "MANIFEST" ファイルを
生成します。

この機構は、デフォルトのファイルリストが十分でないときに利用できます。
(配布するファイルを指定する を参照)


4.3.1. 原則
-----------

マニフェストテンプレートには一行あたり一つのコマンドがあります。各コマ
ンドはソース配布物に入れたり配布物から除外したりするファイルのセットを
指定します。例えば、Distutils 自体のマニフェストテンプレートを見てみま
しょう:

   include *.txt
   recursive-include examples *.txt *.py
   prune examples/sample?/build

各行はかなり明確に意味を取れるはずです: 上の指定では、 "*.txt" にマッ
チする配布物ルート下の全てのファイル、 "examples" ディレクトリ下にある
"*.txt" か "*.py" にマッチする全てのファイルを含め、
"examples/sample?/build" にマッチする全てのファイルを除外します。これ
らの処理はすべて、標準的に含められるファイルセットの評価よりも *後に*
行われるので、マニフェストテンプレートに明示的に指示をしておけば、標準
セット中のファイルも除外できます。 ("--no-defaults" オプションを設定し
て、標準セット自体を無効にもできます。)

マニフェストテンプレート中のコマンドの順番には意味があります; 初期状態
では、上で述べたようなデフォルトのファイルがあり、テンプレート中の各コ
マンドによって、逐次ファイルを追加したり除去したりしていいます。マニフ
ェストテンプレートを完全に処理し終えたら、ソース配布物中に含めるべきで
ない以下のファイルをリストから除去します:

* 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.3.2. コマンド
---------------

マニフェストテンプレートコマンド一覧:

+---------------------------------------------+-------------------------------------------------+
| コマンド                                    | 説明                                            |
+=============================================+=================================================+
| **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 ではコロンとバックスラッシュ以外の全ての文字です
。
