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

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

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

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

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

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

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

[command]
option=value
...

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

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

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

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

Сноски