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

簡単な例 節で示したように、ソースコード配布物を作成するには **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. requires the **compress** program.

When using any "tar" format ("gztar", "bztar", "ztar" or "tar") under
Unix, you can specify the "owner" and "group" names that will be set
for each member of the archive.

例えば、アーカイブ内の全てのファイルの所有者を root にするには、次のよ
うにします。

   python setup.py sdist --owner=root --group=root


配布するファイルを指定する
==========================

明確なファイルのリスト (またはファイルリストを生成する方法) を明示的に
与えなかった場合、 **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 で変更: **sdist** will read a "MANIFEST" file if no
"MANIFEST.in" exists, like it did before 2.7.

See The MANIFEST.in template section for a syntax reference.


マニフェスト (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" のショートカットです。


The MANIFEST.in template
========================

A "MANIFEST.in" file can be added in a project to define the list of
files to include in the distribution built by the **sdist** command.

When **sdist** is run, it will look for the "MANIFEST.in" file and
interpret it to generate the "MANIFEST" file that contains the list of
files that will be included in the package.

This mechanism can be used when the default list of files is not
enough. (See 配布するファイルを指定する).


Principle
---------

The manifest template has one command per line, where each command
specifies a set of files to include or exclude from the source
distribution.  For an example, let’s look at the Distutils』 own
manifest template:

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

The meanings should be fairly clear: include all files in the
distribution root matching "*.txt", all files anywhere under the
"examples" directory matching "*.txt" or "*.py", and exclude all
directories matching "examples/sample?/build".  All of this is done
*after* the standard include set, so you can exclude files from the
standard set with explicit instructions in the manifest template.
(Or, you can use the "--no-defaults" option to disable the standard
set entirely.)

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

* 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 は、こうしたディレクトリ名を
注意深くプラットフォームでの標準的な表現に変換します。このため、マニフ
ェストテンプレートは複数のオペレーティングシステムにわたって可搬性を持
ちます。


Commands
--------

The manifest template commands are:

+---------------------------------------------+-------------------------------------------------+
| Command                                     | 説明                                            |
+=============================================+=================================================+
| **include pat1 pat2 ...**                   | include all files matching any of the listed    |
|                                             | patterns                                        |
+---------------------------------------------+-------------------------------------------------+
| **exclude pat1 pat2 ...**                   | exclude all files matching any of the listed    |
|                                             | patterns                                        |
+---------------------------------------------+-------------------------------------------------+
| **recursive-include dir pat1 pat2 ...**     | include all files under *dir* matching any of   |
|                                             | the listed patterns                             |
+---------------------------------------------+-------------------------------------------------+
| **recursive-exclude dir pat1 pat2 ...**     | exclude all files under *dir* matching any of   |
|                                             | the listed patterns                             |
+---------------------------------------------+-------------------------------------------------+
| **global-include pat1 pat2 ...**            | include all files anywhere in the source tree   |
|                                             | matching — & any of the listed patterns         |
+---------------------------------------------+-------------------------------------------------+
| **global-exclude pat1 pat2 ...**            | exclude all files anywhere in the source tree   |
|                                             | matching — & any of the listed patterns         |
+---------------------------------------------+-------------------------------------------------+
| **prune dir**                               | exclude all files under *dir*                   |
+---------------------------------------------+-------------------------------------------------+
| **graft dir**                               | include all files under *dir*                   |
+---------------------------------------------+-------------------------------------------------+

The patterns here are Unix-style 「glob」 patterns: "*" matches any
sequence of regular filename characters, "?" matches any single
regular filename character, and "[range]" matches any of the
characters in *range* (e.g., "a-z", "a-zA-Z", "a-f0-9_.").  The
definition of 「regular filename character」 is platform-specific: on
Unix it is anything except slash; on Windows anything except backslash
or colon.
