.. highlightlang:: none

.. _install-index:

*************************************
  Python モジュールのインストール
*************************************

:Author: Greg Ward ---  日本語訳: Python ドキュメント翻訳プロジェクト
:Release: |version|
:Date: |today|

.. TODO: Fill in XXX comments

.. topic:: Abstract

   このドキュメントでは、 Python モジュール配布ユーティリティ (Python Distribution Utilities, "Distutils")
   について、  エンドユーザの視点に立ち、サードパーティ製のモジュールや拡張モジュールの構築やインストールによって標準の Python に
   機能を追加する方法について述べます。

.. _inst-intro:

はじめに
========

Python の広範な標準ライブラリは、プログラミングにおける多くの要求をカバーしていますが、時には何らかの新たな機能をサードパーティ製
モジュールの形で追加する必要に迫られます。自分がプログラムを書くときのサポートとして必要な場合もあるし、自分が使いたいアプリケーションがたまたま
Python で書かれていて、そのサポートとして必要な場合もあるでしょう。

以前は、すでにインストール済みの Python に対して、サードパーティ製モジュールを追加するためのサポートはほとんどありませんでした。しかしPython
配布ユーティリティ (Python Distribution Utilities,  略して Distutils) が Python 2.0
から取り入れられ、状況は変わりました。

このドキュメントが主要な対象としているのは、サードパーティモジュールをインストールする必要がある人たち: 単に何らかの Python アプリケーション
を稼動させたいだけのエンドユーザやシステム管理者、そしてすでに Python プログラマであって、新たな道具を自分のツールキットに加えたい
と思っている人たちです。このドキュメントを読むために、 Python について知っておく必要はありません; インストールしたモジュールを調べるために
Python の対話モードにちょっとだけ手を出す必要がありますが、それだけです。自作の Python モジュールを他人が使える
ようにするために配布する方法を探しているのなら、 :ref:`distutils-index`
マニュアルを参照してください。


.. _inst-trivial-install:

もっとも簡単な場合: ありふれたインストール作業
----------------------------------------------

最も楽なのは、インストールしたいモジュール配布物の特殊なバージョンをインストールしたいプラットフォーム向けに誰かがすでに用意してくれていて、
他のアプリケーションと同じようにインストールするだけであるような場合です。例えば Windows ユーザ向けには実行可能形式のインストーラ、 RPM ベースの
Linux システム (Red Hat, SuSE, Mandrake その他多数)  向けには RPM パッケージ、 Debian ベースの Linux
システム向けには  Debian パッケージといった具合に、モジュール開発者はビルド済み配布物を作成しているかもしれません。

このような場合、自分のプラットフォームに合ったインストーラをダウンロードして、実行可能形式なら実行し、RPM なら ``rpm --install``
するといった、分かりきった作業をするだけです。 Python を起動したり、 setup スクリプトを実行する必要はなく、何もコンパイルする必要はありません
--- 説明書きを読む必要すら全くないかもしれません (とはいえ、説明書きを読むのはよいことですが)。

もちろん、いつもこう簡単とは限りません。自分のプラットフォーム向けのお手軽なインストーラがないモジュール配布物に興味を持つこともあるでしょう。
そんな場合には、モジュールの作者やメンテナがリリースしているソース配布物から作業をはじめねばなりません。
ソース配布物からのインストールは、モジュールが標準的な方法でパッケージ化されている限りさほど大変ではありません。このドキュメントの大部分は、
標準的なソース配布物からのビルドとインストールに関するものです。


.. _inst-new-standard:

新しい標準: Distutils
---------------------

モジュールのソースコード配布物をダウンロードしたら、配布物が標準のやり方、すなわち Distutils のやり方に従ってパッケージされて
配布されているかどうかすぐに分かります。Distutils の場合、まず配布物の名前とバージョン番号が、例えば :file:`foo-1.0.tar.gz`
や :file:`widget-0.9.7.zip` のように、ダウンロードされたアーカイブファイルの
名前にはっきりと反映されます。次に、アーカイブは同様の名前のディレクトリ、例えば :file:`foo-1.0` や :file:`widget-0.9.7`
に展開されます。さらに、配布物には setup スクリプト :file:`setup.py` が入っています。また、 :file:`README.txt`
場合によっては :file:`README` という名前のファイルも入っていて、そこには、モジュール配布物の構築とインストールは簡単で、 ::

   python setup.py install

とするだけだ、という説明が書かれているはずです。


上記の全てが当てはまるなら、ダウンロードしたものをビルドしてインストールする方法はすでに知っていることになります: 上記のコマンドを実行するだけです。
非標準の方法でインストールを行ったり、ビルドプロセスをカスタマイズ行いたいのでない限り、このマニュアルは必要ありません。
別の言葉で言えば、上のコマンドこそが、このマニュアルから習得すべき全てということになります。


.. _inst-standard-install:

標準的なビルド・インストール作業
================================

:ref:`inst-new-standard` 節で述べたよいうに、 Distutils を使ったモジュール配布物のビルドとインストールは、通常は単純なコマンド::

   python setup.py install

で行います。

Unixでは、このコマンドをシェルプロンプトで行います; Windows では、コマンドプロンプトウィンドウ ("DOS ボックス") を開いて、そこで
行います; Mac OS X の場合、 :command:`Terminal` ウィンドウを開いてシェルプロンプトを出してください。


.. _inst-platform-variations:

プラットフォームによる違い
--------------------------

setup コマンドは常に配布物ルートディレクトリ、すなわちモジュールのソース配布物を展開した際のトップレベルのサブディレクトリ内で
実行しなければなりません。例えば、あるモジュールのソース配布物 :file:`foo-1.0.tar.gz` を Unix システム上にダウンロードしたなら、
通常は以下の操作を行います::

   gunzip -c foo-1.0.tar.gz | tar xf -    # unpacks into directory foo-1.0
   cd foo-1.0
   python setup.py install

Windows では、おそらく :file:`foo-1.0.zip` をダウンロードしているでしょう。アーカイブファイルを :file:`C:\\Temp`
にダウンロードしたのなら、(WinZip のような) グラフィカルユーザインタフェースつきのアーカイブ操作ソフトや、 (:program:`unzip` や
:program:`pkunzip` のような) コマンドラインツールを使ってアーカイブを展開します。次に、コマンドプロンプトウィンドウ ("DOS
ボックス") を開いて、以下を実行します:

.. %

::

   cd c:\Temp\foo-1.0
   python setup.py install


.. _inst-splitting-up:

ビルド作業とインストール作業を分割する
--------------------------------------

``setup.py install`` を実行すると、一度の実行で全てのモジュールをビルドしてインストールします。段階的に作業をしたい場合 --- ビルド
プロセスをカスタマイズしたり、作業がうまくいかない場合に特に便利です --- には、setup スクリプトに一度に一つづつ作業を行わせるよう
にできます。この機能は、ビルドとインストールを異なるユーザで行う場合にも便利です --- 例えば、モジュール配布物をビルドしておいてシステム管理者に渡して
(または、自分でスーパユーザになって) 、インストールしたくなるかもしれません.

最初のステップでは全てをビルドしておき、次のステップで全てをインストールするには、 setup スクリプトを二度起動します::

   python setup.py build
   python setup.py install

この作業を行ってみれば、 :command:`install` コマンドを実行するとまず :command:`build` コマンドを実行し、さらに  ---
この場合には ---  :file:`build` ディレクトリの中が全て最新の状態になっているので、 :command:`build`
は何も行わなくてよいと判断していることがわかるでしょう。


インターネットからダウンロードしたモジュールをインストールしたいだけなら、上のように作業を分割する機能は必要ないかもしれませんが、
この機能はより進んだ使い方をする際にはとても便利です。自作の Python モジュールや拡張モジュールを配布することになれば、個々の Distutils
コマンドを自分で何度も実行することになるでしょう。


.. _inst-how-build-works:

ビルドの仕組み
--------------

上で示唆したように、 :command:`build` コマンドは、インストールすべきファイルを *ビルドディレクトリ (build directory)*
に置く働きがあります。デフォルトでは、ビルドディレクトリは配布物ルート下の  :file:`build` になります;
システムの処理速度に強いこだわりがあったり、ソースツリーに指一本触れたくないのなら、 :option:`--build-base`
オプションを使ってビルドディレクトリを変更できます。例えば::

   python setup.py build --build-base=/tmp/pybuild/foo-1.0

(あるいは、システム全体向け、あるいは個人用の Distutils 設定ファイルにディレクティブを書いて、永続的に設定を変えられます;
:ref:`inst-config-files` 節を参照してください。)  通常は必要ない作業です。

ビルドツリーのデフォルトのレイアウトは以下のようになっています::

   --- build/ --- lib/
   または
   --- build/ --- lib.<plat>/
                  temp.<plat>/

``<plat>`` は、現在の OS/ハードウェアプラットフォームと Python のバージョンを記述する短い文字列に展開されます。第一の
:file:`lib` ディレクトリだけの形式は、 "pure モジュール配布物" --- すなわち、pure Python
モジュールだけの入ったモジュール配布物 --- の場合に使われます。モジュール配布物に何らかの拡張モジュール (C/C++ で書かれたモジュール)
が入っている場合、第二の ``<plat>`` 付きディレクトリが二つある形式が使われます。この場合、  :file:`temp.{plat}`
ディレクトリには、コンパイル/リンク過程で生成され、実際にはインストールされない一時ファイルが収められます。どちらの場合にも、 :file:`lib`
(または :file:`lib.{plat}`)  ディレクトリには、最終的にインストールされることになる全ての Python  モジュール (pure
Python モジュールおよび拡張モジュール) が入ります。


今後、 Python スクリプト、ドキュメント、バイナリ実行可能形式、その他 Python モジュールやアプリケーションのインストール作業に
必要なディレクトリが追加されるかもしれません。


.. _inst-how-install-works:

インストールの仕組み
--------------------

:command:`build` コマンドを実行した後 (明示的に実行した場合も、 :command:`install`
コマンドが代わりに実行してくれた場合も) は、 :command:`install` コマンドの仕事は比較的単純なもの: :file:`build/lib`
(または :file:`build/lib.{plat}`) の下にあるもの全ての指定したインストールディレクトリへのコピー、になります。

インストールディレクトリを選ばなかった場合 --- すなわち、 ``setup.py install`` を実行しただけの場合 ---
には、 :command:`install` コマンドはサードパーティ製 Python モジュールを置くための標準の場所に
インストールを行います。この場所は、プラットフォームや、Python 自体をどのようにビルド/インストールしたかで変わります。 Unix (と、Unix
をベースとしたMac OS X) では、インストールしようとするモジュール配布物が pure Python なのか、拡張モジュールを含む ("非 pure")
のかによっても異なります:

+------------------+-------------------------------------------------------+--------------------------------------------------+-------+
| プラットフォーム | 標準のインストール場所                                | デフォルト値                                     | 注記  |
+==================+=======================================================+==================================================+=======+
| Unix (pure)      | :file:`{prefix}/lib/python{X.Y}/site-packages`        | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1)  |
+------------------+-------------------------------------------------------+--------------------------------------------------+-------+
| Unix (non-pure)  | :file:`{exec-prefix}/lib/python{X.Y}/site-packages`   | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1)  |
+------------------+-------------------------------------------------------+--------------------------------------------------+-------+
| Windows          | :file:`{prefix}`                                      | :file:`C:\\Python`                               | \(2)  |
+------------------+-------------------------------------------------------+--------------------------------------------------+-------+

注記:

(1)
   ほとんどの Linux ディストリビューションには、システムの標準インストール物として Python が入っているので、 Linux では普通、
   :file:`{prefix}` や :file:`{exec-prefix}` はどちらも :file:`/usr`  になります。 Linux (または
   Unixライクなシステム) 上で自分で Python  をビルドした場合、デフォルトの :file:`{prefix}` および
   :file:`{exec-prefix}` は :file:`/usr/local` になります。

(2)
   Windows での Python のデフォルトインストールディレクトリは、 Python 1.6a1、 1.5.2、およびそれ以前のバージョンでは
   :file:`C:\\Program Files\\Python` です。

:file:`{prefix}` および :file:`{exec-prefix}` は、 Python がインストール
されているディレクトリと、実行時にライブラリを探しにいく場所を表します。これらのディレクトリは、Windows では常に同じで、 Unixと Mac OS X
でもほぼ常に同じです。自分の Python がどんな :file:`{prefix}` や :file:`{exec-prefix}`
を使っているかは、Python を対話モードで起動して、単純なコマンドをいくつか入力すればわかります。 Windows
では、:menuselection:`スタート --> (すべての) プログラム -->  Python X.Y --> Python
(command line)` を選びます。 Mac OS 9 では、 :file:`PythonInterpreter` を起動します。
インタプリタを起動すると、プロンプトに Python コードを入力できます。例えば、作者の使っている Linux システムで、三つの Python
文を以下のように入力すると、出力から作者のシステムの :file:`{prefix}` と :file:`{exec-prefix}` を得られます::

   Python 2.4 (#26, Aug  7 2004, 17:19:02)
   Type "help", "copyright", "credits" or "license" for more information.
   >>> import sys
   >>> sys.prefix
   '/usr'
   >>> sys.exec_prefix
   '/usr'

モジュールを標準の場所にインストールしたくない場合や、標準の場所にインストールするためのファイル権限を持っていない場合、
:ref:`inst-alt-install` 節にある、別の場所へのインストール方法の説明を読んでください。
インストール先のディレクトリを大幅にカスタマイズしければ、
:ref:`inst-custom-install` 節のカスタムインストールに関する説明を読んでください。


.. _inst-alt-install:

別の場所へのインストール
========================

しばしば、サードパーティ製 Python モジュールをインストールするための標準の場所以外にモジュールをインストールしなければならなかったり、
単にそうしたくなるときがあります。例えばUnix システムでは、標準のサードパーティ製モジュールディレクトリに対する書き込み権限を持っていないかも
しれません。または、あるモジュールを、ローカルで使っている Python に標準のモジュールの一部として組み込む前にテストしてみたいと思う
かもしれません。既存の配布物をアップグレードする際には特にそうでしょう: 実際にアップグレードする前に、既存のスクリプトの基本となる部分が
新たなバージョンでも動作するか確認したいはずです。

Distutils の :command:`install` コマンドは、別の場所へ配布物をインストール
する作業を単純で苦労のない作業にするように設計されています。基本的なアイデアは、インストール先のベースディレクトリを指定しておき、
:command:`install` コマンドがそのベースディレクトリ下にファイル群をインストールするための一連のディレクトリ (*インストールスキーム :
installation scheme*) を作成するというものです。詳細はプラットフォームによって異なるので、以下の節から自分の
プラットフォームに当てはまるものを読んでください。


.. _inst-alt-install-prefix:

別の場所へのインストール: home スキーム
---------------------------------------

"home スキーム" の背後にある考え方は、Python モジュールを個人用のモジュール置き場でビルドし、維持するというものです。このスキームの名前は
Unixの「ホーム」ディレクトリの概念からとりました。というのも、 Unixのユーザにとって、自分のホームディレクトリを :file:`/usr/` や
:file:`/usr/local/` のようにレイアウトするのはよくあることだからです。とはいえ、このスキームはどの
オペレーティングシステムのユーザでも使えます。新たなモジュールのインストールは単純で、 ::

   python setup.py install --home=<dir>

のようにします。このとき、 :option:`--home` オプションを使ってディレクトリを指定します。面倒臭がりの人は、単にチルダ (``~``)
をタイプするだけでかまいません;  :command:`install` コマンドがチルダをホームディレクトリに展開してくれます。

::

   python setup.py install --home=~

:option:`--home` オプションは、インストールのベースディレクトリを指定します。ファイルはインストールベース下の以下のディレクトリに
保存されます:

+------------------------------+---------------------------+-----------------------------+
| Type of file                 | Installation Directory    | Override option             |
+==============================+===========================+=============================+
| pure module distribution     | :file:`{home}/lib/python` | :option:`--install-purelib` |
+------------------------------+---------------------------+-----------------------------+
| non-pure module distribution | :file:`{home}/lib/python` | :option:`--install-platlib` |
+------------------------------+---------------------------+-----------------------------+
| scripts                      | :file:`{home}/bin`        | :option:`--install-scripts` |
+------------------------------+---------------------------+-----------------------------+
| data                         | :file:`{home}/share`      | :option:`--install-data`    |
+------------------------------+---------------------------+-----------------------------+


.. versionchanged:: 2.4
   :option:`--home` は Unixでしかサポートされていませんでした.


.. _inst-alt-install-home:

別の場所へのインストール: Unix (prefix スキーム)
------------------------------------------------

あるインストール済みの Python を使ってモジュールのビルド/インストールを (例えば setup スクリプトを実行して) 行いたいけれども、
別のインストール済みの Python のサードパーティ製モジュール置き場 (あるいは、そう見えるようなディレクトリ構造) に、ビルドされた
モジュールをインストールしたい場合には、"prefix スキーム" が便利です。そんな作業はまったくありえそうにない、と思うなら、確かにその通りです ---
"home スキーム" を先に説明したのもそのためです。とはいえ、prefix スキームが有用なケースは少なくとも二つあります。

まず、多くの Linux ディストリビューションは、 Python を :file:`/usr/local` ではなく :file:`/usr`
に置いていることを考えてください。この場合は、 Python はローカルの計算機ごとのアドオン (add-on) ではなく、"システム"
の一部となっているので、 :file:`/usr` に置くのは全く正当なことです。しかしながら、 Python モジュールをソースコードからインストール
していると、モジュールを :file:`/usr/lib/python2.{X}` ではなく
:file:`/usr/local/lib/python2.{X}` に置きたいと思うかもしれません。これを行うには ::

   /usr/bin/python setup.py install --prefix=/usr/local

と指定します。

.. %

もう一つありえるのは、ネットワークファイルシステムにおいて、遠隔のディレクトリに対する読み出しと書き込みの際に違う名前を使う場合です。例えば、
:file:`/usr/local/bin/python` でアクセスするような Python  インタプリタは、
:file:`/usr/local/lib/python2.{X}` からモジュールを探すでしょうが、モジュールは別の場所、例えば
:file:`/mnt/{@server}/export/lib/python2.{X}` にインストールしなければならないかもしれません。この場合には、
::

   /usr/local/bin/python setup.py install --prefix=/mnt/@server/export

のようにします。

.. %

どちらの場合も、 :option:`--prefix` オプションでインストールベースディレクトリを決め、 :option:`--exec-prefix` で
プラットフォーム固有のファイル置き場名として使う、プラットフォーム固有インストールベースディレクトリを決めます。
(プラットフォーム固有のファイルとは、現状では単に非 pure モジュール配布物のことを意味しますが、 C ライブラリやバイナリ実行可能形式など
に拡張されるかもしれません。) :option:`--exec-prefix`  が指定されていなければ、デフォルトの :option:`--prefix`
になります。ファイルは以下のようにインストールされます:

+------------------------------+-----------------------------------------------------+-----------------------------+
| Type of file                 | Installation Directory                              | Override option             |
+==============================+=====================================================+=============================+
| pure module distribution     | :file:`{prefix}/lib/python{X.Y}/site-packages`      | :option:`--install-purelib` |
+------------------------------+-----------------------------------------------------+-----------------------------+
| non-pure module distribution | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :option:`--install-platlib` |
+------------------------------+-----------------------------------------------------+-----------------------------+
| scripts                      | :file:`{prefix}/bin`                                | :option:`--install-scripts` |
+------------------------------+-----------------------------------------------------+-----------------------------+
| data                         | :file:`{prefix}/share`                              | :option:`--install-data`    |
+------------------------------+-----------------------------------------------------+-----------------------------+

:option:`--prefix` や :option:`--exec-prefix` が実際に他のインストール済み Python
の場所を指している必要はありません; 上に挙げたディレクトリがまだ存在しなければ、インストール時に作成されます。

ちなみに、prefix スキームが重要な本当の理由は、単に標準の Unix  インストールが prefix スキームを使っているからです。ただし、
そのときには、 :option:`--prefix` や :option:`--exec-prefix`  は Python 自体が
``sys.prefix `` や `` sys.exec_prefix`` を使って決めます。というわけで、読者は prefix スキームを決して使うことは
あるまいと思っているかもしれませんが、 ``python setup.py install``  をオプションを何もつけずに実行していれば、常に prefix
スキームを使っていることになるのです。

拡張モジュールを別のインストール済み Python にインストールしても、拡張モジュールのビルド方法による影響を受けることはありません:
特に、拡張モジュールをコンパイルする際には、 setup スクリプトを実行する際に使う Python インタプリタと一緒にインストールされている Python
ヘッダファイル (:file:`Python.h`  とその仲間たち) を使います。上で述べてきたやり方でインストールされた拡張モジュールを実行する
インタプリタと、インタプリタをビルドする際に用いた別のインタプリタとの互換性を保証するのはユーザの責任です。

これを行うには、二つのインタプリタが同じバージョンの Python  (ビルドが違っていたり、同じビルドのコピーということもあり得ます) であるかどうかを
確かめます。(もちろん、 :option:`--prefix` や  :option:`--exec-prefix` が別のインストール済み Python
の場所すら指していなければどうにもなりません。)


.. _inst-alt-install-windows:

別の場所へのインストール (prefix を使う方法): Windows
-----------------------------------------------------

Windows はユーザのホームディレクトリという概念がなく、 Windows 環境下で標準的にインストールされた Python は Unixよりも
単純な構成をしているので、 Windows で追加のパッケージを別の場所に入れる場合には、伝統的に :option:`--prefix` が使われてきました。
::

   python setup.py install --prefix="\Temp\Python"

とすると、モジュールを現在のドライブの :file:`\\Temp\\Python` ディレクトリにインストールします

.. %

インストールベースディレクトリは、 :option:`--prefix` オプションだけで決まります; :option:`--exec-prefix`
オプションは、Windows ではサポートされていません。ファイルは以下のような構成でインストールされます:

+------------------------------+---------------------------+-----------------------------+
| Type of file                 | Installation Directory    | Override option             |
+==============================+===========================+=============================+
| pure module distribution     | :file:`{prefix}`          | :option:`--install-purelib` |
+------------------------------+---------------------------+-----------------------------+
| non-pure module distribution | :file:`{prefix}`          | :option:`--install-platlib` |
+------------------------------+---------------------------+-----------------------------+
| scripts                      | :file:`{prefix}\\Scripts` | :option:`--install-scripts` |
+------------------------------+---------------------------+-----------------------------+
| data                         | :file:`{prefix}\\Data`    | :option:`--install-data`    |
+------------------------------+---------------------------+-----------------------------+


.. _inst-custom-install:

カスタムのインストール
======================

たまに、 :ref:`inst-alt-install` 節で述べたような別の場所へのインストールスキームが、自分のやりたいインストール方法と違うことがあります。
もしかすると、同じベースディレクトリ下にあるディレクトリのうち、一つか二つだけをいじりたかったり、インストールスキームを完全に
再定義したいと思うかもしれません。どちらの場合にせよ、こうした操作では *カスタムのインストールスキーム* を作成することになります。

別の場所へのインストールスキームに関するこれまでの説明で、 "オーバライドするためのオプション" というコラムにお気づきかも
しれません。このオプションは、カスタムのインストールスキームを定義するための手段です。各オーバライドオプションには、
相対パスを指定しても、絶対パスを指定しても、インストールベースディレクトリのいずれかを明示的に指定してもかまいません。
(インストールベースディレクトリは二種類あり、それら二つは通常は同じディレクトリです --- Unix の "prefix スキーム" を使っていて、
:option:`--prefix` と :option:`--exec-prefix` オプションを使っているときだけ異なります。)

例えば、 Unix環境でモジュール配布物をホームディレクトリにインストールしたい --- とはいえ、スクリプトは :file:`~/bin` ではなく
:file:`~/scripts` に置きたい --- とします。ご想像の通り、スクリプトを置くディレクトリは、
:option:`--install-scripts` オプションで上書きできます; この場合は相対パスで指定もでき、インストールベースディレクトリ
(この場合にはホームディレクトリ) からの相対パスとして解釈されます::

   python setup.py install --home=~ --install-scripts=scripts

Unix 環境での例をもう一つ紹介します: インストール済みの Python が、 :file:`/usr/local/python` を prefix
にしてビルドされ、インストールされていて、標準のインストールスクリプトは :file:`/usr/local/python/bin`
に入るようになっているとします。 :file:`/usr/local/bin` に入るようにしたければ、絶対パスを
:option:`--install-scripts` オプションに与えて上書きすることになるでしょう:

.. %

::

   python setup.py install --install-scripts=/usr/local/bin

(この操作を行うと、 "prefix スキーム" を使ったインストールになり、 prefix は Python インタプリタがインストールされている場所
--- この場合には :file:`/usr/local/python` になります。)

.. %

Windows 用の Python を管理しているのなら、サードパーティ製モジュールを :file:`{prefix}` そのものの下ではなく、
:file:`{prefix}` の下にあるサブディレクトリに置きたいと考えるかもしれません。
この作業は、インストールディレクトリのカスタマイズとほぼ同じくらい簡単です --- 覚えておかねばならないのは、モジュールには二つのタイプ、 pure
モジュールと非 pure モジュール (非 pure モジュール配布物内のモジュール) があるということです。例えば以下のようにします::

   python setup.py install --install-purelib=Site --install-platlib=Site

指定したインストール先ディレクトリは、 :file:`{prefix}` からの相対です。もちろん、 :file:`{prefix}` を
:file:`.pth` ファイルに入れるなどして、これらのディレクトリが Python のモジュール検索パス内に入るようにしなければなりません。
Python のモジュール検索パスを修正する方法は、  :ref:`inst-search-path` 節を参照してください。

インストールスキーム全体を定義したいのなら、全てのインストールディレクトリオプションを指定しなければなりません。この作業には、
相対パスを使った指定を勧めます; 例えば、全ての Python モジュール関連ファイルをホームディレクトリ下の :file:`python` ディレクトリの
下に置き、そのホームディレクトリをマウントしている各プラットフォームごとに別のディレクトリを置きたければ、以下のようにインストールスキームを定義します::

   python setup.py install --home=~ \
                           --install-purelib=python/lib \
                           --install-platlib=python/lib.$PLAT \
                           --install-scripts=python/scripts
                           --install-data=python/data

また、以下のようにも指定できます:

::

   python setup.py install --home=~/python \
                           --install-purelib=lib \
                           --install-platlib='lib.$PLAT' \
                           --install-scripts=scripts
                           --install-data=data

``$PLAT`` は、(必ずしも) 環境変数ではありません ---  この表記は、 Distutils がコマンドラインオプションの解釈と同じやり方
で展開します。設定ファイルを解釈する際と同じです。

言うまでもないことですが、毎回新たなモジュール配布物をインストールする度にインストールスキーム全体の指定を行っていては面倒です。そこで、オプションは
Distutils 設定ファイル (:ref:`inst-config-files` 参照) にも指定できます::

   [install]
   install-base=$HOME
   install-purelib=python/lib
   install-platlib=python/lib.$PLAT
   install-scripts=python/scripts
   install-data=python/data

あるいは、以下のようにも指定できます:

::

   [install]
   install-base=$HOME/python
   install-purelib=lib
   install-platlib=lib.$PLAT
   install-scripts=scripts
   install-data=data

これら二つは、 setup スクリプトを異なるインストールベースディレクトリから実行した場合には同じには *ならない* ので注意してください。例えば、

::

   python setup.py install --install-base=/tmp

とすると、最初の書き方では pure モジュールが :file:`{/tmp/python/lib}`  に入り、二番目の書き方では
:file:`{/tmp/lib}` に入ります。(二番目のケースでは、インストールベースを :file:`/tmp/python` に指定しようと
考えるでしょう。)


読者は、設定ファイル例で、入力値に ``$HOME`` や ``$PLAT`` を使っていることに気づいているかもしれませんね。これらは Distutils
の設定変数で、環境変数を彷彿とさせます。実際、この表記が使えるプラットフォーム上では、設定ファイル中に環境変数を入れられますが、 Distutils
は他にも、例えば ``$PLAT`` のようにおそらくユーザの環境中にないような変数をいくつか持っています。(そしてもちろん、 Mac OS 9
のような環境変数のないシステムでは、設定ファイル中で使える変数は Distutils が提供しているものだけです。)
詳細は :ref:`inst-config-files` を参照してください。


.. _inst-search-path:

Python サーチパスの変更
-----------------------

Python インタプリタが :keyword:`import` 文を実行するとき、インタプリタは Python コードや拡張モジュールをモジュール検索パス
中から探します。検索パスのデフォルト値は、インタプリタをビルドする際に Python のバイナリ内に設定されます。検索パスは、 :mod:`sys` を
import して、 ``sys.path`` を出力すればわかります。 ::

   $ python
   Python 2.2 (#11, Oct  3 2002, 13:31:27)
   [GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
   Type "help", "copyright", "credits" or "license" for more information.
   >>> import sys
   >>> sys.path
   ['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
    '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
    '/usr/local/lib/python2.3/site-packages']
   >>>

``sys.path`` 内の空文字列は、現在の作業ディレクトリを表します。

ローカルでインストールされるパッケージは、 :file:`{...}/site-packages/`
ディレクトリに入るのが決まりですが、ユーザはどこか任意のディレクトリに Python モジュールをインストールしたいと思うかもしれません。
例えば、自分のサイトでは、 web サーバに関連する全てのソフトウェアを :file:`/www` に置くという決まりがあるかもしれません。そこで、
アドオンの Python モジュールが :file:`/www/python` 置かれることになると、モジュールを import するためにはディレクトリを
``sys.path`` に追加せねばなりません。ディレクトリを検索パスに追加するには、いくつかの異なる方法が存在します。

最も手軽な方法は、パス設定ファイルをすでに Python の検索パスに含まれるディレクトリ、通常は :file:`.../site-packages/`
ディレクトリに置くというものです。パス設定ファイルは拡張子が :file:`.pth` で、ファイルには ``sys.path``
に追加するパスを一行に一つづつ記述しなければなりません。 (新たなパスは今の ``sys.path`` の後ろに追加されるので、追加された
ディレクトリ内にあるモジュールが標準のモジュールセットを上書きすることはありません。つまり、このメカニズムを使って、標準モジュール
に対する修正版のインストールはできないということです。)

パスは絶対パスでも相対パスでもよく、相対パスの場合には :file:`.pth` ファイルのあるパスからの相対になります。
詳しくは :mod:`site` モジュールを参照してください。

やや便利さには欠けますが、Python の標準ライブラリ中にある  :file:`site.py` ファイルを編集することでも、 ``sys.path`` を変更
できます。 :file:`site.py` は、 :option:`-S` スイッチを与えて抑制しないかぎり、Python インタプリタが実行される際に自動的に
import  されます。ただし、設定するには、単に :file:`site.py` を編集して、例えば以下のような二行を加えます::

   import sys
   sys.path.append('/www/python/')

しかしながら、(例えば 2.2 から 2.2.2 にアップグレードするときのように) 同じメジャーバージョンの Python を再インストールすると、
:file:`site.py` は手持ちのバージョンで上書きされてしまいます。ファイルが変更されていることを覚えておき、インストールを行う前に
コピーを忘れずとっておかねばなりません。

また、 ``sys.path`` を修正できる二つの環境変数があります。 :envvar:`PYTHONHOME` を使うと、インストールされている Python
のプレフィクスを別の値に設定できます。例えば、 :envvar:`PYTHONHOME` を ``/www/python`` に設定すると、検索パスは
``['', '/www/python/lib/pythonX.Y/', '/www/python/lib/pythonX.Y/plat-linux2', ...]`` といった具合になります。

:envvar:`PYTHONPATH` を使うと、 ``sys.path`` の先頭に一連の
パスを追加できます。例えば、 :envvar:`PYTHONPATH` を ``/www/python:/opt/py`` に設定すると、検索パスは
``['/www/python', '/opt/py']`` から始まります。  (`` sys.path`` にディレクトリを追加するには、そのディレクトリが
実在しなければなりません; :mod:`site` は実在しないディレクトリを除去します。)

最後に、 ``sys.path`` はただの普通の Python のリストなので、どんな Python アプリケーションもエントリを追加したり除去したりと
いった修正を行えます。


.. _inst-config-files:

Distutils 設定ファイル
======================

上で述べたように、 Distutils 設定ファイルを使えば、任意の  Distutils オプションに対して個人的な設定やサイト全体の設定を
記録できます。すなわち、任意のコマンドの任意のオプションを二つか三つ (プラットフォームによって異なります) の
設定ファイルに保存でき、コマンドラインを解釈する前にオプションを問い合わせさせるようにできます。
つまり、設定ファイルはデフォルトの値を上書きし、さらにコマンドライン上で与えた値が設定ファイルの内容を上書きするわけです。
さらに、複数の設定ファイルが適用されると、"先に" 適用されたファイルに指定されていた値は "後に" 適用されたファイル内の値で上書きされます。


.. _inst-config-filenames:

設定ファイルの場所と名前
------------------------

設定ファイルの名前と場所は、非常にわずかですがプラットフォーム間で異なります。Unix と Mac OS X では、三種類の設定ファイルは以下のようになります
(処理される順に並んでいます):

+----------------------+----------------------------------------------------------+------+
| 設定ファイルのタイプ | 場所とファイル名                                         | 注記 |
+======================+==========================================================+======+
| system               | :file:`{prefix}/lib/python{ver}/distutils/distutils.cfg` | \(1) |
+----------------------+----------------------------------------------------------+------+
| personal             | :file:`$HOME/.pydistutils.cfg`                           | \(2) |
+----------------------+----------------------------------------------------------+------+
| local                | :file:`setup.cfg`                                        | \(3) |
+----------------------+----------------------------------------------------------+------+

Windows では設定ファイルは以下のようになります:

+----------------------+-------------------------------------------------+------+
| 設定ファイルのタイプ | 場所とファイル名                                | 注記 |
+======================+=================================================+======+
| system               | :file:`{prefix}\\Lib\\distutils\\distutils.cfg` | \(4) |
+----------------------+-------------------------------------------------+------+
| personal             | :file:`%HOME%\\pydistutils.cfg`                 | \(5) |
+----------------------+-------------------------------------------------+------+
| local                | :file:`setup.cfg`                               | \(3) |
+----------------------+-------------------------------------------------+------+

注記:

(1)
   厳密に言えば、システム全体向けの設定ファイルは、 Distutils がインストールされているディレクトリになります; Unixの Python 1.6
   以降では、表の通りの場所になります。 Python 1.5.2 では、 Distutils は通常
   :file:`{prefix}/lib/python1.5/site-packages/distutils` にインストールされるため、 Python
   1.5.2 では設定ファイルをそこに置かなければなりません。

(2)
   Unixでは、環境変数 :envvar:`HOME` が定義されていない場合、標準モジュール :mod:`pwd`
   の :func:`getpwuid` 関数を使ってユーザのホームディレクトリを決定します。

(3)
   現在のディレクトリ (通常は setup スクリプトがある場所) です。

(4)
   (注記 (1) も参照してください)  Python 1.6 およびそれ以降のバージョンでは、 Python のデフォルトの "インストールプレフィクス" は
   :file:`C:\\Python` なので、システム設定ファイルは通常
   :file:`C:\\Python\\Lib\\distutils\\distutils.cfg` になります。Python 1.5.2 ではデフォルトの
   プレフィクスは :file:`C:\\Program Files\\Python` であり、Distutils は標準ライブラリの一部ではありません ---
   従って、システム設定ファイルは、 Windows 用の標準の Python 1.5.2 では :file:`C:\\Program
   Files\\Python\\distutils\\distutils.cfg` になります。

(5)
   Windows では、環境変数 :envvar:`HOME` が設定されていない場合、個人用の設定ファイルはどこにもなく、使われることもありません。
   (言い換えれば、 Windows での Distutils はホームディレクトリがどこにあるか一切推測しようとしないということです。)


.. _inst-config-syntax:

設定ファイルの構文
------------------

Distutils 設定ファイルは、全て同じ構文をしています。設定ファイルはセクションでグループ分けされています。各 Distutils
コマンドごとにセクションがあり、それに加えて全てのコマンドに影響するグローバルオプションを設定するための ``global``
セクションがあります。各セクションには ``option=value`` の形で、一行あたり一つのオプションを指定します。

例えば、以下は全てのコマンドに対してデフォルトでメッセージを出さないよう強制するための完全な設定ファイルです::

   [global]
   verbose=0

この内容のファイルがシステム全体用の設定ファイルとしてインストールされていれば、そのシステムの全てのユーザによる全ての Python モジュール
配布物に対する処理に影響します。ファイルが (個人用の設定をサポートしているシステムで) 個人用の設定ファイルとしてインストールされていれば、
そのユーザが処理するモジュール配布物にのみ影響します。この内容を特定のモジュール配布物の :file:`setup.cfg` として使えば、
その配布物だけに影響します。

.. %

以下のようにして、デフォルトの "ビルドベース" ディレクトリをオーバライドしたり、 :command:`build\*` コマンドが常に強制的にリビルドを
行うようにもできます::

   [build]
   build-base=blib
   force=1

この設定は、コマンドライン引数の

.. %

::

   python setup.py build --build-base=blib --force

に対応します。ただし、後者ではコマンドライン上で :command:`build`  コマンドを含めて、そのコマンドを実行するよう意味しているところが
違います。特定のコマンドに対するオプションを設定ファイルに含めると、このような関連付けの必要はなくなります;
あるコマンドが実行されると、そのコマンドに対するオプションが適用されます。 (また、設定ファイル内からオプションを取得するような他のコマンドを
実行した場合、それらのコマンドもまた設定ファイル内の対応するオプションの値を使います。)

.. %

あるコマンドに対するオプションの完全なリストは、例えば以下のように、 :option:`--help` を使って調べます::

   python setup.py build --help

グローバルオプションの完全なリストを得るには、コマンドを指定せずに :option:`--help` オプションを使います:

.. %

::

   python setup.py --help

"Python モジュールの配布" マニュアルの、 "リファレンスマニュアル" の節も参照してください。

.. %


.. _inst-building-ext:

拡張モジュールのビルド: 小技と豆知識
====================================

Distutils は、可能なときにはいつでも、 :file:`setup.py` スクリプトを実行する Python
インタプリタが提供する設定情報を使おうとします。例えば、拡張モジュールをコンパイルする際には、コンパイラやリンカのフラグには Python
をコンパイルした際と同じものが使われます。通常、この設定はうまくいきますが、状況が複雑になると不適切な設定になることもあります。この節では、通常の
Distutils の動作をオーバライドする方法について議論します。


.. _inst-tweak-flags:

コンパイラ/リンカのフラグをいじるには
-------------------------------------

C や C++ で書かれた Python 拡張をコンパイルする際、しばしば特定のライブラリを使ったり、特定の種類のオブジェクトコードを
生成したりする上で、コンパイラやリンカに与えるフラグをカスタマイズする必要があります。ある拡張モジュールが自分のプラットフォームでは
テストされていなかったり、クロスコンパイルを行わねばならない場合にはこれが当てはまります。

最も一般的なケースでは、拡張モジュールの作者はすでに拡張モジュールのコンパイルが複雑になることを見越していて、 :file:`Setup`
ファイルを提供して編集できるようにしています。 :file:`Setup` ファイルの編集は、モジュール配布物に多くの個別の拡張
モジュールがあったり、コンパイラに拡張モジュールをコンパイルさせるために細かくフラグをセットする必要があるような場合にのみ行うことになるでしょう。

:file:`Setup` ファイルが存在する場合、ビルドするべき拡張モジュールのリストを得るために解釈されます。 :file:`Setup`
ファイルの各行には単一のモジュールを書きます。各行は以下のような構造をとります::

   module ... [sourcefile ...] [cpparg ...] [library ...]


次に、各フィールドについて見てみましょう。

.. %

* *module* はビルドする拡張モジュールの名前で、Python の識別子名として有効でなければなりません。モジュールの名前変更は、
  このフィールドを変えるだけではできない (ソースコードの編集も必要です)  ので、このフィールドに手を加えるべきではありません。

* *sourcefile* は、少なくともファイル名から何の言語で書かれているかがわかるようになっているソースコードファイル名です。 :file:`.c`
  で終わるファイルは C で書かれているとみなされ、 :file:`.C` 、 :file:`.cc` 、および :file:`.c++` で終わるファイルは C++
  で書かれているとみなされます。 :file:`.m` や :file:`.mm` で終わるファイルは Objective C で書かれているとみなされます。

* *cpparg* は C プリプロセッサへの引数で、 :option:`-I` 、 :option:`-D` 、 :option:`-U` または
  :option:`-C` のいずれかから始まる文字列です。

* *library* は :file:`.a` で終わるか、 :option:`-l` または :option:`-L` のいずれかから始まる文字列です。

特定のプラットフォームにおいて、プラットフォーム上の特殊なライブラリが必要な場合、 :file:`Setup` ファイルを編集して ``python
setup.py build`` を実行すればライブラリを追加できます。例えば、以下の行 ::

   foo foomodule.c

で定義されたモジュールを、自分のプラットフォーム上の数学ライブラリ :file:`libm.a` とリンクしなければならない場合、 :file:`Setup`
内の行に :option:`-lm` を追加するだけです:

.. %

::

   foo foomodule.c -lm

コンパイラやリンカ向けの任意のスイッチオプションは、 :option:`-Xcompiler` *arg* や :option:`-Xlinker` *arg*
オプションで与えます:

.. %

::

   foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm

:option:`-Xcompiler` および :option:`-Xlinker` の後にくるオプションは、それぞれ適切なコマンドラインに追加されます。
従って、上の例では、コンパイラには :option:`-o32` オプションが渡され、リンカには :option:`-shared` が渡されます。
コンパイラオプションに引数が必要な場合、複数の :option:`-Xcompiler`  オプションを与えます; 例えば、 ``-x c++`` を渡すには、
:file:`Setup` ファイルには ``-Xcompiler -x -Xcompiler c++`` を渡さねばなりません。

.. %

コンパイラフラグは、環境変数 :envvar:`CFLAGS` の設定でも与えられます。 :envvar:`CFLAGS`
が設定されていれば、 :file:`Setup` ファイル内で指定されているコンパイラフラグに :envvar:`CFLAGS` の内容が追加されます。


.. _inst-non-ms-compilers:

Windows で非 Microsoft コンパイラを使ってビルドするには
-------------------------------------------------------

.. sectionauthor:: Rene Liebscher <R.Liebscher@gmx.de>



Borland/CodeGear C++
^^^^^^^^^^^^^^^^^^^^

この小節では、 Borland C++ コンパイラのバージョン 5.5 で Distutils を使うために必要な手順について述べています。  まず、
Borland のオブジェクトファイル形式 (OMF) は、Python 公式サイトや ActiveState の Web サイトからダウンロード
できるバージョンの Python が使っている形式とは違うことを知っておかねばなりません (Python は通常、 Microsoft Visual C++
でビルドされています。Microsoft Visual C++ は COFF をオブジェクトファイル形式に使います。) このため、以下のようにして、
Python のライブラリ :file:`python25.lib`  を Borland の形式に変換する必要があります:

::

   coff2omf python25.lib python25_bcpp.lib

:file:`coff2omf` プログラムは、 Borland コンパイラに付属しています。 :file:`python25.lib` は Python
インストールディレクトリの :file:`Libs`  ディレクトリ内にあります。拡張モジュールで他のライブラリ (zlib, ...)
を使っている場合、それらのライブラリも変換しなければなりません。

.. %

変換されたファイルは、通常のライブラリと同じディレクトリに置かねばなりません。

さて、 Distutils は異なる名前を持つこれらのライブラリをどのように扱うのでしょうか? 拡張モジュールで (例えば :file:`foo`
という名の) ライブラリが必要な場合、 Distutils はまず :file:`_bcpp` が後ろに付いたライブラリ (例えば
:file:`foo_bcpp.lib`) が見つかるかどうか調べ、あればそのライブラリを使います。該当するライブラリがなければ、デフォルトの名前
(:file:`foo.lib`) を使います [#]_。

Borland C++ を使って Distutils に拡張モジュールをコンパイルさせるには、以下のように入力します::

   python setup.py build --compiler=bcpp

Borland C++ コンパイラをデフォルトにしたいなら、自分用、またはシステム全体向けに、 Distutils の設定ファイルを書くことを検討した
方がよいでしょう (:ref:`inst-config-files` 節を参照してください)。


.. seealso::

   `C++Builder Compiler <http://www.codegear.com/downloads/free/cppbuilder>`_
      Borland によるフリーの C++ コンパイラに関する情報で、コンパイラのダウンロードページへのリンクもあります。

   `Creating Python Extensions Using Borland's Free Compiler <http://www.cyberus.ca/%7eg_will/pyExtenDL.shtml>`_
      Borland 製のフリーのコマンドライン C++ を使って Python をビルドする方法について述べたドキュメントです。


GNU C / Cygwin / MinGW
^^^^^^^^^^^^^^^^^^^^^^

この手引きは2.4.1 以降のPython と 3.0.0 (binutils-2.13.90-20030111-1) 以上の MinGW でのみ有効です。

この節では、 Cygwin や MinGW  [#]_ 配布物中の GNU C/C++ コンパイラで Distutils
を使うために必要な手順について述べます。 Cygwin 向けにビルドされている Python インタプリタを使っているなら、以下の手順をとらなくても
Distutils はまったく問題なく動作します。

上記のコンパイラは、いくつかの特殊なライブラリを必要とします。この作業は Borland の C++ よりもやや複雑です。というのは、
ライブラリを変換するためのプログラムが存在しないからです。  まず、 Python DLL が公開している全てのシンボルからなるリストを
作成しなければなりません。 (この作業むけの良いプログラムは、
http://www.emmestech.com/software/cygwin/pexports-0.43/download_pexports.html
から入手できます。)

::

   pexports python25.dll >python25.def

これで、上で得られた情報をもとに、 gcc 用の import ライブラリを作成できます。

.. %

インストールされた :file:`python25.dll` の位置はインストールオプションと、
Windowsのバージョンと言語に依存します。"自分だけのため"のインストールの場合には、インストールディレクトリのルートに配置されます。
共有インストールの場合にはシステムディレクトリに配置されます。 ::

   dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a

出来上がったライブラリは、 :file:`python25.lib` と同じディレクトリ (Python インストールディレクトリの :file:`libs`
ディレクトリになるはずです) に置かなければなりません。

.. %

拡張モジュールが他のライブラリ (zlib, ... ) を必要とする場合、それらのライブラリも変換しなければなりません。
変換されたファイルは、それぞれ通常のライブラリが置かれているのと同じディレクトリに置かねばなりません。

Cygwin を使って Distutils に拡張モジュールをコンパイルさせるには、 ::

   python setup.py build --compiler=cygwin

のように入力します。また、非 cygwin モードの Cygwin  [#]_ や MinGW では、

.. %

::

   python setup.py build --compiler=mingw32

のように入力します。

.. %

上記のオプションやコンパイラをデフォルトにしたいなら、自分用、またはシステム全体向けに、 Distutils の設定ファイルを書くことを検討した
方がよいでしょう ( :ref:`inst-config-files` 節を参照してください)。


.. seealso::

   `Building Python modules on MS Windows platform with MinGW <http://www.zope.org/Members/als/tips/win32_mingw_modules>`_
      MinGW 環境で必要なライブラリのビルドに関する情報があります。


.. rubric:: 脚注

.. [#] つまり、全ての既存の COFF ライブラリを同名の OMF ライブラリに置き換えてもかまわないということです

.. [#] 詳しくは http://sources.redhat.com/cygwin/ や http://www.mingw.org/ を参照してください

.. [#] このモードでは POSIX エミュレーションを利用できませんが、 :file:`cygwin1.dll` も必要なくなります。


日本語訳について
================

.. toctree::
   :maxdepth: 2

   jptranslation.rst

