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.