.. _distutils-intro:

***************
Distutilsの紹介
***************

このドキュメントで扱っている内容は、 Distutils を使った Python  モジュールの配布で、とりわけ開発者/配布者の役割に重点を置いています:
Python モジュールのインストールに関する情報を探しているのなら、 :ref:`install-index`
を参照してください。


.. _distutils-concepts:

概念と用語
==========

Distutils の使い方は、モジュール開発者とサードパーティ製のモジュールをインストールするユーザ/管理者のどちらにとってもきわめて単純です。
開発者側のやるべきことは (もちろん、しっかりした実装で、詳しく文書化され、よくテストされたコードを書くことは別として！) 以下の項目になります:

* setup スクリプト (:file:`setup.py` という名前にするのがならわし) を書く

* (必要があれば) setup 設定ファイルを書く

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

* (必要があれば) 一つまたはそれ以上のビルド済み (バイナリ) 形式の配布物を作成する

これらの作業については、いずれもこのドキュメントで扱っています。

全てのモジュール開発者が複数の実行プラットフォームを利用できるわけではないので、全てのプラットフォーム向けにビルド済みの配布物を提供して
もらえると期待するわけにはいきません。ですから、仲介を行う人々、いわゆる *パッケージ作成者 (packager)* がこの問題を解決すべく
立ち上がってくれることが望ましいでしょう。パッケージ作成者はモジュール開発者がリリースしたソースコード配布物を、一つまたはそれ以上
のプラットフォーム上でビルドして、得られたビルド済み配布物をリリースすることになります。したがって、ほとんどの一般的なプラットフォームに
おけるユーザは、setup スクリプト一つ実行せず、コードを一行たりともコンパイルしなくても、使っているプラットフォーム向けのきわめて普通の
方法でほとんどの一般的な Python モジュール配布物をインストールできるでしょう。


.. _distutils-simple-example:

簡単な例
========

setup スクリプトは通常単純なものですが、Python で書かれているため、スクリプト中で何かを処理しようと考えたとき特に制限はありません。とはいえ、
setup スクリプト中に何かコストの大きな処理を行うときは十分注意してください。 autoconf 形式の設定スクリプトとは違い、 setup
スクリプトはモジュール配布物をビルドしてインストールする中で複数回実行されることがあります。

:file:`foo.py` という名前のファイルに収められている :mod:`foo` という名前のモジュールを配布したいだけなら、setup
スクリプトは以下のような単純なものになります::

   from distutils.core import setup
   setup(name='foo',
         version='1.0',
         py_modules=['foo'],
         )

以下のことに注意してください:

* Distutils に与えなければならない情報のほとんどは、  :func:`setup` 関数のキーワード引数として与えます。

* キーワード引数は二つのカテゴリ: パッケージのメタデータ  (パッケージ名、バージョン番号) 、パッケージに何が収められているかの情報 (上の場合は
  pure Python モジュールのリスト)、に行き着きます。

* モジュールはファイル名ではなく、モジュール名で指定します (パッケージと拡張モジュールについても同じです)

* 作者名、電子メールアドレス、プロジェクトの URL といった追加のメタデータを入れておくよう奨めます ( :ref:`setup-script` の
  例を参照してください)

このモジュールのソースコード配布物を作成するには、上記のコードが入った setup スクリプト :file:`setup.py`
を作成して、以下のコマンド::

   python setup.py sdist

を実行します。

.. %

この操作を行うと、アーカイブファイル (例えば Unixでは tarball、Windows では ZIP ファイル) を作成します。アーカイブファイル
には、setup スクリプト :file:`setup.py` と、配布したいモジュール :file:`foo.py`
が入っています。アーカイブファイルの名前は :file:`foo-1.0.targ.gz` (または :file:`.zip`) になり、展開すると
ディレクトリ :file:`foo-1.0` を作成します。

エンドユーザが :mod:`foo` モジュールをインストールしたければ、 :file:`foo-1.0.tar.gz` (または :file:`.zip`)
をダウンロードし、パッケージを展開して、以下のスクリプトを --- :file:`foo-1.0`  ディレクトリ中で --- 実行します::

   python setup.py install

この操作を行うと、インストールされている Python での適切なサードパーティ製モジュール置き場に :file:`foo.py` を完璧にコピーします．

ここで述べた簡単な例では、 Distutils の基本的な概念のいくつかを示しています。まず、開発者とインストール作業者は同じ基本インタフェース、すなわち
setup スクリプトを使っています。二人の作業の違いは、使っている Distutils *コマンド (command)* にあります:
:command:`sdist` コマンドは、ほぼ完全に開発者だけが対象となる一方、 :command:`install` はどちらかというとインストール
作業者向けです (とはいえ、ほとんどの開発者は自分のコードをインストールしたくなることがあるでしょう)。

ユーザにとって本当に簡単なものにしたいのなら、一つまたはそれ以上のビルド済み配布物を作ってあげられます。例えば、Windows マシン
上で作業をしていて、他の Windows ユーザにとって簡単な配布物を提供したいのなら、実行可能な形式の (このプラットフォーム向けのビルド済み配布物としては
もっとも適切な) インストーラを作成できます。これには :command:`bdist_wininst` を使います。例えば::

   python setup.py bdist_wininst

とすると、実行可能なインストーラ形式、 :file:`foo-1.0.win32.exe` が現在のディレクトリに作成されます。

.. %

その他の有用な配布形態としては、 :command:`bdist_rpm` に実装されている RPM 形式、 Solaris
:program:`pkgtool` (:command:`bdist_pkgtool`) 、 HP-UX :program:`swinstall`
(:command:`bdist_sdux`) があります。例えば、以下のコマンドを実行すると、 :file:`foo-1.0.noarch.rpm`
という名前の RPM ファイルを作成します::

   python setup.py bdist_rpm

(:command:`bdist_rpm` コマンドは :command:`rpm` コマンドを使うため、 Red Hat Linux や SuSE
Linux、 Mandrake Linux といった RPM ベースのシステムで実行しなければなりません)

どの配布形式が利用できるかは、 ::

   python setup.py bdist --help-formats

を実行すれば分かります。

.. %


.. _python-terms:

Python 一般の用語
=================

このドキュメントを読んでいるのなら、モジュール (module)、拡張モジュール (extension) などが何を表すのかをよく知っているかも
しれません。とはいえ、読者がみな共通のスタートポイントに立って Distutils の操作を始められるように、ここで一般的な Python 用語
について以下のような用語集を示しておきます:

モジュール (module)
   Python においてコードを再利用する際の基本単位: すなわち、他のコードから import されるひとかたまりのコード
   です。ここでは、三種類のモジュール: pure Python モジュール、拡張モジュール、パッケージが関わってきます。

pure Python モジュール
   Python で書かれ、単一の :file:`.py`  ファイル内に収められたモジュールです (:file:`.pyc` かつ/または
   :file:`.pyo` ファイルと関連があります) 。 "pure モジュール  (pure module)" と呼ばれることもあります。

拡張モジュール (extension module)
   Python を実装している低水準言語: Python の場合は C/C++ 、 Jython の場合は Java 、で書かれたモジュールです。
   通常は、動的にロードできるコンパイル済みの単一のファイルに入っています。例えば、Unix向け Python 拡張のための共有オブジェクト
   (:file:`.so`) 、 Windows 向け Python 拡張のための DLL (:file:`.pyd` という拡張子が与えられています)、
   Jython 拡張のための Java クラスといった具合です。 (現状では、 Distutils は Python 向けの C/C++ 拡張モジュールしか
   扱わないので注意してください。)

パッケージ (package)
   他のモジュールが入っているモジュールです; 通常、ファイルシステム内のあるディレクトリに収められ、 :file:`__init__.py`
   が入っていることで通常のディレクトリと区別できます。

ルートパッケージ (root package)
   階層的なパッケージの根 (root) の部分にあたるパッケージです。(この部分には :file:`__init__.py`
   ファイルがないので、本当のパッケージではありませんが、便宜上そう呼びます。) 標準ライブラリの大部分はルートパッケージに入って
   います、また、多くの小規模な単体のサードパーティモジュールで、他の大規模なモジュールコレクションに属していないものもここに入ります。
   正規のパッケージと違い、ルートパッケージ上のモジュールの実体は様々なディレクトリにあります: 実際は、 ``sys.path`` に列挙されている
   ディレクトリ全てが、ルートパッケージに配置されるモジュールの内容に影響します。


.. _distutils-term:

Distutils 固有の用語
====================

以下は Distutils を使って Python モジュールを配布する際に使われる特有の用語です:

モジュール配布物 (module distribution)
   一個のファイルとしてダウンロード可能なリソースの形をとり、 *一括して*  インストールされることになっている形態で配られる Python モジュールの
   コレクションです。よく知られたモジュール配布物には、Numeric Python、 PyXML、 PIL (the Python Imaging
   Library)、 mxBase などがあります。 (*パッケージ (package)* と呼ばれることもありますが、 Python
   用語としてのパッケージとは意味が違います: 一つのモジュール配布物の中には、場合によりゼロ個、一つ、それ以上の Python パッケージが入っています。)

pure モジュール配布物 (pure module distribution)
   pure Python モジュールやパッケージだけが入ったモジュール配布物です。"pure 配布物 (pure distribution)" とも呼ばれます。

非 pure モジュール配布物 (non-pure module distribution)
   少なくとも一つの拡張モジュールが入ったモジュール配布物です。 "非 pure 配布物"とも呼びます。

配布物ルートディレクトリ (distribution root)
   ソースコードツリー (またはソース配布物) ディレクトリの最上階層で、 :file:`setup.py` のある場所です。一般的には、
   :file:`setup.py` はこのディレクトリ上で実行します。


