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

注記:

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

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

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

(4)
   外部ユーティリティ :program:`compress` が必要です。
   このフォーマットは廃止待ちで、将来のバージョンの Python では削除されるでしょう。

``tar`` フォーマットのどれか (``gztar``, ``bztar``, ``ztar``, ``tar``) を Unix で利用する時、
アーカイブ内の各メンバに設定される ``owner`` と ``group`` 名を指定することができます。

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

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

.. _manifest:

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

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

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

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

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

* :option:`scripts` オプションで指定されたスクリプト。
  :ref:`distutils-installing-scripts` を参照してください。

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

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

* ``package_data`` メタデータにマッチする全てのファイル。
  :ref:`distutils-installing-package-data` を参照してください。

* ``data_files`` メタデータにマッチする全てのファイル。
  :ref:`distutils-additional-files` を参照してください。

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

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

.. versionadded:: 2.7
   :file:`MANIFEST` のコメントで始まるファイルは、それが生成されたものであることを表します。
   そうでないファイルは上書きされたり削除されたりしません。

シンタックスリファレンスは :ref:`manifest_template` を参照してください。


.. _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`  を使います。

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

   python setup.py sdist --manifest-only

:option:`-o` は :option:`--manifest-only` のショートカットです。


.. _manifest_template:

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

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

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

This mechanism can be used when the default list of files is not enough.
(See :ref:`manifest`).
この機構は、デフォルトのファイルリストが十分でないときに利用できます。
(:ref:`manifest` を参照)

.. Principle

原則
---------

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

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

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

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

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


.. Commands

コマンド
--------

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

+-------------------------------------------+-----------------------------------------------+
| コマンド                                  | 説明                                          |
+===========================================+===============================================+
| :command:`include pat1 pat2 ...`          | リストされたパターンのどれかにマッチする全て  |
|                                           | のファイルを含める                            |
+-------------------------------------------+-----------------------------------------------+
| :command:`exclude pat1 pat2 ...`          | リストされたパターンのどれかにマッチする全て  |
|                                           | のファイルを除外する                          |
+-------------------------------------------+-----------------------------------------------+
| :command:`recursive-include dir pat1 pat2 | *dir* 配下の、リストされたパターンのどれかに  |
| ...`                                      | マッチする全てのファイルを含める              |
+-------------------------------------------+-----------------------------------------------+
| :command:`recursive-exclude dir pat1 pat2 | *dir* 配下の、リストされたパターンのどれかに  |
| ...`                                      | マッチする全てのファイルを除外する            |
+-------------------------------------------+-----------------------------------------------+
| :command:`global-include pat1 pat2 ...`   | ソースツリー内にある、リストされたパターンの  |
|                                           | どれかにマッチする全てのファイルを含める      |
+-------------------------------------------+-----------------------------------------------+
| :command:`global-exclude pat1 pat2 ...`   | ソースツリー内にある、リストされたパターンの  |
|                                           | どれかにマッチする全てのファイルを除外する    |
+-------------------------------------------+-----------------------------------------------+
| :command:`prune dir`                      | *dir* 配下の全てのファイルを除外する          |
+-------------------------------------------+-----------------------------------------------+
| :command:`graft dir`                      | *dir* 配下の全てのファイルを含める            |
+-------------------------------------------+-----------------------------------------------+

ここで使うパターンは、 Unix スタイルの "glob" パターンです。
``*`` は通常のファイル名文字の任意のシーケンスにマッチします。
``?`` は通常のファイル名文字の1文字にマッチします。
``[range]`` は *range* に含まれる全ての文字にマッチします (例: ``a-z``, ``a-zA-Z``, ``a-f0-9_.``)
通常のファイル名文字は、プラットフォーム依存になります。 Unix ではスラッシュ以外の全ての文字で、
Windows ではコロンとバックスラッシュ以外の全ての文字です。

.. versionchanged:: 2.7
    :command:`sdist` は既存の生成された :file:`MANIFEST` ファイルを
    :file:`MANIFEST.in` や :file:`setup.py` の変更時刻と比較すること無しに
    再生成します。
