.. _source-dist:

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

:ref:`distutils-simple-example` 節で示したように、ソースコード配布物を作成するには :command:`sdist`
コマンドを使います。最も単純な例では、 ::

   python setup.py sdist

のようにします (ここでは、 :command:`sdist` に関するオプションを setup スクリプトや設定ファイル中で行っていないものと仮定します)。
:command:`sdist` は、現在のプラットフォームでのデフォルトのアーカイブ形式でアーカイブを生成します。デフォルトの形式は Unixでは gzip
で圧縮された tar ファイル形式 (:file:`.tar.gz`) で、Windows では ZIP 形式です。

:option:`--formats` オプションを使えば、好きなだけ圧縮形式を指定できます。例えば::

   python setup.py sdist --formats=gztar,zip

は、gzip された tarball と zip ファイルを作成します。利用可能な形式は以下の通りです:

.. %

+-----------+----------------------------------+---------+
| 形式      | 説明                             | 注記    |
+===========+==================================+=========+
| ``zip``   | zip ファイル (:file:`.zip`)      | (1),(3) |
+-----------+----------------------------------+---------+
| ``gztar`` | gzip 圧縮された tar ファイル     | (2),(4) |
|           | (:file:`.tar.gz`)                |         |
+-----------+----------------------------------+---------+
| ``bztar`` | bzip2 圧縮された tar ファイル    | \(4)    |
|           | (:file:`.tar.bz2`)               |         |
+-----------+----------------------------------+---------+
| ``ztar``  | compress 圧縮された tar ファイル | \(4)    |
|           | (:file:`.tar.Z`)                 |         |
+-----------+----------------------------------+---------+
| ``tar``   | tar ファイル (:file:`.tar`)      | \(4)    |
+-----------+----------------------------------+---------+

注記:

(1)
   Windows でのデフォルトです

(2)
   Unixでのデフォルトです

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

(4)
   外部ユーティリティ: :program:`tar` 、場合によっては :program:`gzip`, :program:`bzip2` 、または
   :program:`compress` も必要です


.. _manifest:

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

明確なファイルのリスト (またはファイルリストを生成する方法) を明示的に与えなかった場合、 :command:`sdist`
コマンドはソース配布物に以下のような最小のデフォルトのセットを含めます:

* :option:`py_modules` と :option:`packages` オプションに指定された Python ソースファイル全て

* :option:`ext_modules` や :option:`libraries` オプションに記載された C ソースファイル

  **\*\*** (C ライブラリソースの取得機構は現状ではうまく動きません -- :file:`build_clib.py` には、
  :meth:`get_source_files` メソッドがありません!) **\*\***

* :option:`scripts` オプションで指定されたスクリプト

* テストスクリプトと思しきファイル全て: :file:`test/test\*.py` (現状では、Distutils
  はテストスクリプトをただソース配布物に含めるだけですが、将来は Python モジュール配布物に対するテスト標準ができるかもしれません)

* :file:`README.txt` (または :file:`README`)、 :file:`setup.py`  (または setup
  スクリプトにしているもの) 、および :file:`setup.cfg`

上記のセットで十分なこともありますが、大抵他のファイルを配布物に含めたいと思うでしょう。普通は、 :file:`MANIFEST.in` と呼ばれる
*マニフェストテンプレート (manifest template)* を使ってこれを行います。マニフェストテンプレートは、ソース配布物に
含めるファイルの正確なリストであるマニフェストファイル :file:`MANIFEST` をどうやって作成するか指示しているリストです。
:command:`sdist` コマンドはこのテンプレートを処理し、書かれた指示とファイルシステム上に見つかったファイルに基づいて
マニフェストファイルを作成します。

自分用のマニフェストファイルを書きたいなら、その形式は簡単です: 一行あたり一つの通常ファイル (または通常ファイルに対するシンボリックリンク)
だけを書きます。自分で :file:`MANIFEST` を提供する場合、全てを自分で指定しなければなりません:
ただし、上で説明したデフォルトのファイルセットは、この中には含まれません。

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

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

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

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

* Distutls の "build" (デフォルトの名前は :file:`build`) ツリー下にある全てのファイル

* :file:`RCS`, :file:`CVS`, :file:`.svn`, :file:`.hg`, :file:`.git`, :file:`.bzr`, :file:`_darcs`
  といった名前のディレクトリ下にある全てのファイル

こうして完全なファイルのリストができ、後で参照するためにマニフェストに書き込まれます。この内容は、ソース配布物のアーカイブを作成する際に使われます。

含めるファイルのデフォルトセットは :option:`--no-defaults` で無効化でき、標準で除外するセットは
:option:`--no-prune` で無効化できます。

Distutils 自体のマニフェストテンプレートから、 :command:`sdist` コマンドがどのようにして Distutils
ソース配布物に含めるファイルのリストを作成するか見てみましょう:

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

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

#. :file:`test/test\*.py` (標準のファイルセット) を含めます

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

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

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

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

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


.. _manifest-options:

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

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

* マニフェストファイル :file:`MANIFEST` が存在しなければ、 :file:`MANIFEST.in`
  を読み込んでマニフェストファイルを作成します

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

* :file:`MANIFEST.in` または (:file:`setup.py`) が :file:`MANIFEST`
  より新しければ、 :file:`MANIFEST.in` を読み込んで :file:`MANIFEST` を生成します

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

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

第二に、マニフェストファイルの再生成を強制できます --- 例えば、現在マニフェストテンプレート内に指定しているパターンにマッチする
ファイルやディレクトリを追加したり削除したりすると、マニフェストを再生成しなくてはなりません::

   python setup.py sdist --force-manifest

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

   python setup.py sdist --manifest-only

:option:`--manifest-only` を行うと、 :option:`--force-manifest` を呼び出します。 :option:`-o`
は :option:`--manifest-only` のショートカット、 :option:`-f` は :option:`--force-manifest`
のショートカットです。


