3. Написання файлу конфігурації установки

Примітка

Цей документ зберігається лише до тих пір, поки документація setuptools за адресою https://setuptools.readthedocs.io/en/latest/setuptools.html окремо не охопить всю відповідну інформацію, яка зараз включена тут.

Часто неможливо записати все, що потрібно для створення дистрибутива a priori: вам може знадобитися отримати деяку інформацію від користувача або від системи користувача, щоб продовжити. Якщо ця інформація досить проста — список каталогів для пошуку файлів заголовків 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 — один із параметрів, які підтримує ця команда. Для кожної команди можна надати будь-яку кількість параметрів, і до файлу можна включити будь-яку кількість розділів команд. Порожні рядки ігноруються, як і коментарі, які починаються від символу '#' до кінця рядка. Довгі значення параметрів можна розділити на кілька рядків, просто зробивши відступ у рядках продовження.

Ви можете дізнатися список параметрів, які підтримує певна команда, за допомогою універсального параметра --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, що було б дуже втомливо робити в командному рядку для кожного запуску. Отже, ось фрагмент із власного 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 — це просто розділений пробілами рядок, розділений на кілька рядків для зручності читання.

Дивись також

Синтаксис конфігураційних файлів у розділі «Встановлення модулів Python»

Додаткову інформацію про файли конфігурації можна знайти в посібнику для системних адміністраторів.

Виноски

1

Цей ідеал, ймовірно, не буде досягнутий, доки автоматичне налаштування не буде повністю підтримуватися Distutils.