Запись файла конфигурации установки
Этот документ сохраняется только до тех пор, пока документация по setuptools по адресуhttps://setuptools.readthedocs.io/en/latest/setuptools.html не будет охватывать всю соответствующую информацию, включенную в настоящее время здесь.
Часто невозможно заранее записать все необходимое для создания дистрибутива : вам может потребоваться получить некоторую информацию от пользователя или из системы пользователя, чтобы продолжить. Пока эта информация довольно проста — например, список каталогов для поиска заголовочных файлов C или библиотек — тогда предоставление файла конфигурации setup.cfg для редактирования пользователями — это дешевый и простой способ запросить его. Файлы конфигурации также позволяют указать значения по умолчанию для любого параметра команды, которые установщик затем может переопределить либо в командной строке, либо путем редактирования файла конфигурации.
Файл конфигурации установки является полезным промежуточным звеном между сценарием установки, который в идеале должен быть непрозрачным для установщиков 1 , и командной строкой сценария установки, который находится вне вашего контроля и полностью зависит от установщика. На самом деле setup.cfg (и любые другие файлы конфигурации Distutils, присутствующие в целевой системе) обрабатываются после содержимого сценария установки, но перед командной строкой. Это имеет несколько полезных последствий:
- установщики могут переопределить часть того, что вы поместили в setup.py , отредактировав setup.cfg
- вы можете указать нестандартные значения по умолчанию для параметров, которые нелегко установить в setup.py .
- установщики могут переопределить что-либо в setup.cfg , используя параметры командной строки для setup.py .
Основной синтаксис конфигурационного файла прост:
где command — одна из команд Distutils (например , build_py , install ), а option — одна из опций, поддерживаемых командой. Для каждой команды может быть задано любое количество параметров, и в файл может быть включено любое количество разделов команд. Пустые строки игнорируются, как и комментарии, которые начинаются от символа ‘#’ до конца строки. Длинные значения опций можно разделить на несколько строк, просто сделав отступ для строк продолжения.
Вы можете узнать список опций, поддерживаемых конкретной командой, с помощью универсальной опции —help , например
$ python setup.py --help build_ext [. ] Options for 'build_ext' command: --build-lib (-b)каталог для скомпилированных модулей расширения --build-temp (-t)каталог для временных файлов (побочных продуктов сборки) --inplace (-i)игнорирует build-lib и помещает скомпилированные расширения в source directory alongside your pure Python modules --include-dirs (-I)список каталогов для поиска заголовочных файлов --define (-D)макросы препроцессора C для определения --undef (-U)Макросы препроцессора C для неопределения --swig-opts список опций командной строки SWIG [. ]
Обратите внимание, что опция —foo-bar в командной строке записывается как foo_bar в файлах конфигурации.
Например, предположим, что вы хотите, чтобы ваши расширения собирались «на месте», то есть у вас есть расширение pkg.ext , и вы хотите, чтобы скомпилированный файл расширения ( скажем, ext.so в Unix) был помещен в тот же файл. исходный каталог как ваши чистые модули Python pkg.mod1 и pkg.mod2 . Вы всегда можете использовать параметр —inplace в командной строке, чтобы убедиться в этом:
python setup.py build_ext --inplace
Но это требует, чтобы вы всегда явно указывали команду build_ext и не —inplace . Более простой способ — «установить и забыть» эту опцию, закодировав ее в setup.cfg , файл конфигурации для этого дистрибутива:
Это повлияет на все сборки этого дистрибутива модуля, независимо от того, укажете ли вы явно build_ext . Если вы setup.cfg в свой исходный дистрибутив, это также повлияет на сборки конечного пользователя — что, вероятно, является плохой идеей для этого варианта, поскольку постоянное создание расширений на месте нарушит установку дистрибутива модулей. Однако в некоторых особых случаях модули создаются прямо в каталоге их установки, так что это, вероятно, полезная возможность. (Однако распространение расширений, которые должны быть собраны в их установочном каталоге, почти всегда является плохой идеей.)
Другой пример: некоторые команды принимают множество параметров, которые не меняются от запуска к запуску; например, bdist_rpm должен знать все, что требуется для создания файла «spec» для создания дистрибутива RPM. Часть этой информации поступает из сценария установки, а часть автоматически генерируется программой Distutils (например, список установленных файлов). Но некоторые из них должны быть предоставлены как опции для bdist_rpm , что было бы очень утомительно делать в командной строке для каждого запуска. Итак, вот фрагмент из собственного setup.cfg Distutils :
[bdist_rpm] release = 1 packager = Greg Ward [email protected]> doc_files = CHANGES.txt README.txt USAGE.txt doc/ examples/
Обратите внимание, что параметр doc_files — это просто строка, разделенная пробелами, разделенная на несколько строк для удобства чтения.
Более подробную информацию о конфигурационных файлах можно найти в руководстве для системных администраторов.
Footnotes
Этот идеал,вероятно,не будет достигнут до тех пор,пока автоконфигурация не будет полностью поддерживаться Distutils.
3. Writing the Setup Configuration File¶
Often, it’s not possible to write down everything needed to build a distribution a priori: you may need to get some information from the user, or from the user’s system, in order to proceed. As long as that information is fairly simple—a list of directories to search for C header files or libraries, for example—then providing a configuration file, setup.cfg , for users to edit is a cheap and easy way to solicit it. Configuration files also let you provide default values for any command option, which the installer can then override either on the command-line or by editing the config file.
The setup configuration file is a useful middle-ground between the setup script —which, ideally, would be opaque to installers [1]—and the command-line to the setup script, which is outside of your control and entirely up to the installer. In fact, setup.cfg (and any other Distutils configuration files present on the target system) are processed after the contents of the setup script, but before the command-line. This has several useful consequences:
- installers can override some of what you put in setup.py by editing setup.cfg
- you can provide non-standard defaults for options that are not easily set in setup.py
- installers can override anything in setup.cfg using the command-line options to setup.py
The basic syntax of the configuration file is simple:
where command is one of the Distutils commands (e.g. build_py, install), and option is one of the options that command supports. Any number of options can be supplied for each command, and any number of command sections can be included in the file. Blank lines are ignored, as are comments, which run from a ‘#’ character until the end of the line. Long option values can be split across multiple lines simply by indenting the continuation lines.
You can find out the list of options supported by a particular command with the universal —help option, e.g.
> 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 [. ]
Note that an option spelled —foo-bar on the command-line is spelled foo_bar in configuration files.
For example, say you want your extensions to be built “in-place”—that is, you have an extension pkg.ext , and you want the compiled extension file ( ext.so on Unix, say) to be put in the same source directory as your pure Python modules pkg.mod1 and pkg.mod2 . You can always use the —inplace option on the command-line to ensure this:
python setup.py build_ext --inplace
But this requires that you always specify the build_ext command explicitly, and remember to provide —inplace . An easier way is to “set and forget” this option, by encoding it in setup.cfg , the configuration file for this distribution:
This will affect all builds of this module distribution, whether or not you explicitly specify build_ext. If you include setup.cfg in your source distribution, it will also affect end-user builds—which is probably a bad idea for this option, since always building extensions in-place would break installation of the module distribution. In certain peculiar cases, though, modules are built right in their installation directory, so this is conceivably a useful ability. (Distributing extensions that expect to be built in their installation directory is almost always a bad idea, though.)
Another example: certain commands take a lot of options that don’t change from run to run; for example, bdist_rpm needs to know everything required to generate a “spec” file for creating an RPM distribution. Some of this information comes from the setup script, and some is automatically generated by the Distutils (such as the list of files installed). But some of it has to be supplied as options to bdist_rpm, which would be very tedious to do on the command-line for every run. Hence, here is a snippet from the Distutils’ own setup.cfg :
[bdist_rpm] release = 1 packager = Greg Ward gward@python.net> doc_files = CHANGES.txt README.txt USAGE.txt doc/ examples/
Note that the doc_files option is simply a whitespace-separated string split across multiple lines for readability.
Syntax of config files in “Installing Python Modules” More information on the configuration files is available in the manual for system administrators.
| [1] | This ideal probably won’t be achieved until auto-configuration is fully supported by the Distutils. |