`setup.py` (傳統)¶

在基於 pyproject.toml 建置手法 (於 PEP 517 和 PEP 518) 之前，pip 僅支援透過 setuptools 搭建的 setup.py 檔案來安裝套件。

此處記錄的介面現僅用於傳統目的，直至可完成遷移至基於 pyproject.toml 的建置手法為止。

警告

pip 對 setup.py 進行各種調用的引數與語法，被視為實作細節，與 setuptools 緊密相連。此建置系統介面並非供任何其他建置後端使用，後端應改為採用 pyproject.toml 建置系統介面。

此外，專案不應該依賴 setup.py 介面的任何形式反向相容性保證。

建置流程¶

建置套件的整體流程：

產生套件的元資料。
為套件產生輪子。

接著可使用輪子來執行安裝 (如有需要的話)。

元資料產生¶

第一步是，pip 需要獲取套件的元資料 (名稱、版本、依存關係，以及更多)。它透過呼叫 setup.py egg_info 來收集這些資料。

egg_info 命令會產生套件的元資料，接著 pip 就會消費這些資料，並收集套件的所有依存關係。依存關係解析程序完成後，pip 將會針對這些套件執行建置流程的下一階段。

輪子產生¶

如果收到 (依據 Python 封裝使用者指南)原始程式碼散布 (或「sdist」)，pip 會嘗試幫套件建置 (依據 Python 封裝使用者指南)輪子。由於輪子散布可以快取，這將大幅提升套件未來的安裝速度。

透過呼叫 setup.py bdist_wheel 來完成此動作，此動作需要安裝 wheel 套件。

如果此輪組建立成功（這可能包括編譯 C/C++ 程式碼，視套件而定），產生的輪組會加入到 pip 的輪組快取中，並會用於此安裝。已建置的輪組會由 pip 快取在本地端，以避免重複相同的建置。

如果此輪組建立失敗，pip 會執行 setup.py clean 來清除任何可能已產生建置人工製品。之後，pip 會嘗試直接安裝。

可編輯安裝¶

對於以「可編輯」模式安裝套件 (pip install --editable），pip 會呼叫 setup.py develop，這會使用 setuptools 機制來執行可編輯/開發安裝。

Setuptools 注入¶

為了支援直接使用 distutils 的專案，pip 會在呼叫 setup.py 之前，將 setuptools 注入到 sys.modules 中。此注入對於以 distutils 為基礎的專案應該是透明的。

自訂建置¶

--global-option 和 --build-option 參數傳遞至 pip install 和 pip wheel 會將其他參數注入到 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 將假設為 UTF-8（用以考慮部分 Unix 系統的行為）。

建置系統應確保他們呼叫的任何工具（例如編譯器）產生正確編碼的輸出。實際上，尤其是 Windows 上，工具在使用「OEM」及「ANSI」代碼頁時並未統一，可能會無法做到這一點。因此，如果出現編碼錯誤的建置工具輸出，pip 將嘗試乾淨地還原，方法是將意外的位元組序列轉換為 Python 樣式的十六進位轉換字元序列（"\x80\xff" 等）。然而，輸出依然可能會以錯誤的編碼方式顯示（亂碼）。