Написание файла конфигурации установки

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

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

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

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

[command]
option=value
...

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

Список параметров, поддерживаемых конкретной командой, можно узнать с помощью универсального параметра --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 должен знать все, что нужно для генерации файла «спецификации» для создания дистрибутива RPM. Часть этой информации поступает из скрипта установки, и часть автоматически генерируется 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 представляет собой просто строку, разделенную пробелами, разбитую на несколько строк для удобочитаемости.

Примечания

1

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