3. 编写设置配置文件

笔记

本文档仅保留到 https://setuptools.readthedocs.io/en/latest/setuptools.html 上的 setuptools 文档独立涵盖当前包含在此处的所有相关信息之前。

通常，不可能写下构建发行版先验所需的所有内容：您可能需要从用户或用户系统获取一些信息，以便继续。只要该信息相当简单——例如用于搜索 C 头文件或库的目录列表——然后提供一个配置文件 setup.cfg 供用户编辑是一种廉价且简单的请求方式它。配置文件还允许您为任何命令选项提供默认值，然后安装程序可以在命令行上或通过编辑配置文件来覆盖这些默认值。

安装配置文件是安装脚本（理想情况下对安装程序 1 不透明）和安装脚本的命令行之间的有用中间地带，该命令行不受您的控制且完全由安装人员决定。事实上，setup.cfg（以及目标系统上存在的任何其他 Distutils 配置文件）是在安装脚本的内容之后，但在命令行之前处理的。这有几个有用的结果：

安装人员可以通过编辑 setup.cfg 来覆盖您在 setup.py 中放置的一些内容
您可以为 setup.py 中不容易设置的选项提供非标准默认值
安装程序可以使用 setup.py 的命令行选项覆盖 setup.cfg 中的任何内容

配置文件的基本语法很简单：

[command]
option=value
...

其中 command 是 Distutils 命令之一（例如 build_py、install)和option是command支持的选项之一。可以为每个命令提供任意数量的选项，并且文件中可以包含任意数量的命令部分。空行被忽略，注释也被忽略，它们从 '#' 字符开始直到行尾。只需缩进连续行，就可以将长选项值拆分为多行。

您可以使用通用 --help 选项找出特定命令支持的选项列表，例如

$ python setup.py --help build_ext
[...]
Options for 'build_ext' command:
  --build-lib (-b)     directory for compiled extension modules
  --build-temp (-t)    directory for temporary files (build by-products)
  --inplace (-i)       ignore build-lib and put compiled extensions into the
                       source directory alongside your pure Python modules
  --include-dirs (-I)  list of directories to search for header files
  --define (-D)        C preprocessor macros to define
  --undef (-U)         C preprocessor macros to undefine
  --swig-opts          list of SWIG command line options
[...]

请注意，命令行上拼写为 --foo-bar 的选项在配置文件中拼写为 foo_bar。

例如，假设您希望“就地”构建扩展——也就是说，您有一个扩展 pkg.ext，并且您想要编译后的扩展文件（例如，Unix 上的 ext.so）与纯 Python 模块 pkg.mod1 和 pkg.mod2 放在同一源目录中。您始终可以在命令行上使用 --inplace 选项来确保这一点：

python setup.py build_ext --inplace

但这需要你始终明确指定 build_ext 命令，并记得提供 --inplace。一个更简单的方法是“设置并忘记”这个选项，通过在 setup.cfg 中编码，这个发行版的配置文件：

[build_ext]
inplace=1

这将影响此模块分发的所有构建，无论您是否明确指定 build_ext。如果你在你的源代码分发中包含 setup.cfg，它也会影响最终用户的构建——这对于这个选项来说可能是个坏主意，因为总是就地构建扩展会破坏模块分发的安装。但是，在某些特殊情况下，模块直接构建在其安装目录中，因此可以想象这是一个有用的功能。（不过，分发期望在其安装目录中构建的扩展几乎总是一个坏主意。）

另一个例子：某些命令有很多选项，每次运行都不会改变；例如，bdist_rpm 需要知道生成用于创建 RPM 发行版的“spec”文件所需的一切。这些信息有些来自安装脚本，有些是由 Distutils 自动生成的（例如安装的文件列表）。但是其中一些必须作为 bdist_rpm 的选项提供，这对于每次运行在命令行上执行都会非常乏味。因此，这里是 Distutils 自己的 setup.cfg 的片段：

[bdist_rpm]
release = 1
packager = Greg Ward <gward@python.net>
doc_files = CHANGES.txt
            README.txt
            USAGE.txt
            doc/
            examples/

请注意， doc_files 选项只是一个以空格分隔的字符串，分为多行以提高可读性。

也可以看看

“安装Python模块”中配置文件的语法: 系统管理员手册中提供了有关配置文件的更多信息。

脚注

1: 在 Distutils 完全支持自动配置之前，这个理想可能不会实现。

3. 编写设置配置文件 — Python 文档

3. 编写设置配置文件