3. Запись файла конфигурации установки¶

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

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

• установщики могут отменить часть того, что вы ввели в 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. Часть этой информации поступает из сценария установки, часть автоматически генерируется 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.