安裝 Python 模組（舊版）
************************

作者:
   Greg Ward

備註:

  整个 "distutils" 包已被弃用并将在 Python 3.12 中被移除。 此文档仅保
  留作参考，并将随包一起被移除。 更多信息请参阅 有什么新变化 条目。

也參考:

  安裝 Python 模組
     最新的模块安装文档。对于常规Python使用，你几乎肯定像使用该文档而
     非这个。

備註:

  这篇文档是历史遗留文档，在
  https://setuptools.readthedocs.io/en/latest/setuptools.html 上的
  "setuptools" 文档独立涵盖此处包含的所有相关信息之后，将不再单独作为
  正式文档保留。

備註:

  本指南仅介绍构建和分发扩展的基本工具，这些扩展是作为此Python版本的一
  部分提供的。 第三方工具提供更易于使用和更安全的替代方案。有关详细信
  息，请参阅 Python 打包用户指南中的 快速推荐部分 。


簡介
====

在Python 2.0中，"distutils" API 首次被添加到标准库中。这向Linux发行版
维护者提供了一个将Python项目转换为发行版软件包的标准方法，以及向系统管
理员们提供了直接将这些软件包安装到目标系统的标准方法。

自从很多年前 Python 2.0 发布，将构建系统和包安装器与语言运行时的释放循
环紧密连接在一起产生了很多问题。现在推荐做法是在项目中使用 "pip" 包安
装器和 "setuptools" 构建系统，而不是直接使用 "distutils"。

请参阅 安裝 Python 模組 和 發布 Python 模組 了解更多细节。

这个旧文档将被保留，至到我们相信 "setuptools" 覆盖了所有内容。


基于 "distutils" 的源代码分发
-----------------------------

如果你下载了一个模块源代码发布包，你可以很快地确定它是否按标准方式，即
使用 Distutils 进行打包和分发。 首先，发布包的名称和版本号将在已下载归
档文件的名称中明确显示，例如 "foo-1.0.tar.gz" 或 "widget-0.9.7.zip"。
然后，归档文件将被解包为类似名称的目录: "foo-1.0" 或 "widget-0.9.7"。
此外，发布包将包含一个安装脚本 "setup.py"，以及一个名为 "README.txt"
或是 "README" 的文件，它应当写明构建和安装模块发布包的方式是简单地在终
端中运行一条命令:

   python setup.py install

Windows 用户应该使用命令提示符来运行命令(Start ‣ Accessories):

   setup.py install

如果这些事情都属实，那么您已经了解了如何构建和安装您已经下载的模块：只
需运行如上的命令。除非您需要以非常规方式安装或者定制构建过程，您其实不
需要本文档。更进一步说，以上命令就是您可以从文档中获得的全部。


标准构建及安装
==============

正如 基于 distutils 的源代码分发 中所描述的那样，通过 Distutils 构建和
安装发行的模块常常只需要在终端执行一个简单的命令。

   python setup.py install


平台差异
--------

您应当总是在分发文件的根目录处运行设置的命令，比如，模块分发的源代码最
高的子目录。例如，如果您刚刚在 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"，则它将被解包至 "C:\Temp\foo-1.0"；你可以使用带有图形用户界
面的归档管理器（如 WinZip）或命令行工具（如 **unzip** 或 **pkunzip**
等）来解包归档文件。 然后，打开一个命令行提示符窗口并运行:

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


拆分任务
--------

运行 "setup.py install" 会在一次运行中构建并安装所有模块。如果你更喜欢
逐步进行——特别是当你想自定义构建过程，或者遇到问题时，这尤其有用——你可
以使用安装脚本每次只做一件事。当构建和安装由不同的用户完成时，这特别有
帮助——例如，你可能想构建一个模块发布包并将其交给系统管理员进行安装（或
者使用超级用户权限自己完成）。

例如，你可以通过调用两次安装脚本，在第一步中构建所有内容，然后在第二步
中安装所有内容:

   python setup.py build
   python setup.py install

如果你这样做，你会注意到运行 **install** 命令会首先运行 **build** 命令
，而在这种情况下，它会很快发现自己无事可做，因为 "build" 目录中的所有
内容都是最新的。

如果你所做的只是安装从网上下载的模块，你可能不需要经常使用这种拆分步骤
的能力，但对于更高级的任务来说，它非常方便。如果你开始分发自己的
Python 模块和扩展，你将单独运行许多独立的 Distutils 命令。


构建的工作原理
--------------

如上所述，**build** 命令负责将要安装的文件放入一个 *构建目录* 中。默认
情况下，这是发布包根目录下的 "build"；如果你非常关注速度，或者希望保持
源代码树的整洁，可以使用 "--build-base" 选项更改构建目录。例如:

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

（或者你也可以通过在系统或个人 Distutils 配置文件中使用指令来永久执行
此操作；请参阅 Distutils 配置文件Configuration Files 一节。）通常情况
下，这是没有必要的。

构建树的默认布局如下:

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

其中 "<plat>" 会展开为当前操作系统/硬件平台和 Python 版本的简短描述。
第一种形式只有一个 "lib" 目录，用于“纯模块发布包”——即仅包含纯 Python
模块的模块发布包。如果模块发布包包含任何扩展（用 C/C++ 编写的模块），
则使用带有两个 "<plat>" 目录的第二种形式。在这种情况下，"temp.*plat*"
目录保存由编译/链接过程生成的临时文件，这些文件实际上不会被安装。无论
哪种情况，"lib" (或 "lib.*plat*") 目录都包含所有将被安装的 Python 模块
（纯 Python 模块和扩展模块）。

在未来，将会添加更多目录来处理 Python 脚本、文档、二进制可执行文件，以
及处理安装 Python 模块和应用程序工作所需的任何其他内容。


安装的工作原理
--------------

在 **build** 命令运行之后（无论你是显式运行它，还是由 **install** 命令
为你运行），**install** 命令的工作相对简单：它所要做的只是将
"build/lib" (或 "build/lib.*plat*") 下的所有内容复制到你选择的安装目录
中。

如果你没有选择安装目录——即如果你只运行 "setup.py install" ——那么
**install** 命令会将模块安装到第三方 Python 模块的标准位置。此位置因平
台以及你构建/安装 Python 本身的方式而异。在 Unix（以及同样基于 Unix 的
macOS）上，它还取决于正在安装的模块发布包是纯 Python 的还是包含扩展的
（“非纯的”）：

+-------------------+-------------------------------------------------------+----------------------------------------------------+---------+
| 平台              | 标准安装位置                                          | 默认值                                             | 註解    |
|===================|=======================================================|====================================================|=========|
| （单一）Unix      | "*prefix*/lib/python*X.Y*/site-packages"              | "/usr/local/lib/python*X.Y*/site-packages"         | (1)     |
+-------------------+-------------------------------------------------------+----------------------------------------------------+---------+
| （类）Unix        | "*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. 在 Python 1.6a1、1.5.2 及更早版本下，Windows 上的默认安装目录是
   "C:Program FilesPython"。

"*prefix*" 和 "*exec-prefix*" 代表 Python 安装到的目录，以及它在运行时
查找其库的目录。它们在 Windows 下总是相同的，而在 Unix 和 macOS 下也往
往是相同的。你可以通过以交互模式运行 Python 并输入几个简单的命令，来弄
清楚你的 Python 安装对 "*prefix*" 和 "*exec-prefix*" 使用的值。在 Unix
下，只需在 shell 提示符下输入 "python"。在 Windows 下，选择 Start ‣
Programs ‣ Python X.Y ‣ Python (command line)。启动解释器后，即可在提
示符下输入 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** 命令在
此基准目录下选择一组目录（称为 *安装方案*）来安装文件。具体细节因平台
而异，因此请阅读以下适用于你的章节。

请注意，各种替代安装方案是互斥的：你可以传递 "--user"，或者 "--home"，
或者 "--prefix" 和 "--exec-prefix"，或者 "--install-base" 和 "--
install-platbase"，但你不能混用这些组合。


可选安装形式：用户方案
----------------------

此方案被设计为针对没有全局 site-packages 目录写入权限或不想安装到该目
录的用户的最便捷解决方案。 它可以通过一个简单的选项来启用:

   python setup.py install --user

文件将被安装到 "site.USER_BASE" （以下简称 "*userbase*"）的子目录中。
此方案将纯 Python 模块和扩展模块安装在同一位置（也称为
"site.USER_SITE"）。以下是包括 macOS 在内的 UNIX 所使用的值：

+-----------------+-------------------------------------------------------------+
| 文件类型        | 安装目录                                                    |
|=================|=============================================================|
| 模組            | "*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" 脚本之后无需执行额外的步骤即可完成安装。

**build_ext** 命令也有一个 "--user" 选项，用于将 "*userbase*/include"
添加到编译器的头文件搜索路径中，并将 "*userbase*/lib" 添加到编译器的库
搜索路径以及共享 C 库的运行时搜索路径 (rpath) 中。


可选安装形式：家目录方案
------------------------

“主方案”背后的理念是你可以构建并维护个人的 Python 模块集。 该方案的名
称源自 Unix 上“主目录”的概念，因为通常 Unix 用户会将其主目录的布局设置
为与 "/usr/" 或 "/usr/local/" 相似。 任何人都可以使用该方案，无论其安
装的操作系统是什么。

安装一个新的模块发布包非常简单

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

其中你可以为 "--home" 选项提供任何你喜欢的目录。在 Unix 上，懒得打字的
人可以只输入一个波浪号 ("~")；**install** 命令会将其展开为你的主目录:

   python setup.py install --home=~

为了让 Python 找到使用此方案安装的发布包，你可能需要 修改 Python 的搜
索路径，或者编辑 "sitecustomize" （参阅 "site"）以调用
"site.addsitedir()" 或直接编辑 "sys.path"。

"--home" 选项定义了安装基准目录。文件将被安装到安装基准目录下的以下目
录中，如下所示：

+-----------------+-------------------------------------------------------------+
| 文件类型        | 安装目录                                                    |
|=================|=============================================================|
| 模組            | "*home*/lib/python"                                         |
+-----------------+-------------------------------------------------------------+
| 脚本            | "*home*/bin"                                                |
+-----------------+-------------------------------------------------------------+
| 数据            | "*home*"                                                    |
+-----------------+-------------------------------------------------------------+
| C 头文件        | "*home*/include/python/*distname*"                          |
+-----------------+-------------------------------------------------------------+

（如果你是使用 Windows 请将斜杠替换为反斜杠。）


可选安装形式：Unix（前缀方案）
------------------------------

“前缀方案”适用于当你希望使用一个 Python 安装程序来执行构建/安装（即运
行 setup 脚本），但需要将模块安装到另一个 Python 安装版（或看起来类似
于另一个 Python 安装版）的第三方模块目录中的情况。 如果这听起来有点不
寻常，确实如此 --- 这就是为什么要先介绍用户和主目录方案的原因。 然而，
至少有两种已知的情况会用到前缀方案。

首先，考虑到许多 Linux 发行版将 Python 放在 "/usr" 中，而不是更传统的
"/usr/local" 中。这是完全恰当的，因为在这些情况下，Python 是“系统”的一
部分，而不是本地附加组件。但是，如果你是从源代码安装 Python 模块，你可
能会希望将它们放在 "/usr/local/lib/python2.*X*" 中，而不是
"/usr/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" 选
项定义了特定于平台的安装基准目录，该目录用于存放特定于平台的文件。（目
前，这只意味着非纯模块发布包，但可以扩展到 C 库、二进制可执行文件等。
）如果未提供 "--exec-prefix"，则默认为 "--prefix"。文件的安装位置如下
：

+-------------------+------------------------------------------------------------+
| 文件类型          | 安装目录                                                   |
|===================|============================================================|
| 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 安
装；如果上面列出的目录尚不存在，则会在安装时创建它们。

顺便说一句，前缀方案之所以重要的真正原因仅仅在于标准 Unix 安装使用了前
缀方案，只不过其 "--prefix" 和 "--exec-prefix" 是由 Python 本身作为
"sys.prefix" 和 "sys.exec_prefix" 提供的。因此，你可能认为自己永远不会
使用前缀方案，但每次你在不带任何其他选项的情况下运行 "python setup.py
install" 时，你都在使用它。

请注意，将扩展安装到替代的 Python 安装中不会影响这些扩展的构建方式：具
体而言，在编译扩展时，将使用与用于运行安装脚本的 Python 解释器一起安装
的 Python 头文件（"Python.h" 及其同类）。你有责任确保用于运行以此方式
安装的扩展的解释器与用于构建它们的解释器兼容。做到这一点的最佳方法是确
保这两个解释器是相同版本的 Python（可能是不同的构建版本，或者是相同构
建版本的副本）。（当然，如果你的 "--prefix" 和 "--exec-prefix" 甚至没
有指向替代的 Python 安装，这就无关紧要了。）


可选安装形式：Windows（前缀方案）
---------------------------------

Windows 没有用户主目录的概念，而且由于 Windows 下的标准 Python 安装比
Unix 下更简单，因此传统上一直使用 "--prefix" 选项在 Windows 上的单独位
置安装附加包。

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

以将模块安装到当前驱动器上的 "TempPython" 目录中。

安装基准目录由 "--prefix" 选项定义；Windows 下不支持 "--exec-prefix"
选项，这意味着纯 Python 模块和扩展模块会安装到同一位置。文件的安装位置
如下：

+-----------------+------------------------------------------------------------+
| 文件类型        | 安装目录                                                   |
|=================|============================================================|
| 模組            | "*prefix*\Lib\site-packages"                               |
+-----------------+------------------------------------------------------------+
| 脚本            | "*prefix*\Scripts"                                         |
+-----------------+------------------------------------------------------------+
| 数据            | "*prefix*"                                                 |
+-----------------+------------------------------------------------------------+
| C 头文件        | "*prefix*\Include{distname}"                               |
+-----------------+------------------------------------------------------------+


自定义安装
==========

有时候，可选安装形式 一节中描述的替代安装方案并不能满足你的需求。你可
能只想调整一两个目录，同时将其余所有内容保留在同一个基准目录下，或者你
可能想完全重新定义安装方案。无论哪种情况，你都是在创建一个 *自定义安装
方案*。

要创建自定义安装方案，你可以从一种替代方案开始，并使用以下选项覆盖用于
各种类型文件的部分安装目录：

+------------------------+-------------------------+
| 文件类型               | 覆盖选项                |
|========================|=========================|
| Python 模块            | "--install-purelib"     |
+------------------------+-------------------------+
| 扩展模块               | "--install-platlib"     |
+------------------------+-------------------------+
| 所有模块               | "--install-lib"         |
+------------------------+-------------------------+
| 脚本                   | "--install-scripts"     |
+------------------------+-------------------------+
| 数据                   | "--install-data"        |
+------------------------+-------------------------+
| C 头文件               | "--install-headers"     |
+------------------------+-------------------------+

这些覆盖选项可以是相对路径、绝对路径，或者根据某个安装基准目录显式定义
。（有两个安装基准目录，它们通常是相同的——只有当你使用 Unix“前缀方案”
并提供不同的 "--prefix" 和 "--exec-prefix" 选项时，它们才会不同；使用
"--install-lib" 将覆盖为 "--install-purelib" 和 "--install-platlib" 计
算或给定的值，推荐用于不区分 Python 模块和扩展模块的方案。）

例如，假设你正在 Unix 下将一个模块发布包安装到你的主目录中——但你希望脚
本放到 "~/scripts" 而不是 "~/bin" 中。正如你所料，你可以使用 "--
install-scripts" 选项覆盖此目录；在这种情况下，提供相对路径是最合理的
，它将相对于安装基准目录（在本例中即你的主目录）进行解释:

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

另一个 Unix 示例：假设你的 Python 安装在构建和安装时使用了前缀
"/usr/local/python"，因此在标准安装下，脚本最终会放在
"/usr/local/python/bin" 中。如果你希望它们改为放在 "/usr/local/bin" 中
，可以为 "--install-scripts" 选项提供这个绝对目录:

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

（这会使用“前缀方案”执行安装，其中前缀是你的 Python 解释器安装时所使用
的任何前缀——在本例中为 "/usr/local/python"。）

如果你在 Windows 上维护 Python，你可能希望第三方模块位于 "*prefix*" 的
子目录中，而不是直接位于 "*prefix*" 本身中。这几乎和自定义脚本安装目录
一样简单——你只需要记住有两种类型的模块需要考虑，即 Python 模块和扩展模
块，它们可以很方便地通过一个选项同时进行控制:

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

指定的安装目录是相对于 "*prefix*" 的。当然，你还必须确保此目录位于
Python 的模块搜索路径中，例如将 ".pth" 文件放在站点目录中（参阅 "site"
）。请参阅 修改 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 配置文件
Configuration 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

请注意，如果你在运行安装脚本时提供了不同的安装基准目录，那么这两者是 *
不* 等价的。例如，

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

在第一种情况下会将纯模块安装到 "/tmp/python/lib" 中，而在第二种情况下
则会安装到 "/tmp/lib" 中。（对于第二种情况，你可能希望提供一个
"/tmp/python" 作为安装基准目录。）

你可能已经注意到示例配置文件输入中使用了 "$HOME" 和 "$PLAT"。这些是
Distutils 配置变量，它们与环境变量非常相似。事实上，在具有环境变量概念
的平台上，你可以在配置文件中使用环境变量，但 Distutils 另外还定义了一
些可能不在你的环境中的额外变量，例如 "$PLAT"。（当然，在没有环境变量的
系统上，例如 Mac OS 9，Distutils 提供的配置变量是你唯一可以使用的变量
。）详见 Distutils 配置文件Configuration Files 一节。

備註:

  当 虚拟环境 被激活时，所有 distutils 配置文件中任何更改安装路径的选
  项都将被忽略，以防止无意中将项目安装到虚拟环境之外。


修改 Python 的搜索路径
----------------------

当 Python 解释器执行 "import" 语句时，它会沿着搜索路径搜索 Python 代码
和扩展模块。当构建解释器时，路径的默认值会被配置到 Python 二进制文件中
。你可以通过导入 "sys" 模块并打印 "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"，而为了导入它们，必须将此目录添加到
"sys.path" 中。有几种不同的方法可以添加该目录。

最方便的方法是将一个路径配置文件添加到已经在 Python 路径上的目录中，通
常是添加到 ".../site-packages/" 目录中。路径配置文件的扩展名为 ".pth"
，每行必须包含一个将被追加到 "sys.path" 的单一路径。（因为新路径是追加
到 "sys.path" 的，所以添加目录中的模块不会覆盖标准模块。这意味着你不能
使用此机制来安装标准模块的修复版本。）

路径可以是绝对路径或相对路径，如果是相对路径，则相对于包含 ".pth" 文件
的目录。更多信息请参阅 "site" 模块的文档。

一种稍显不便的方法是编辑 Python 标准库中的 "site.py" 文件，并修改
"sys.path"。当执行 Python 解释器时会自动导入 "site.py"，除非提供了
"-S" 开关来抑制此行为。因此，你可以简单地编辑 "site.py" 并向其中添加两
行：

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

但是，如果你重新安装相同的次要版本的 Python（例如从 2.2 升级到 2.2.2
时），"site.py" 将被原装版本覆盖。你必须记住它曾被修改过，并在执行安装
之前保存一份副本。

有两个环境变量可以修改 "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 配置文件Configuration Files
=====================================

如上所述，你可以使用 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. 在 Unix 上，如果未定义 "HOME" 环境变量，则将使用标准 "pwd" 模块中的
   "getpwuid()" 函数来确定用户的主目录。这是由 Distutils 使用的
   "os.path.expanduser()" 函数完成的。

3. 即在当前目录（通常是安装脚本所在的位置）中。

4. （另请参阅注释 (1)。）在 Python 1.6 及更高版本下，Python 的默认“安
   装前缀”是 "C:Python"，因此系统配置文件通常是
   "C:PythonLibdistutilsdistutils.cfg"。在 Python 1.5.2 下，默认前缀是
   "C:Program FilesPython"，并且 Distutils 不是标准库的一部分——因此在
   Windows 下的标准 Python 1.5.2 安装中，系统配置文件将是 "C:Program
   FilesPythondistutilsdistutils.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 扩展有时需要为编译器和链接器指定自定义标
志，以便使用特定的库或生成特殊类型的目标代码。如果该扩展尚未在你的平台
上进行过测试，或者你正在尝试交叉编译 Python，情况尤其如此。

在最一般的情况下，扩展作者可能已经预见到编译扩展会很复杂，并提供了一个
供你编辑的 "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" 链接，只需向该行添加 "-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" 文件中指定的编译器标志中。


在 Windows 上使用非 Microsoft 编辑器
------------------------------------


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

本小节描述了将 Distutils 与 Borland C++ 编译器 5.5 版结合使用所需的步
骤。首先你必须知道，Borland 的目标文件格式 (OMF) 与你可以从 Python 或
ActiveState 网站下载的 Python 版本所使用的格式不同。（Python 是用
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]

要让 Distutils 使用 Borland C++ 编译你的扩展，你现在必须输入:

   python setup.py build --compiler=bcpp

如果你想默认使用 Borland C++ 编译器，可以在 Distutils 的个人或系统范围
的配置文件中指定它（参阅 Distutils 配置文件Configuration Files 一节）
。

也參考:

  C++Builder Compiler
     有关 Borland 发布的免费 C++ 编译器的信息，包括下载页面的链接。

  Creating Python Extensions Using Borland's Free Compiler
     介绍如何使用 Borland 发布的免费命令行方式 C++ 编译器构建 Python
     的文档。


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

本节描述了将 Distutils 与 Cygwin 和 MinGW 发行版中的 GNU C/C++ 编译器
结合使用所需的步骤。 [2] 对于使用 Cygwin 构建的 Python 解释器，无需执
行以下任何步骤，一切都应该能够正常工作。

并非所有扩展都可以使用 MinGW 或 Cygwin 进行构建，但许多扩展都可以。最
可能无法工作的扩展是那些使用 C++ 或依赖 Microsoft Visual C 扩展的模块
。

要让 Distutils 使用 Cygwin 编译你的扩展，你必须输入:

   python setup.py build --compiler=cygwin

而对于处于 no-cygwin 模式的 Cygwin [3] 或对于 MinGW，请输入:

   python setup.py build --compiler=mingw32

如果你想默认使用这些选项/编译器中的任何一个，你应该考虑将其写入你的
Distutils 个人或系统范围的配置文件中（参阅 Distutils 配置文件
Configuration Files 一节）。


旧版 Python 和 MinGW
""""""""""""""""""""

以下说明仅适用于你正在将低于 2.4.1 版本的 Python 与低于 3.0.0 版本的
MinGW (带有 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 创建一个导入库。

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

生成的库必须放在与 "python25.lib" 相同的目录中。（应该是你的 Python 安
装目录下的 "libs" 目录。）

如果你的扩展使用了其他库 (zlib 等)，你可能也必须对它们进行转换。转换后
的文件必须与常规库位于相同的目录中。

也參考:

  在 MS Windows 平台上使用 MinGW 构建 Python 模块
     针对 MinGW 环境生成必要的库的相关信息

-[ 註解 ]-

[1] 这也意味着你可以将现有的全部 COFF 库替换为同名的 OMF 库。

[2] 更多資訊請見 https://www.sourceware.org/cygwin/

[3] 你将没有可用的 POSIX 模拟，但你也将不再需要 "cygwin1.dll"。
