Python モジュールのインストール (旧版)
**************************************

著者:
   Greg Ward --- 日本語訳: Python ドキュメント翻訳プロジェクト

注釈:

  "distutils" パッケージ全体の使用は非推奨 (deprecated) であり、Python
  3.12 で削除されます。この文書は参照のために維持されており、パッケー
  ジとともに削除されます。詳しくは What's New エントリを参照してくださ
  い。

参考:

  Python モジュールのインストール
     Python モジュールのインストールに関するドキュメントの最新版です。
     通常の Python の利用の場合、このページよりも、ほぼ確実にこちらの
     ドキュメントを参照したほうがよいでしょう。

注釈:

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

注釈:

  このガイドは、Python のバージョンの一部として提供される拡張のビルド
  と配布についての基礎的なツールについてのみをカバーします。サードパー
  ティによるツールが、容易に使えてもっと安全な代替として使えるでしょう
  。もっと詳しい情報は quick recommendations section にある Python パ
  ッケージングユーザガイドから得られます。


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

Python 2.0 において、 "distutils" API は初めて標準ライブラリに追加され
ました。このモジュールは、Linux ディストリビューションのメンテナンス担
当者には Python プロジェクトを Linux ディストリビューションに変換する
標準的な方法を提供しました。また、システム管理者には Python プロジェク
トを対象のシステムにインストールする標準的な方法を提供しました。

Python 2.0 がリリースされてから何年もたち、ビルドシステムとパッケージ
のインストーラーを Python ランタイムのリリースサイクルと強く結合させる
ことには問題があることがわかってきました。そして現在、プロジェクトは
"distutils" を直接使うよりも "pip" パッケージインストーラーと
"setuptools" ビルドシステムを使うことが推奨されています。

詳しくは Python モジュールのインストール と Python モジュールの配布 を
参照してください。

このレガシードキュメントは、 "setuptools" のドキュメントが必要な全ての
情報を網羅していると自信を持って言えるようになるまで保持されます。


Distutils にもとづくソースコードの配布
--------------------------------------

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

   python setup.py install

Windows ではこのコマンドは、コマンドプロンプトのウィンドウを開いて (ス
タート ‣ アクセサリ)、このように実行するのに違いありません

   setup.py install

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


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

Distutils にもとづくソースコードの配布 節で述べたように、 Distutils を
使ったモジュール配布物のビルドとインストールは、通常は端末からの単純な
以下コマンドで行います:

   python setup.py install


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

setup コマンドは常に配布物ルートディレクトリ、すなわちモジュールのソー
ス配布物を展開した際のトップレベルのサブディレクトリ内で実行しなければ
なりません。例えば、あるモジュールのソース配布物 "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 では、おそらく "foo-1.0.zip" をダウンロードしているでしょう。
アーカイブファイルを "C:\Temp" にダウンロードしたのなら、(WinZip のよ
うな) グラフィカルユーザインターフェースつきのアーカイブ操作ソフトや、
(**unzip** や **pkunzip** のような) コマンドラインツールを使ってアーカ
イブを "C:\Temp\foo-1.0" に展開します。次に、コマンドプロンプトウィン
ドウを開いて、以下を実行します:

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


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

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

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

   python setup.py build
   python setup.py install

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

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


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

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

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

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

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

   --- build/ --- lib/
   or
   --- build/ --- lib.<plat>/
                  temp.<plat>/

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

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


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

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

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

+-------------------+-------------------------------------------------------+----------------------------------------------------+---------+
| プラットフォーム  | 標準のインストール場所                                | デフォルト値                                       | 注釈    |
|===================|=======================================================|====================================================|=========|
| Unix (pure)       | "*prefix*/lib/python*X.Y*/site-packages"              | "/usr/local/lib/python*X.Y*/site-packages"         | (1)     |
+-------------------+-------------------------------------------------------+----------------------------------------------------+---------+
| Unix (非 pure)    | "*exec-prefix*/lib/python*X.Y*/site-packages"         | "/usr/local/lib/python*X.Y*/site-packages"         | (1)     |
+-------------------+-------------------------------------------------------+----------------------------------------------------+---------+
| Windows           | "*prefix*\Lib\site-packages"                          | "C:\Python*XY*\Lib\site-packages"                  | (2)     |
+-------------------+-------------------------------------------------------+----------------------------------------------------+---------+

注釈:

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

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

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

このドキュメントではほかにちょっとだけプレースホルダを使います:
"*X.Y*" は Python のバージョンを表し、例えば "3.2" です; "*abiflags*"
は "sys.abiflags" の値に置き換えられるか、プラットフォームが ABI フラ
グを定義しない場合、空文字列に置き換えられます; "*distname*" はインス
トールしようとしているモジュール配布物の名前に置き換えられます。ドット
とキャピタライズはパス内で重要です; 例えば UNIX では "python3.2" が使
われる値が、Windows では普通 "Python32" を使います。

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


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

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

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

色々な代替インストールスキームは相互に排他的であることに注意してくださ
い: "--user", または "--home", または "--prefix" と "--exec-prefix",
または "--install-base" と "--install-platbase" を指定できますが、それ
らグループを混ぜこぜには使えません。


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

このスキームはグローバルな site-packages ディレクトリへの書き込み権限
を持たないユーザあるいはそこにインストールしたくないユーザに最も便利な
解法となるようデザインされています。簡単なオプションでこれが可能です:

   python setup.py install --user

Files will be installed into subdirectories of "site.USER_BASE"
(written as "*userbase*" hereafter).  This scheme installs pure Python
modules and extension modules in the same location (also known as
"site.USER_SITE"). Here are the values for UNIX, including macOS:

+-----------------+-------------------------------------------------------------+
| ファイルのタイ  | インストールディレクトリ                                    |
| プ              |                                                             |
|=================|=============================================================|
| モジュール      | "*userbase*/lib/python*X.Y*/site-packages"                  |
+-----------------+-------------------------------------------------------------+
| スクリプト      | "*userbase*/bin"                                            |
+-----------------+-------------------------------------------------------------+
| データ          | "*userbase*"                                                |
+-----------------+-------------------------------------------------------------+
| C ヘッダー      | "*userbase*/include/python*X.Y**abiflags*/*distname*"       |
+-----------------+-------------------------------------------------------------+

Windows の場合は以下の通り:

+-----------------+-------------------------------------------------------------+
| ファイルのタイ  | インストールディレクトリ                                    |
| プ              |                                                             |
|=================|=============================================================|
| モジュール      | "*userbase*\Python*XY*\site-packages"                       |
+-----------------+-------------------------------------------------------------+
| スクリプト      | "*userbase*\Python*XY*\Scripts"                             |
+-----------------+-------------------------------------------------------------+
| データ          | "*userbase*"                                                |
+-----------------+-------------------------------------------------------------+
| C ヘッダー      | "*userbase*\Python*XY*\Include{distname}"                   |
+-----------------+-------------------------------------------------------------+

このスキームが前述してきたほかのものと比較して有利なのは、ユーザの
site-packages ディレクトリが常に "sys.path" に含まれる普通の状態にある
(詳細は "site" 参照)ということで、つまり "setup.py" スクリプト後にイン
ストールを完成させるための特別なステップが不要ということです。

さらに、コンパイラがヘッダファイルを検索するための
"*userbase*/include" 、ライブラリを検索するための "*userbase*/lib" 、
ランタイムの共有ライブラリを探すためのパス(rpath)を追加するために、
**build_ext** コマンドには "--user" オプションがあります。


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

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

新たなモジュールのインストールは単純で

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

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

   python setup.py install --home=~

To make Python find the distributions installed with this scheme, you
may have to modify Python's search path or edit "sitecustomize" (see
"site") to call "site.addsitedir()" or edit "sys.path".

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

+-----------------+-------------------------------------------------------------+
| ファイルのタイ  | インストールディレクトリ                                    |
| プ              |                                                             |
|=================|=============================================================|
| モジュール      | "*home*/lib/python"                                         |
+-----------------+-------------------------------------------------------------+
| スクリプト      | "*home*/bin"                                                |
+-----------------+-------------------------------------------------------------+
| データ          | "*home*"                                                    |
+-----------------+-------------------------------------------------------------+
| C ヘッダー      | "*home*/include/python/*distname*"                          |
+-----------------+-------------------------------------------------------------+

(Windows の場合はスラッシュをバックスラッシュに脳内変換)


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

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

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

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

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

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

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

+-------------------+------------------------------------------------------------+
| ファイルのタイプ  | インストールディレクトリ                                   |
|===================|============================================================|
| pure Python モジ  | "*prefix*/lib/python*X.Y*/site-packages"                   |
| ュール            |                                                            |
+-------------------+------------------------------------------------------------+
| 拡張モジュール    | "*exec-prefix*/lib/python*X.Y*/site-packages"              |
+-------------------+------------------------------------------------------------+
| スクリプト        | "*prefix*/bin"                                             |
+-------------------+------------------------------------------------------------+
| データ            | "*prefix*"                                                 |
+-------------------+------------------------------------------------------------+
| C ヘッダー        | "*prefix*/include/python*X.Y**abiflags*/*distname*"        |
+-------------------+------------------------------------------------------------+

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

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

拡張モジュールを別のインストール済み Python にインストールしても、拡張
モジュールのビルド方法による影響を受けることはありません: 特に、拡張モ
ジュールをコンパイルする際には、 setup スクリプトを実行する際に使う
Python インタプリタと一緒にインストールされている Python ヘッダファイ
ル ("Python.h"  とその仲間たち) を使います。上で述べてきたやり方でイン
ストールされた拡張モジュールを実行するインタプリタと、インタプリタをビ
ルドする際に用いた別のインタプリタとの互換性を保証するのはユーザの責任
です。これを行うには、二つのインタプリタが同じバージョンの Python  (ビ
ルドが違っていたり、同じビルドのコピーということもあり得ます) であるか
どうかを確かめます。(もちろん、 "--prefix" や  "--exec-prefix" が別の
インストール済み Python の場所すら指していなければどうにもなりません。
)


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

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

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

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

インストールベースディレクトリは、 "--prefix" オプションだけで決まりま
す; "--exec-prefix" オプションは、Windows ではサポートされていません。
pure モジュールと拡張モジュールは同じ場所にインストールされます。ファ
イルは以下のような構成でインストールされます:

+-----------------+------------------------------------------------------------+
| ファイルのタイ  | インストールディレクトリ                                   |
| プ              |                                                            |
|=================|============================================================|
| モジュール      | "*prefix*\Lib\site-packages"                               |
+-----------------+------------------------------------------------------------+
| スクリプト      | "*prefix*\Scripts"                                         |
+-----------------+------------------------------------------------------------+
| データ          | "*prefix*"                                                 |
+-----------------+------------------------------------------------------------+
| C ヘッダー      | "*prefix*\Include{distname}"                               |
+-----------------+------------------------------------------------------------+


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

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

カスタムインストールのためには、スキームの中のひとつから始めて、ファイ
ルのタイプごとに使われるインストールディレクトリを以下オプションで上書
きします:

+------------------------+-------------------------+
| ファイルのタイプ       | 上書きオプション        |
|========================|=========================|
| pure Python モジュール | "--install-purelib"     |
+------------------------+-------------------------+
| 拡張モジュール         | "--install-platlib"     |
+------------------------+-------------------------+
| 全てのモジュール       | "--install-lib"         |
+------------------------+-------------------------+
| スクリプト             | "--install-scripts"     |
+------------------------+-------------------------+
| データ                 | "--install-data"        |
+------------------------+-------------------------+
| C ヘッダー             | "--install-headers"     |
+------------------------+-------------------------+

これらの上書きオプションには相対パス、絶対パス、あるいはベースディレク
トリのひとつとして明確に定義されたものを指定することができます（2つの
ベースディレクトリがあり、通常それらは同一です。これらは Unix の
prefix スキームを選択し、 "--prefix" と "--exec-prefix" オプションに異
なるパスを指定した場合にだけ同一でなくなります。  "--install-lib" を指
定すると内部で設定された、あるいは指定された "--install-purelib" と "
--install-platlib" を上書きしますので、この方法が pure モジュールと拡
張モジュールのインストール先を同一とするようなスキームでは推奨されます
）。

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

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

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

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

(この例は prefix スキームによるインストールを実行します。ここで prefix
は Python インタープリタがインストールされている場所 --- この例では
"/usr/local/python" --- になります。)

Windows 上の Python を管理している場合、サードパーティ製のモジュールは
"*prefix*" 直下ではなく、 "*prefix*" 配下のサブディレクトリにインスト
ールしたいと考えるかもしれません。これはスクリプトのインストール先ディ
レクトリをカスタマイズするのとほとんど同じくらいに簡単です。 --- 覚え
ておかなければならないのは、Python には pure モジュールと拡張モジュー
ルの2種類があり、これらのインストール先はただひとつのオプションで簡単
にコントロールできる、ということだけです。

   python setup.py install --install-lib=Site

指定したインストール先ディレクトリは、 "*prefix*" からの相対です。もち
ろん、 このディレクトリを ".pth" ファイルに入れるなどして("site" 参照)
、Python のモジュール検索パス内に入るようにしなければなりません。
Python のモジュール検索パスを修正する方法は、  Python サーチパスの変更
節を参照してください。

インストールスキーム全体を定義したいのなら、全てのインストールディレク
トリオプションを指定しなければなりません。この作業には、相対パスを使っ
た指定を勧めます; 例えば、全ての Python モジュール関連ファイルをホーム
ディレクトリ下の "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 設定ファイル (Distutils 設定ファイ
ル 参照) にも指定できます:

   [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 モジュールが "/tmp/python/lib"  に入り
、二番目の書き方では "/tmp/lib" に入ります。(二番目のケースでは、イン
ストールベースを "/tmp/python" に指定しようと考えるでしょう。)

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

注釈:

  virtual environment 下にいる場合、仮想環境の外に不注意でプロジェクト
  をインストールしてしまうことを避けるために、インストールパスを変更す
  るあらゆるオプションは distutils の全ての設定ファイルによって無視さ
  れます。


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

Python インタプリタが "import" 文を実行するとき、インタプリタは Python
コードや拡張モジュールをモジュール検索パス中から探します。検索パスのデ
フォルト値は、インタプリタをビルドする際に Python のバイナリ内に設定さ
れます。検索パスは、 "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" 内の空文字列は、現在の作業ディレクトリを表します。

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

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

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

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

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

However, if you reinstall the same minor version of Python (perhaps
when upgrading from 2.2 to 2.2.2, for example) "site.py" will be
overwritten by the stock version.  You'd have to remember that it was
modified and save a copy before doing the installation.

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

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

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


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

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


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

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

+----------------+------------------------------------------------------------+---------+
| ファイルのタイ | 場所とファイル名                                           | 注釈    |
| プ             |                                                            |         |
|================|============================================================|=========|
| system         | "*prefix*/lib/python*ver*/distutils/distutils.cfg"         | (1)     |
+----------------+------------------------------------------------------------+---------+
| personal       | "$HOME/.pydistutils.cfg"                                   | (2)     |
+----------------+------------------------------------------------------------+---------+
| local          | "setup.cfg"                                                | (3)     |
+----------------+------------------------------------------------------------+---------+

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

+----------------+---------------------------------------------------+---------+
| ファイルのタイ | 場所とファイル名                                  | 注釈    |
| プ             |                                                   |         |
|================|===================================================|=========|
| system         | "*prefix*\Lib\distutils\distutils.cfg"            | (4)     |
+----------------+---------------------------------------------------+---------+
| personal       | "%HOME%\pydistutils.cfg"                          | (5)     |
+----------------+---------------------------------------------------+---------+
| local          | "setup.cfg"                                       | (3)     |
+----------------+---------------------------------------------------+---------+

全てのプラットフォームにおいて、"個人の" ファイルは "--no-user-cfg" オ
プションを使って一時的に無効にすることができます。

注釈:

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

2. On Unix, if the "HOME" environment variable is not defined, the
   user's home directory will be determined with the "getpwuid()"
   function from the standard "pwd" module. This is done by the
   "os.path.expanduser()" function used by Distutils.

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

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

5. Windows では、環境変数 "HOME" が設定されていない場合、
   "USERPROFILE" 、 "HOMEDRIVE" 、 "HOMEPATH" を順々に試します。このと
   き同時に Distutils によって "os.path.expanduser()" が実行されます。


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

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

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

   [global]
   verbose=0

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

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

   [build]
   build-base=blib
   force=1

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

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

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

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

   python setup.py build --help

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

   python setup.py --help

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


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

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


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

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

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

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

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

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

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

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

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

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

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

   foo foomodule.c

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

   foo foomodule.c -lm

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

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

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

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


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


Borland/CodeGear C++
~~~~~~~~~~~~~~~~~~~~

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

   coff2omf python25.lib python25_bcpp.lib

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

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

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

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

   python setup.py build --compiler=bcpp

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

参考:

  C++Builder Compiler
     Borland によるフリーの C++ コンパイラに関する情報で、コンパイラの
     ダウンロードページへのリンクもあります。

  Creating Python Extensions Using Borland's Free Compiler
     Borland 製のフリーのコマンドライン C++ を使って Python をビルドす
     る方法について述べたドキュメントです。


GNU C / Cygwin / MinGW
~~~~~~~~~~~~~~~~~~~~~~

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

全ての拡張ライブラリが MinGW や Cygwin でビルドできるわけではありませ
んが、多くの場合はビルドできます。ビルドできない拡張ライブラリは、大抵
C++を利用していたり Microsoft Visual Cの拡張に依存していたりします。

distutils に Cygwin を使って拡張をコンパイルさせるには次のようにタイプ
します:

   python setup.py build --compiler=cygwin

Cygwin を no-cygwin モード [3] で使うときや MinGW を使うときは次のよう
にします:

   python setup.py build --compiler=mingw32

これらのオプションやコンパイラをデフォルトにしたい場合、 Distutils の
個人用あるいはシステム全体用の設定ファイルを書くことを検討するべきです
。 (Distutils 設定ファイル を参照してください)


古いバージョンの Python と MinGW
""""""""""""""""""""""""""""""""

以下の手順は Python 2.4.1 以前と MinGW 3.0.0
(binutils-2.13.90-20030111-1) 以前を利用しているときのものです。

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

   pexports python25.dll >python25.def

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

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

   /cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a

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

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

参考:

  Building Python modules on MS Windows platform with MinGW
     MinGW 環境で必要なライブラリのビルドに関する情報があります。

-[ 脚注 ]-

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

[2] より詳細な情報については https://www.sourceware.org/cygwin/ を参照
    して下さい。

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