`setup.py` (レガシー)¶

pyproject.tomlベースのビルドが導入される前（PEP 517とPEP 518）、pipはsetuptoolsを使用して構築されたsetup.pyファイルを使用したパッケージのインストールのみをサポートしていました。

ここに文書化されているインターフェースは、pyproject.tomlベースのビルドへの移行が完了するまで、現在、レガシー目的でのみ保持されています。

注意

pipによって作成されたsetup.pyのさまざまな呼び出しの引数と構文は、setuptoolsと強く結びついた実装の詳細とみなされます。このビルドシステムインタフェースは、他のビルドバックエンドで使用するためのものではなく、代わりにpyproject.tomlビルドシステムインタフェースに基づいている必要があります。

さらに、プロジェクトはsetup.pyインターフェースに関するいかなる形式の後方互換性の保証があることを期待すべきでは *ありません*。

ビルドプロセス¶

パッケージをビルドするための全体的なプロセスは次のとおりです。

パッケージのメタデータを生成します。
パッケージのwheelを生成します。

必要に応じて、wheelを使用してインストールを実行できます。

メタデータ生成¶

最初のステップとして、pipはパッケージに関するメタデータ（名前、バージョン、依存関係など）を取得する必要があります。これは、setup.py egg_infoを呼び出すことで収集されます。

egg_infoコマンドは、パッケージのメタデータを生成します。これにより、pipはそれを消費し、パッケージのすべての依存関係を収集することができます。依存関係の解決プロセスが完了すると、pipはこれらのパッケージのビルドプロセスの次の段階に進みます。

wheel生成¶

パッケージのソースディストリビューション（または「sdist」）が提供されると、pipはwheelをビルドしようとします。wheelディストリビューションはキャッシュできるため、パッケージの今後のインストールを大幅に高速化できます。

これは、setup.py bdist_wheelを呼び出すことで行われます。これには、wheelパッケージがインストールされている必要があります。

このwheel生成が成功した場合（これは、パッケージによってはC/C++コードのコンパイルを含む場合があります）、生成されたwheelはpipのwheelキャッシュに追加され、このインストールに使用されます。構築されたwheelは、同一のビルドを繰り返さないように、pipによってローカルにキャッシュされます。

このwheel生成が失敗した場合、pipはsetup.py cleanを実行して、生成された可能性のあるビルドアーティファクトをクリーンアップします。その後、pipは直接インストールを試みます。

編集可能なインストール¶

パッケージを「編集可能」モード（pip install --editable）でインストールする場合、pipはsetup.py developを呼び出します。これにより、setuptoolsのメカニズムを使用して、編集可能/開発インストールが実行されます。

Setuptoolsインジェクション¶

distutilsを直接使用するプロジェクトをサポートするために、pipはsetup.pyを呼び出す前に、setuptoolsをsys.modulesに挿入します。このインジェクションは、distutilsベースのプロジェクトに対して透過的である必要があります。

ビルドのカスタマイズ¶

pip installおよびpip wheelに対する--global-optionおよび--build-option引数は、setup.pyコマンドに追加の引数を挿入します（--build-optionはpip wheelでのみ使用できます）。

注意

--global-optionおよび--build-optionの使用は、setuptoolsに非常に固有のものであり、サポートされているインターフェースというよりも、現在の実装の偶然の産物と見なされます。ここでは、完全性のために文書化されています。これらのフラグは、このビルドシステムインターフェースが削除されるとサポートされなくなります。

これらの引数は、次のようにコマンドに含まれます。

python setup.py <global_options> BUILD COMMAND <build_options>

オプションは変更されずに渡され、現在、distutilsコマンドラインへの直接アクセスを提供します。たとえば

Linux

$ python -m pip wheel --global-option bdist_ext --global-option -DFOO wheel

MacOS

$ python -m pip wheel --global-option bdist_ext --global-option -DFOO wheel

Windows

C:> py -m pip wheel --global-option bdist_ext --global-option -DFOO wheel

これにより、pipは次を呼び出します。

setup.py bdist_ext -DFOO bdist_wheel -d TARGET

これにより、プリプロセッサシンボルが拡張ビルドに渡されます。

ビルド出力¶

ビルドシステムによって生成された出力はすべて、pipによって読み取られます（要求された場合はユーザーに表示するため）。ビルドシステムの出力を正しく読み取るために、pipは、出力が明確に定義されたエンコードで書き込まれていることを要求します。具体的には、ユーザーがテキスト出力用に設定したエンコード（Pythonではlocale.getpreferredencodingを使用して取得できます）です。設定されたエンコードがASCIIの場合、pipは（一部のUnixシステムの動作を考慮して）UTF-8を想定します。

ビルドシステムは、呼び出すツール（コンパイラなど）が正しいエンコードで出力を生成するようにする必要があります。実際には、特にWindowsでは、ツールが「OEM」および「ANSI」コードページの使い方が一貫していないため、これが常に可能であるとは限りません。したがって、pipは、正しくエンコードされていないビルドツールの出力が提示された場合に、予期しないバイトシーケンスをPythonスタイルの16進エスケープシーケンス（"\x80\xff"など）に変換して、クリーンに回復を試みます。ただし、出力が誤ったエンコード（文字化け）で表示される可能性はまだあります。