On this page
安装 Python 模块(旧版)
Author
- Greg Ward
See also
最新的模块安装文档。对于常规的 Python 使用,您几乎肯定会想要该文档而不是这份文档。
Note
该文档将一直保留,直到https://setuptools.readthedocs.io/en/latest/setuptools.html的setuptools
文档独立涵盖了此处当前包括的所有相关信息。
Note
本指南仅涵盖构建和分发此版本 Python 的一部分提供的扩展的基本工具。第三方工具提供了更易于使用和更安全的替代方案。有关更多信息,请参阅《 Python 打包用户指南》中的快速推荐部分。
Introduction
在 Python 2.0 中,distutils
API 首先添加到标准库中。这为 Linux 发行版维护者提供了将 Python 项目转换为 Linux 发行版软件包的标准方法,为系统 Management 员提供了将它们直接安装到目标系统上的标准方法。
自从 Python 2.0 发布以来的许多年里,将构建系统和程序包安装程序与语言运行时发布周期紧密耦合已成为一个问题,现在建议项目使用pip
程序包安装程序和setuptools
构建系统,而不是而不是直接使用distutils
。
有关更多详细信息,请参见安装 Python 模块和分发 Python 模块。
仅在我们确信setuptools
文档涵盖了所有必要内容之前,这些旧文档才会保留。
基于 Distutils 的源分发
如果下载了模块源分发版,则可以非常迅速地知道它是否以标准方式打包和分发,即使用 Distutils。首先,发行版本的名称和版本号将以下载 Files 的名称突出显示,例如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,应在命令提示符窗口(开始‣附件)中运行以下命令:
setup.py install
如果所有这些都正确,那么您已经知道如何构建和安装刚刚下载的模块:运行上面的命令。除非您需要以非标准的方式安装东西或自定义构建过程,否则您实际上并不需要此手册。更确切地说,以上命令是您摆脱本手册所需要的一切。
标准构建和安装
如第基于 Distutils 的源分发节所述,使用 Distutils 构建和安装模块发行版通常是从终端运行的一个简单命令:
python setup.py install
Platform variations
您应始终从分发根目录(即模块源分发解压缩到的顶级子目录)中运行 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
,则它将解压缩到C:\Temp\foo-1.0
;您可以使用带有图形用户界面的存档操纵器(例如 WinZip)或命令行工具(例如 unzip 或 pkunzip )来解压缩存档。然后,打开命令提示符窗口并运行:
cd c:\Temp\foo-1.0
python setup.py install
分解工作
运行setup.py install
可以一次运行生成并安装所有模块。如果您希望以增量方式工作(特别是在要自定义构建过程或出现问题时特别有用),则可以一次使用设置脚本来做一件事。当构建和安装将由不同的用户完成时,这特别有帮助-例如,您可能希望构建模块分发并将其分发给系统 Management 员进行安装(或使用超级用户权限自行完成)。
例如,可以pass两次调用安装脚本来一步一步构建所有内容,然后第二步安装一切:
python setup.py build
python setup.py install
如果这样做,您会注意到运行 install 命令首先运行 build 命令,在这种情况下,它会迅速注意到它无关紧要,因为build
目录中的所有内容都已启动-至今。
如果您要做的只是安装从网络上下载的模块,则可能不需要经常分解的Function,但是对于执行更高级的任务而言,它非常方便。如果您要分发自己的 Python 模块和扩展,则将自己运行许多单独的 Distutils 命令。
构建的运作方式
如上所示, build 命令负责将要安装的文件放入* 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
目录,用于“纯模块分发”,即仅包含纯 Python 模块的模块分发。如果模块发行版包含任何 extensions(使用 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(和 Mac OS X,也基于 Unix)上,它还取决于要安装的模块分发是纯 Python 还是包含 extensions(“非纯”):
Platform | 标准安装位置 | Default value | Notes |
---|---|---|---|
Unix (pure) | prefix/lib/pythonX.Y/site-packages |
/usr/local/lib/pythonX.Y/site-packages |
(1) |
Unix (non-pure) | exec-prefix/lib/pythonX.Y/site-packages |
/usr/local/lib/pythonX.Y/site-packages |
(1) |
Windows | prefix\Lib\site-packages |
C:\PythonXY\Lib\site-packages |
(2) |
Notes:
大多数 Linux 发行版都将 Python 作为系统的标准部分,因此
prefix
和exec-prefix
在 Linux 上通常都是/usr
。如果您在 Linux(或任何类似 Unix 的系统)上自行构建 Python,则默认prefix
和exec-prefix
为/usr/local
。Windows 上的默认安装目录在 Python 1.6a1、1.5.2 和更低版本下为
C:\Program Files\Python
。
prefix
和exec-prefix
代表 Python 安装到的目录,以及它在运行时在其中找到其库的位置。在 Windows 下,它们总是相同的,而在 Unix 和 Mac OS X 下,它们通常是相同的。pass以交互方式运行 Python 并键入一些简单的命令,您可以找出 python 安装用于prefix
和exec-prefix
的含义。在 Unix 下,只需在 shell 提示符下键入python
。在 Windows 下,选择开始‣程序‣Python X.Y‣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
。
如果您不想将模块安装到标准位置,或者没有权限在此处编写模块,则需要在Alternate Installation部分中阅读有关替代安装的信息。如果您想更加自定义安装目录,请参阅关于自定义安装的Custom Installation部分。
Alternate Installation
通常,有必要或希望将模块安装到第三方 Python 模块的标准位置以外的其他位置。例如,在 Unix 系统上,您可能没有写标准第三方模块目录的权限。或者,您可能希望先try一个模块,然后再将其作为本地 Python 安装的标准部分。升级已经存在的发行版时尤其如此:您要确保实际升级之前,现有脚本库仍可与新版本一起使用。
Distutils install 命令旨在使安装模块分发到其他位置变得简单而轻松。基本思想是为安装提供基本目录,并且 install 命令在此基本目录下选择一组目录(称为安装方案),用于在其中安装文件。各个平台的详细信息各不相同,因此请阅读以下适用于您的任何部分。
请注意,各种备用安装方案是互斥的:您可以传递--user
或--home
,或者--prefix
和--exec-prefix
,或者--install-base
和--install-platbase
,但是不能从这些组中混合使用。
备用安装:用户方案
对于没有全局站点包目录写权限或不想安装到全局站点包目录的用户,此方案旨在成为最方便的解决方案。pass一个简单的选项启用它:
python setup.py install --user
文件将被安装到site.USER_BASE的子目录中(此后记为userbase
)。此方案将纯 Python 模块和扩展模块安装在同一位置(也称为site.USER_SITE)。以下是 UNIX 的值,包括 Mac OS X:
Files 类型 | Installation directory |
---|---|
modules | userbase/lib/pythonX.Y/site-packages |
scripts | userbase/bin |
data | userbase |
C headers | userbase/include/pythonX.Yabiflags/distname |
以下是 Windows 上使用的值:
Files 类型 | Installation directory |
---|---|
modules | userbase\PythonXY\site-packages |
scripts | userbase\PythonXY\Scripts |
data | userbase |
C headers | userbase\PythonXY\Include{distname} |
与下文所述的其他方案相比,使用此方案的优势在于,用户 site-packages 目录在正常情况下始终包含在sys.path中(有关更多信息,请参见site),这意味着在运行该方案后无需执行其他步骤。 setup.py
脚本完成安装。
build_ext 命令还具有--user
选项,可将userbase/include
添加到头文件的编译器搜索路径中,并将userbase/lib
添加到库的编译器搜索路径中,并将userbase/lib
添加到共享 C 库的运行时搜索路径(rpath)中。
备用安装:家庭方案
“家庭方案”背后的想法是,您构建并维护一个个人的 Python 模块存储库。该方案的名称源自 Unix 上的“ home”目录,因为对于 Unix 用户而言,使其主目录具有类似于/usr/
或/usr/local/
的布局并不罕见。任何人都可以使用此方案,无论他们要安装的 os 是什么。
安装新的模块发行版非常简单
python setup.py install --home=<dir>
您可以在其中提供--home
选项所需的任何目录。在 Unix 上,懒惰的 typing 员只能 Importing 波浪号(~
); install 命令会将其扩展到您的主目录:
python setup.py install --home=~
为了使 Python 查找使用此方案安装的发行版,您可能必须修改 Python 的搜索路径或编辑sitecustomize
(请参阅site)来调用site.addsitedir()或编辑sys.path。
--home
选项定义安装基础目录。将文件安装到安装基础下的以下目录中,如下所示:
Files 类型 | Installation directory |
---|---|
modules | home/lib/python |
scripts | home/bin |
data | home |
C headers | home/include/python/distname |
(如果您使用的是 Windows,请用反斜杠替换掉斜杠.)
备用安装:Unix(前缀方案)
当您希望使用一个 Python 安装来执行构建/安装(即,运行安装脚本)但将模块安装到另一个 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
。文件安装如下:
Files 类型 | Installation directory |
---|---|
Python modules | prefix/lib/pythonX.Y/site-packages |
extension modules | exec-prefix/lib/pythonX.Y/site-packages |
scripts | prefix/bin |
data | prefix |
C headers | prefix/include/pythonX.Yabiflags/distname |
并不需要--prefix
或--exec-prefix
实际指向其他 Python 安装;如果上面列出的目录尚不存在,则会在安装时创建它们。
顺便说一句,前缀方案很重要的 true 原因仅仅是标准的 Unix 安装使用了前缀方案,而 Python 本身提供的--prefix
和--exec-prefix
分别为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"
将模块安装到当前驱动器的\Temp\Python
目录中。
安装基础由--prefix
选项定义; Windows 不支持--exec-prefix
选项,这意味着将纯 Python 模块和扩展模块安装在同一位置。文件安装如下:
Files 类型 | Installation directory |
---|---|
modules | prefix\Lib\site-packages |
scripts | prefix\Scripts |
data | prefix |
C headers | prefix\Include{distname} |
Custom Installation
有时,第Alternate Installation节中描述的备用安装方案只是不执行您想要的操作。您可能只想调整一个或两个目录,同时将所有内容都保留在同一基本目录下,或者您可能想要完全重新定义安装方案。无论哪种情况,您都是在创建自定义安装方案。
要创建自定义安装方案,请从一种替代方案开始,并使用以下选项覆盖用于各种文件类型的某些安装目录:
Files 类型 | Override option |
---|---|
Python modules | --install-purelib |
extension modules | --install-platlib |
all modules | --install-lib |
scripts | --install-scripts |
data | --install-data |
C headers | --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 和扩展模块,可以方便地pass一个选项控制它们:
python setup.py install --install-lib=Site
指定的安装目录是相对于prefix
的。当然,您还必须确保此目录位于 Python 的模块搜索路径中,例如pass将.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
or, equivalently,
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
or, equivalently,
[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/python
的安装基础.)
您可能已经注意到 samples 配置文件 Importing 中使用了$HOME
和$PLAT
。这些是 Distutils 配置变量,与环境变量非常相似。实际上,您可以在具有这种概念的平台上的配置文件中使用环境变量,但 Distutils 还会定义一些可能不在您的环境中的额外变量,例如$PLAT
。 (当然,在没有环境变量的系统上,例如 Mac OS 9,Distutils 提供的配置变量是唯一可以使用的变量.)有关详细信息,请参见Distutils 配置文件。
Note
激活virtual environment时,所有 distutils 配置文件中都会忽略任何更改安装路径的选项,以防止在虚拟环境之外无意中安装项目。
修改 Python 的搜索路径
当 Python 解释器执行import语句时,它将沿着搜索路径同时搜索 Python 代码和扩展模块。构建解释器时,会将路径的默认值配置到 Python 二进制文件中。您可以pass导入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/
目录。路径配置文件的 extensions 为.pth
,并且每行必须包含一个附加到sys.path
的路径。 (由于新路径附加到sys.path
,添加目录中的模块将不会覆盖标准模块.这意味着您不能使用此机制来安装标准模块的固定版本.)
路径可以是绝对路径,也可以是相对路径,在这种情况下,它们是相对于包含.pth
文件的目录的。有关更多信息,请参见site模块的文档。
不太方便的方法是在 Python 的标准库中编辑site.py
文件,然后修改sys.path
。 site.py
在执行 Python 解释器时会自动导入,除非提供-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 应用程序都可以pass添加或删除条目来对其进行修改。
Distutils 配置文件
如上所述,您可以使用 Distutils 配置文件记录任何 Distutils 选项的个人或站点首选项。也就是说,任何命令的任何选项都可以存储在两个或三个(取决于您的平台)配置文件中的一个中,在解析命令行之前将先进行配置。这意味着配置文件将覆盖默认值,而命令行将依次覆盖配置文件。此外,如果应用了多个配置文件,则“较早”文件中的值将被“较晚”文件覆盖。
配置文件的位置和名称
配置文件的名称和位置在不同平台上略有不同。在 Unix 和 Mac OS X 上,三个配置文件(按处理 Sequences)是:
Files 类型 | 位置和文件名 | Notes |
---|---|---|
system | prefix/lib/pythonver/distutils/distutils.cfg |
(1) |
personal | $HOME/.pydistutils.cfg |
(2) |
local | setup.cfg |
(3) |
在 Windows 上,配置文件为:
Files 类型 | 位置和文件名 | Notes |
---|---|---|
system | prefix\Lib\distutils\distutils.cfg |
(4) |
personal | %HOME%\pydistutils.cfg |
(5) |
local | setup.cfg |
(3) |
在所有平台上,可以pass传递–no-user-cfg 选项来暂时禁用“个人”文件。
Notes:
严格来说,系统范围的配置文件位于 Distutils 的安装目录中。如图所示,在 Python 1.6 和更高版本的 Unix 下。对于 Python 1.5.2,通常将 Distutils 安装到
prefix/lib/python1.5/site-packages/distutils
,因此系统配置文件应放在 Python 1.5.2 下。在 Unix 上,如果未定义
HOME
环境变量,则将使用标准pwd模块中的getpwuid()
函数确定用户的主目录。这是由 Distutils 使用的os.path.expanduser()函数完成的。即在当前目录中(通常是安装脚本的位置)。
(另请参见 Comments(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
。在 Windows 上,如果未定义
HOME
环境变量,则将tryUSERPROFILE
然后HOMEDRIVE
和HOMEPATH
。这是由 Distutils 使用的os.path.expanduser()函数完成的。
配置文件的语法
Distutils 配置文件都具有相同的语法。配置文件分为几部分。每个 Distutils 命令都有一个部分,另外还有一个global
部分用于影响每个命令的全局选项。每个部分每行包含一个选项,指定为option=value
。
例如,以下是一个完整的配置文件,该文件默认情况下仅强制所有命令安静运行:
[global]
verbose=0
如果将其作为系统配置文件安装,它将影响当前系统上任何用户对任何 Python 模块分发的所有处理。如果作为个人配置文件安装(在支持它们的系统上),它将仅影响您处理的模块分发。并且,如果将其用作特定模块发行版的setup.cfg
,它将仅影响该发行版。
您可以覆盖默认的“ build base”目录,并使 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 尽可能try使用用于运行setup.py
脚本的 Python 解释器提供的配置信息。例如,用于编译 Python 的相同编译器和链接器标志也将用于编译扩展。通常这会很好地工作,但是在复杂的情况下这可能是不合适的。本节讨论如何覆盖常规的 Distutils 行为。
调整编译器/链接器标志
编译用 C 或 C 编写的 Python 扩展有时会要求为编译器和链接器指定自定义标志,以便使用特定的库或生成特殊类型的目标代码。如果未在平台上测试扩展,或者try交叉编译 Python,则尤其如此。
在最一般的情况下,扩展作者可能已经预见到,扩展的编译会很复杂,并提供了一个Setup
文件供您编辑。仅当模块分发中包含许多单独的扩展模块,或者它们通常需要复杂的编译器标志集才能工作时,才可能这样做。
解析Setup
文件(如果存在)以获取要构建的扩展列表。 Setup
中的每一行都描述一个模块。行具有以下结构:
module ... [sourcefile ...] [cpparg ...] [library ...]
让我们依次检查每个字段。
-
- module *是要构建的扩展模块的名称,并且应该是有效的 Python 标识符。您不能仅仅为了更改模块名称而更改此名称(也需要对源代码进行编辑),因此应将其保留下来。
-
- sourcefile *是任何可能是源代码文件的文件,至少从文件名来看。假定以
.c
结尾的文件名用 C 编写,以.C
,.cc
和.c++
结尾的文件名假定为 C,并且以.m
或.mm
结尾的文件名假定在目标 C 中。
- sourcefile *是任何可能是源代码文件的文件,至少从文件名来看。假定以
-
- cpparg *是 C 预处理程序的参数,并且可以是
-I
,-D
,-U
或-C
开头的任何东西。
- cpparg *是 C 预处理程序的参数,并且可以是
-
- library *是以
.a
结尾或以-l
或-L
开头的任何内容。
- library *是以
如果特定平台需要平台上的特殊库,则可以pass编辑Setup
文件并运行python setup.py build
来添加它。例如,如果模块由行定义
foo foomodule.c
必须与您平台上的 math 库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++
。
也可以pass设置 CFLAGS
环境变量来提供编译器标志。如果设置,则 CFLAGS
的内容将添加到Setup
文件中指定的编译器标志中。
在 Windows 上使用非 Microsoft 编译器
Borland/CodeGear C++
本小节介绍将 Distutils 与 Borland C 编译器 5.5 版一起使用的必要步骤。首先,您必须知道 Borland 的目标文件格式(OMF)与可从 Python 或 ActiveState 网站下载的 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 如何设法将这些库及其更改后的名称一起使用?如果 extensions 需要一个库(例如foo
),则 Distutils 首先检查是否找到带有后缀_bcpp
(例如foo_bcpp.lib
)的库,然后使用该库。如果找不到这种特殊的库,它将使用默认名称(foo.lib
)[1]
要让 Distutils 使用 Borland C 编译扩展,您现在必须 Importing:
python setup.py build --compiler=bcpp
如果要使用 Borland C 编译器作为默认编译器,则可以在您的个人或系统范围的 Distutils 配置文件中指定它(请参见Distutils 配置文件)。
See also
有关来自 Borland 的免费 C 编译器的信息,包括下载页面的链接。
说明如何使用 Borland 的免费命令行 C 编译器构建 Python 的文档。
GNU C/Cygwin/MinGW
本节介绍了在其 Cygwin 和 MinGW 发行版中将 Distutils 与 GNU C/C 编译器一起使用的必要步骤。 [2]对于使用 Cygwin 构建的 Python 解释器,无需执行以下任何步骤,一切都可以正常工作。
并非所有扩展都可以使用 MinGW 或 Cygwin 构建,但是很多可以。最可能无法使用的扩展是那些使用 C 或依赖于 Microsoft Visual C 扩展的扩展。
要让 Distutils 使用 Cygwin 编译扩展,您必须 Importing:
python setup.py build --compiler=cygwin
对于非 Cygwin 模式[3]的 Cygwin 或 MinGW 类型:
python setup.py build --compiler=mingw32
如果要默认使用这些选项/编译器中的任何一个,则应考虑将其写入 Distutils 的个人或系统范围的配置文件中(请参阅Distutils 配置文件。)
旧版本的 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 的 importlib。
/cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a
生成的库必须与python25.lib
放在同一目录中。 (应该是 Python 安装目录下的libs
目录.)
如果您的扩展程序使用其他库(zlib 等),则可能也必须转换它们。转换后的文件必须与普通库位于相同的目录中。
See also
有关为 MinGW 环境构建所需的库的信息。
Footnotes
-
- 这也意味着您可以用相同名称的 OMF 库替换所有现有的 COFF 库。
-
- 这样就没有可用的 POSIX 仿真,但也不需要
cygwin1.dll
。
- 这样就没有可用的 POSIX 仿真,但也不需要