#
2 概念と用語

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

- setup スクリプト (setup.py という名前にするのがならわし) を書く
- (必要があれば) setup 設定ファイルを書く
- ソースコード配布物を作成する
- (必要があれば) 一つまたはそれ以上のビルド済み (バイナリ) 形式の 配布物を作成する

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

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

##
2.1 簡単な例

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

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

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

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

- Distutils に与えなければならない情報のほとんどは、 `setup()` 関数のキーワード引数として与えます。
- キーワード引数は二つのカテゴリ: パッケージのメタデータ (パッケージ名、バージョン番号) 、パッケージに何が収められているか の情報 (上の場合は pure Python モジュールのリスト)、に行き着きます。
- モジュールはファイル名ではなく、モジュール名で指定します (パッケージと拡張モジュールについても同じです)
- 作者名、電子メールアドレス、プロジェクトの URL といった 追加のメタデータを入れておくよう奨めます ( 3 の 例を参照してください)

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

    python setup.py sdist

を実行します。

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

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

    python setup.py install

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

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

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

    python setup.py bdist_wininst

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

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

    python setup.py bdist_rpm

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

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

    python setup.py bdist --help-formats

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

##
2.2 Python 一般の用語

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

モジュール (module)
  Python においてコードを再利用する際の 基本単位: すなわち、他のコードから import されるひとかたまりのコード です。ここでは、三種類のモジュール: pure Python モジュール、 拡張モジュール、パッケージが関わってきます。
pure Python モジュール
  Python で書かれ、単一の .py ファイル内に収められたモジュールです (.pyc かつ/または .pyo ファイルと関連があります) 。 ``pure モジュール (pure module)'' と呼ばれることもあります。
拡張モジュール (extension module)
  Python を実装している 低水準言語: Python の場合は C/C++ 、 Jython の場合は Java 、 で書かれたモジュールです。 通常は、動的にロードできるコンパイル済みの単一のファイルに入っています。 例えば、Unix向け Python 拡張のための共有オブジェクト (.so) 、 Windows 向け Python 拡張のための DLL (.pyd という拡張子が与えら れています)、 Jython 拡張のための Java クラスといった具合です。 (現状では、 Distutils は Python 向けの C/C++ 拡張モジュールしか 扱わないので注意してください。)
パッケージ (package)
  他のモジュールが入っているモジュールです; 通常、ファイルシステム内のあるディレクトリに収められ、 __init__.py が入っていることで通常のディレクトリと区別 できます。
ルートパッケージ (root package)
  階層的なパッケージの根 (root) の部分にあたるパッケージです。(この部分には __init__.py ファイルがないので、本当のパッケージではありませんが、便宜上 そう呼びます。) 標準ライブラリの大部分はルートパッケージに入って います、また、多くの小規模な単体のサードパーティモジュールで、他の 大規模なモジュールコレクションに属していないものもここに入ります。 正規のパッケージと違い、ルートパッケージ上のモジュールの実体は様々な ディレクトリにあります: 実際は、`sys.path` に列挙されている ディレクトリ全てが、ルートパッケージに配置されるモジュールの内容に 影響します。

##
2.3 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)
  ソースコードツリー (またはソース配布物) ディレクトリの最上階層で、 setup.py の ある場所です。一般的には、 setup.py はこのディレクトリ上で 実行します。