pytho****@googl*****
pytho****@googl*****
2011年 11月 10日 (木) 01:24:44 JST
Revision: f8a1f1178cd6 Author: Naoki INADA <inada****@klab*****> Date: Wed Nov 9 08:24:03 2011 Log: Update 2.7.2: distutils/sourcedist.rst http://code.google.com/p/python-doc-ja/source/detail?r=f8a1f1178cd6 Modified: /distutils/sourcedist.rst ======================================= --- /distutils/sourcedist.rst Sat Apr 9 01:59:01 2011 +++ /distutils/sourcedist.rst Wed Nov 9 08:24:03 2011 @@ -19,23 +19,21 @@ は、gzip された tarball と zip ファイルを作成します。利用可能な形式は以下の 通りです: -.. % - +-----------+----------------------------------+---------+ | 形式 | 説明 | 注記 | +===========+==================================+=========+ | ``zip`` | zip ファイル (:file:`.zip`) | (1),(3) | +-----------+----------------------------------+---------+ -| ``gztar`` | gzip 圧縮された tar ファイル | (2),(4) | +| ``gztar`` | gzip 圧縮された tar ファイル | \(2) | | | (:file:`.tar.gz`) | | +-----------+----------------------------------+---------+ -| ``bztar`` | bzip2 圧縮された tar ファイル | \(4) | +| ``bztar`` | bzip2 圧縮された tar ファイル | | | | (:file:`.tar.bz2`) | | +-----------+----------------------------------+---------+ | ``ztar`` | compress 圧縮された tar ファイル | \(4) | | | (:file:`.tar.Z`) | | +-----------+----------------------------------+---------+ -| ``tar`` | tar ファイル (:file:`.tar`) | \(4) | +| ``tar`` | tar ファイル (:file:`.tar`) | | +-----------+----------------------------------+---------+ 注記: @@ -51,9 +49,15 @@ 標準ライブラリになっています) (4) - 外部ユーティリティ: :program:`tar` 、場合によって は :program:`gzip`, :program:`bzip2` 、または - :program:`compress` も必要です - + 外部ユーティリティ :program:`compress` が必要です。 + このフォーマットは廃止待ちで、将来のバージョンの Python では削除されるで しょう。 + +``tar`` フォーマットのどれか (``gztar``, ``bztar``, ``ztar``, ``tar``) を Unix で利用する時、 +アーカイブ内の各メンバに設定される ``owner`` と ``group`` 名を指定すること ができます。 + +例えば、アーカイブ内の全てのファイルの所有者を root にするには、次のように します。 :: + + python setup.py sdist --owner=root --group=root .. _manifest: @@ -70,7 +74,8 @@ .. XXX C ライブラリソースの取得機構は現状ではうまく動きません -- :file:`build_clib.py` には、 :meth:`get_source_files` メソッドがありません! -* :option:`scripts` オプションで指定されたスクリプト +* :option:`scripts` オプションで指定されたスクリプト。 + :ref:`distutils-installing-scripts` を参照してください。 * テストスクリプトと思しきファイル全て: :file:`test/test\*.py` (現状では、 Distutils はテストスクリプトをただソース配布物に含めるだけですが、将来は Python モ ジュール配布物に対するテスト標準ができるかもしれません) @@ -78,6 +83,12 @@ * :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` を どうやって作成するか指示しているリストです。 @@ -88,8 +99,71 @@ だけを書きます。自分で :file:`MANIFEST` を提供する場合、全てを自分で指定し なければなりません: ただし、上で説明したデフォルトのファイルセットは、この中には含まれません。 -マニフェストテンプレートには一行あたり一つのコマンドがあります。各コマンド はソース配布物に入れたり配布物から除外したりするファイルのセットを指定しま す。 -例えば、Distutils 自体のマニフェストテンプレートの話に戻ると:: +.. 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: + +.. The MANIFEST.in 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 @@ -98,9 +172,8 @@ 各行はかなり明確に意味を取れるはずです: 上の指定では、 ``*.txt`` にマッチす る配布物ルート下の全てのファイル、 :file:`examples` ディレクトリ下にある ``*.txt`` か ``*.py`` にマッチする全てのファイルを含 め、 ``examples/sample?/build`` にマッチする全てのファイルを除外します。これらの処理はすべて、標準的に含め られるファイルセットの評価よりも *後に* -行われるので、マニフェストテンプレートに明示的に指示をしておけば、標準セッ ト中のファイルも除外できます。 (:option:`--no-defaults` -オプションを設定して、標準セット自体を無効にもできます。) 他にも、このマニ フェストテンプレート記述のためのミニ言語にはいくつかのコマンドがあります: -:ref:`sdist-cmd` 節を参照してください。 +行われるので、マニフェストテンプレートに明示的に指示をしておけば、標準セッ ト中のファイルも除外できます。 +(:option:`--no-defaults` オプションを設定して、標準セット自体を無効にもでき ます。) マニフェストテンプレート中のコマンドの順番には意味があります; 初期状態で は、上で述べたようなデフォルトのファイルがあり、 テンプレート中の各コマンドによって、逐次ファイルを追加したり除去したりして いいます。マニフェストテンプレートを完全に @@ -146,31 +219,47 @@ 名を注意深くプラットフォームでの標準的な表現に変換します。このため、マニフ ェストテンプレートは複数のオペレーティングシステムにわたって可搬性を持ちま す。 -.. _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` のショートカットです。 - - +.. 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` の変更時刻と比較すること無しに + 再生成します。
