3. Написание файла конфигурации setup¶Writing the Setup Configuration File

Часто невозможно заранее описать всё необходимое для сборки дистрибутива a priori: может потребоваться получить информацию от пользователя или от его системы. Если эта информация достаточно проста – например, список каталогов для поиска C-заголовков или библиотек, – то предоставить пользователю файл конфигурации setup.cfg для редактирования – это дешёвый и простой способ её получить. Файлы конфигурации также позволяют задать значения по умолчанию для любых параметров команд, которые установщик может затем переопределить либо в командной строке, либо редактируя файл конфигурации.

Файл конфигурации setup является полезной золотой серединой между скриптом setup – который в идеале должен быть непрозрачным для установщиков 1 – и командной строкой скрипта setup, которая находится вне вашего контроля и полностью зависит от установщика. На самом деле, setup.cfg (и любые другие файлы конфигурации Distutils, присутствующие на целевой системе) обрабатываются после содержимого скрипта setup, но до командной строки. Это имеет несколько полезных следствий:

• установщики могут переопределить часть того, что вы указали в setup.py, редактируя setup.cfg

• вы можете предоставить нестандартные значения по умолчанию для параметров, которые сложно задать в setup.py

• установщики могут переопределить всё в setup.cfg с помощью параметров командной строки для setup.py

Базовый синтаксис файла конфигурации прост:

[command]
option=value
...

где command – одна из команд Distutils (например, build_py, install), а option – один из параметров, поддерживаемых этой командой. Для каждой команды можно указать любое количество параметров, и в файл можно включить любое количество секций команд. Пустые строки игнорируются, как и комментарии, которые начинаются с символа '#' и продолжаются до конца строки. Длинные значения параметров можно разбивать на несколько строк, просто делая отступы для строк продолжения.

Список параметров, поддерживаемых конкретной командой, можно узнать с помощью универсального параметра --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, и вы хотите, чтобы скомпилированный файл расширения (скажем, ext.so в Unix) помещался в тот же каталог с исходным кодом, что и ваши чистые модули 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 должен знать всё необходимое для создания файла «spec» для сборки RPM-дистрибутива. Часть этой информации берётся из скрипта setup, а часть автоматически генерируется Distutils (например, список установленных файлов). Но некоторую информацию приходится передавать в виде параметров bdist_rpm, что было бы очень утомительно делать в командной строке при каждом запуске. Поэтому вот фрагмент из собственного setup.cfg Distutils:

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

Обратите внимание, что параметр doc_files – это просто строка, разделённая пробельными символами и разбитая на несколько строк для удобства чтения.

Сноски

1

Этот идеал, вероятно, не будет достигнут до тех пор, пока автонастройка не будет полностью поддерживаться в Distutils.