1. Distutilsの紹介
******************

注釈:

  このドキュメントは、
  https://setuptools.readthedocs.io/en/latest/setuptools.html にある
  "setuptools" のドキュメントが現時点でここにある関連情報を全て網羅す
  るまで、単独でここに載せておかれます。

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


1.1. 概念と用語
===============

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

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

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

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

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

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

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


1.2. 簡単な例
=============

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 といった追加のメタデ
  ータを入れておくよう奨めます (setup スクリプトを書く の例を参照して
  ください)

このモジュールのソース配布物を作成するには、上記のコードが書かれた
setup スクリプト "setup.py" を作成し、端末からこのコマンドを実行してく
ださい:

   python setup.py sdist

Windows では、コマンドプロンプトのウィンドウを開き (スタート ‣ アクセ
サリ) 、次のようにコマンドを変えてください:

   setup.py sdist

**sdist** は、 setup スクリプト "setup.py" とモジュール "foo.py" を含
むアーカイブファイル (例。 Unix の tarball や Windows の ZIP ファイル)
を作成します。アーカイブファイルは "foo-1.0.tar.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** はどちらかというとイン
ストール作業者向けです (とはいえ、ほとんどの開発者は自分のコードをイン
ストールしたくなることがあるでしょう)。

その他の有用な配布形態としては、 **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


1.3. Python 一般の用語
======================

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

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

pure Python モジュール
   Python で書かれ、単一の ".py"  ファイル内に収められたモジュールです
   (".pyc" ファイルと関連があります) 。 "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) の部分にあたるパッケージです。(この部
   分には "__init__.py" ファイルがないので、本当のパッケージではありま
   せんが、便宜上そう呼びます。) 標準ライブラリの大部分はルートパッケ
   ージに入っています、また、多くの小規模な単体のサードパーティモジュ
   ールで、他の大規模なモジュールコレクションに属していないものもここ
   に入ります。正規のパッケージと違い、ルートパッケージ上のモジュール
   の実体は様々なディレクトリにあります: 実際は、 "sys.path" に列挙さ
   れているディレクトリ全てが、ルートパッケージに配置されるモジュール
   の内容に影響します。


1.4. Distutils 固有の用語
=========================

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

モジュール配布物
   単一のダウンロード可能なリソースとして配布され、*一纏めに* インスト
   ールできる Python モジュールの集まりです。よく知られているモジュー
   ル配布物の例は NumPy、SciPy、Pillow、mxBase です。(Python の文脈で
   既に使われてるとき以外は、これは *パッケージ* と呼ばれます: 1 つの
   モジュール配布物は 0 個か 1 個かもっと多くの Python パッケージを含
   みます。)

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

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

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