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

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

Файл конфигурации установки – это полезный промежуточный вариант между скриптом 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.