builtdist.md

1> **Источник:** https://python-all.ru/3.8/distutils/builtdist.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 5. Создание готовых дистрибутивов89> **Примечание**10>11> Этот документ сохраняется только до тех пор, пока `setuptools` документация по адресу [https://setuptools.readthedocs.io/en/latest/setuptools.html](https://python-all.ru/3.8/distutils/builtdist.html) не станет самостоятельно охватывать всю актуальную информацию, приведённую здесь.1213«Готовый дистрибутив» – это то, что обычно понимают как «бинарный пакет» или «установщик» (в зависимости от контекста). При этом он не обязательно является бинарным, поскольку может содержать только исходный код Python и/или байт-код; его не называют пакетом, так как это слово уже занято в Python. (А «установщик» – термин, относящийся к миру обычных настольных систем.)1415Готовый дистрибутив – это способ максимально упростить задачу установки вашего дистрибутива модуля: для пользователей RPM-систем Linux это бинарный RPM; для пользователей Windows – исполняемый установщик; для пользователей Debian-систем Linux – пакет Debian и так далее. Очевидно, что один человек не сможет создавать готовые дистрибутивы для всех платформ мира, поэтому Distutils спроектированы так, чтобы разработчики модулей могли сосредоточиться на своей специализации – написании кода и создании исходных дистрибутивов, – а тем временем появляется промежуточное звено, называемое *упаковщиками (packagers)*, которые превращают исходные дистрибутивы в готовые для стольких платформ, сколько существует упаковщиков.1617Конечно, разработчик модуля может сам быть своим упаковщиком; или упаковщиком может быть доброволец «где-то там», имеющий доступ к платформе, которой нет у исходного разработчика; или это может быть программа, которая периодически забирает новые исходные дистрибутивы и превращает их в готовые дистрибутивы для стольких платформ, к скольким у неё есть доступ. Независимо от того, кто они, упаковщик использует скрипт установки и семейство команд **bdist** для создания готовых дистрибутивов.1819В качестве простого примера: если выполнить следующую команду в дереве исходного кода Distutils:2021```python22python setup.py bdist23```2425то Distutils собирает мой дистрибутив модуля (в данном случае сам Distutils), выполняет «фиктивную» установку (также в каталоге `build`) и создаёт готовый дистрибутив типа, принятого по умолчанию для моей платформы. Формат по умолчанию для готовых дистрибутивов – «тупой» tar-файл в Unix и простой исполняемый установщик в Windows. (Этот tar-файл считается «тупым», потому что для работы его нужно распаковать в определённое место.)2627Таким образом, приведённая выше команда в Unix создаёт `Distutils-1.0.plat.tar.gz`; распаковка этого tar-архива в правильном месте устанавливает Distutils точно так же, как если бы был скачан исходный дистрибутив и выполнена команда `python setup.py install`. («Правильное место» – это либо корень файловой системы, либо каталог `prefix` Python, в зависимости от параметров, переданных команде **bdist\_dumb**; по умолчанию «тупые» дистрибутивы создаются относительно `prefix`.)2829Очевидно, что для чистых Python-дистрибутивов это не проще, чем просто выполнить `python setup.py install`, – но для нечистых дистрибутивов, включающих расширения, требующие компиляции, это может означать разницу между тем, смогут ли пользователи использовать эти расширения или нет. А создание «умных» готовых дистрибутивов, таких как RPM-пакет или исполняемый установщик для Windows, гораздо удобнее для пользователей, даже если дистрибутив не содержит никаких расширений.3031Команда **bdist** имеет опцию `--formats`, аналогичную команде **sdist**, которая используется для выбора типов создаваемых готовых дистрибутивов: например,3233```python34python setup.py bdist --format=zip35```3637при выполнении в Unix создаст `Distutils-1.0.plat.zip` – опять же, этот архив будет распакован из корневого каталога для установки Distutils.3839Доступные форматы для готовых дистрибутивов:4041| Формат | Описание | Примечания |42| --- | --- | --- |43| `gztar` | файл tar, сжатый gzip (`.tar.gz`) | (1) |44| `bztar` | файл tar, сжатый bzip2 (`.tar.bz2`) |  |45| `xztar` | xz-сжатый tar-файл (`.tar.xz`) |  |46| `ztar` | сжатый tar-файл (`.tar.Z`) | (3) |47| `tar` | tar-файл (`.tar`) |  |48| `zip` | zip-файл (`.zip`) | (2),(4) |49| `rpm` | RPM | (5) |50| `pkgtool` | Solaris **pkgtool** |  |51| `sdux` | HP-UX **swinstall** |  |52| `wininst` | самораспаковывающийся ZIP-файл для Windows | (4) |53| `msi` | Установщик Microsoft. |  |5455Изменено в версии 3.5: Добавлена поддержка формата `xztar`.5657Примечания:58591. по умолчанию на Unix602. по умолчанию на Windows613. требует внешнюю утилиту **compress**.624. требуется внешняя утилита **zip** или модуль [`zipfile`](https://python-all.ru/3.8/library/zipfile.html#module-zipfile) (входит в стандартную библиотеку Python начиная с Python 1.6)635. требует внешнюю утилиту **rpm** версии 3.0.4 или новее (узнать версию можно с помощью `rpm --version`)6465Необязательно использовать команду **bdist** с опцией `--formats` ; можно также использовать команду, напрямую реализующую интересующий формат. Некоторые из этих **bdist** «подкоманд» фактически создают несколько похожих форматов; например, команда **bdist\_dumb** генерирует все «простые» архивные форматы (`tar`, `gztar`, `bztar`, `xztar`, `ztar` и `zip`), а **bdist\_rpm** генерирует как бинарные, так и исходные RPM. Подкоманды **bdist** и создаваемые ими форматы:6667| Команда | Форматы |68| --- | --- |69| **bdist\_dumb** | tar, gztar, bztar, xztar, ztar, zip |70| **bdist\_rpm** | rpm, srpm |71| **bdist\_wininst** | wininst |72| **bdist\_msi** | msi |7374> **Примечание**75>76> bdist\_wininst устарело начиная с Python 3.8.7778В следующих разделах приводятся подробности о каждой команде **bdist\_\***.7980## 5.1. Создание RPM-пакетов8182Формат RPM используется во многих популярных дистрибутивах Linux, включая Red Hat, SuSE и Mandrake. Если один из них (или любой другой дистрибутив на основе RPM) является привычной средой, создание RPM-пакетов для других пользователей того же дистрибутива не составляет труда. В зависимости от сложности распространяемого модуля и различий между дистрибутивами Linux может быть также возможно создание RPM, работающих на разных дистрибутивах на основе RPM.8384Обычный способ создания RPM для распространяемого модуля – выполнить команду **bdist\_rpm**:8586```python87python setup.py bdist_rpm88```8990или команду **bdist** с опцией `--format`:9192```python93python setup.py bdist --formats=rpm94```9596Первая позволяет указывать параметры, специфичные для RPM; вторая позволяет легко указать несколько форматов за один запуск. Если нужно сделать и то и другое, можно явно указать несколько команд **bdist\_\*** и их параметры:9798```python99python setup.py bdist_rpm --packager="John Doe <jdoe@example.org>" \100                bdist_wininst --target-version="2.0"101```102103Создание RPM-пакетов управляется файлом `.spec`, так же как использование Distutils управляется сценарием setup. Для упрощения работы команда **bdist\_rpm** обычно создаёт файл `.spec` на основе информации, предоставленной в сценарии setup, в командной строке и в любых файлах конфигурации Distutils. Различные параметры и разделы в файле `.spec` берутся из параметров сценария setup следующим образом:104105| Параметр или раздел файла `.spec` | Параметр сценария setup Distutils |106| --- | --- |107| Имя | `name` |108| Summary (в преамбуле) | `description` |109| Версия | `version` |110| Поставщик | `author` и `author_email`, или – & `maintainer` и `maintainer_email` |111| Авторские права | `license` |112| URL | `url` |113| %description (раздел) | `long_description` |114115Кроме того, в файлах `.spec` есть много параметров, которые не имеют соответствующих параметров в сценарии setup. Большинство из них обрабатывается через параметры команды **bdist\_rpm** следующим образом:116117| Параметр или раздел файла `.spec` | Параметр команды **bdist\_rpm** | значение по умолчанию |118| --- | --- | --- |119| Версия | `release` | “1” |120| Группа | `group` | “Разработка/Библиотеки” |121| Поставщик | `vendor` | (см. выше) |122| Упаковщик | `packager` | (нет) |123| Предоставляет | `provides` | (нет) |124| Требует | `requires` | (нет) |125| Конфликтует | `conflicts` | (нет) |126| Заменяет | `obsoletes` | (нет) |127| Дистрибутив | `distribution_name` | (нет) |128| Зависимости сборки | `build_requires` | (нет) |129| Иконка | `icon` | (нет) |130131Очевидно, указывать даже несколько таких параметров в командной строке было бы утомительно и чревато ошибками, поэтому обычно лучше помещать их в конфигурационный файл установки, `setup.cfg` – см. раздел [Написание конфигурационного файла установки](https://python-all.ru/3.8/distutils/configfile.html#setup-config). Если требуется распространять или упаковывать много дистрибутивов модулей Python, можно поместить параметры, применимые ко всем из них, в личный конфигурационный файл Distutils (`~/.pydistutils.cfg`). Чтобы временно отключить этот файл, можно передать параметр `--no-user-cfg` команде `setup.py`.132133Для сборки бинарного RPM-пакета необходимо выполнить три шага, все из которых aвтоматически обрабатываются Distutils:1341351. создать файл `.spec`, описывающий пакет (аналогично сценарию установки Distutils; по сути, большая часть информации из сценария установки попадает в файл `.spec`)1362. создать исходный RPM1373. создать «бинарный» RPM (который может содержать или не содержать двоичный код, в зависимости от того, содержит ли дистрибутив модуля расширения Python)138139Обычно RPM объединяет последние два шага; при использовании Distutils все три шага обычно объединяются.140141При желании эти три шага можно разделить. Можно использовать параметр `--spec-only`, чтобы заставить **bdist\_rpm** только создать файл `.spec` и завершить работу; в этом случае файл `.spec` будет записан в «каталог распространения» – обычно это `dist/`, но его можно изменить с помощью параметра `--dist-dir`. (Обычно файл `.spec` оказывается глубоко в «дереве сборки», во временном каталоге, созданном **bdist\_rpm**.)142143## 5.2. Создание установщиков для Windows144145> **Предупреждение**146>147> bdist\_wininst устарело начиная с Python 3.8.148149Исполняемые установщики – естественный формат для двоичных дистрибутивов на Windows. Они отображают удобный графический интерфейс, показывают информацию о распространяемом модуле, взятую из метаданных в сценарии установки, позволяют пользователю выбрать несколько параметров и запустить или отменить установку.150151Поскольку метаданные берутся из сценария установки, создание установщиков для Windows обычно сводится к выполнению команды:152153```python154python setup.py bdist_wininst155```156157или команду **bdist** с опцией `--formats`:158159```python160python setup.py bdist --formats=wininst161```162163Если у вас чистый дистрибутив модулей (содержащий только чистые модули и пакеты Python), результирующий установщик будет не зависеть от версии и будет иметь имя вроде `foo-1.0.win32.exe`. Обратите внимание, что создание `wininst` двоичных дистрибутивов поддерживается только в системах Windows.164165Если у вас нечистый дистрибутив, расширения могут быть созданы только на платформе Windows и будут зависеть от версии Python. Имя файла установщика будет отражать это и теперь имеет вид `foo-1.0.win32-py2.0.exe`. Вам необходимо создать отдельный установщик для каждой версии Python, которую вы хотите поддерживать.166167Установщик попытается скомпилировать чистые модули в [байт-код](https://python-all.ru/3.8/glossary.html#term-bytecode) после установки в целевой системе в обычном и оптимизирующем режимах. Если по какой-то причине вы не хотите этого, вы можете выполнить команду **bdist\_wininst** с параметром `--no-target-compile` и/или `--no-target-optimize`.168169По умолчанию установщик при запуске отображает классный логотип «Python Powered», но вы также можете предоставить собственное растровое изображение 152x261, которое должно быть файлом Windows `.bmp` с параметром `--bitmap`.170171Установщик также будет отображать большой заголовок на окне фона рабочего стола при запуске, который формируется из имени вашего дистрибутива и номера версии. Это можно изменить на другой текст с помощью параметра `--title`.172173Файл установщика будет записан в «каталог дистрибутива» – обычно `dist/`, но его можно настроить с помощью параметра `--dist-dir`.174175## 5.3. Кросс-компиляция в Windows176177Начиная с Python 2.6, distutils поддерживает кросс-компиляцию между платформами Windows. На практике это означает, что при наличии установленных правильных инструментов можно использовать 32-битную версию Windows для создания 64-битных расширений и наоборот.178179Для сборки под другую платформу укажите параметр `--plat-name` команде сборки. Допустимые значения в настоящее время: 'win32' и 'win-amd64'. Например, в 32-битной версии Windows можно выполнить:180181```python182python setup.py build --plat-name=win-amd64183```184185для сборки 64-разрядной версии вашего расширения. Установщики Windows также поддерживают этот параметр, поэтому команда:186187```python188python setup.py build --plat-name=win-amd64 bdist_wininst189```190191создаст 64-битный установочный исполняемый файл в 32-битной версии Windows.192193Для кросс-компиляции необходимо скачать исходный код Python и выполнить кросс-компиляцию самого Python для целевой платформы – это невозможно из бинарной установки Python (поскольку файлы .lib и т.д. для других платформ не включены). На практике это означает, что пользователю 32-битной операционной системы потребуется использовать Visual Studio 2008, чтобы открыть решение `PCbuild/PCbuild.sln` в дереве исходного кода Python и собрать конфигурацию «x64» проекта 'pythoncore', прежде чем станет возможной кросс-компиляция расширений.194195Обратите внимание, что по умолчанию Visual Studio 2008 не устанавливает 64-битные компиляторы или инструменты. Возможно, потребуется повторно запустить процесс установки Visual Studio и выбрать эти инструменты (использование Панели управления -\> «Установка и удаление программ» – удобный способ проверить или изменить существующую установку.)196197### 5.3.1. Сценарий после установки198199Начиная с Python 2.3, сценарий после установки можно указать с помощью параметра `--install-script`. Должно быть указано базовое имя сценария, и имя файла сценария также должно быть перечислено в аргументе scripts функции setup.200201Этот сценарий будет запущен во время установки в целевой системе после копирования всех файлов, с `argv[1]`, установленным в `-install`, и снова во время удаления перед удалением файлов с `argv[1]`, установленным в `-remove`.202203Сценарий установки выполняется встроенным в установщик Windows, каждый вывод (`sys.stdout`, `sys.stderr`) перенаправляется в буфер и будет отображаться в графическом интерфейсе после завершения сценария.204205Некоторые функции, особенно полезные в этом контексте, доступны как дополнительные встроенные функции в сценарии установки.206207#### `directory_created(path)`208209#### `file_created(path)`210211Эти функции следует вызывать, когда каталог или файл создается сценарием после установки во время установки. Они регистрируют *path* в программе удаления, чтобы он был удален при удалении дистрибутива. Для безопасности каталоги удаляются только в том случае, если они пусты.212213#### `get_special_folder_path(csidl_string)`214215Эта функция позволяет получить расположение специальных папок в Windows, таких как меню «Пуск» или рабочий стол. Она возвращает полный путь к папке. Параметр *csidl\_string* должен быть одной из следующих строк:216217```python218"CSIDL_APPDATA"219220"CSIDL_COMMON_STARTMENU"221"CSIDL_STARTMENU"222223"CSIDL_COMMON_DESKTOPDIRECTORY"224"CSIDL_DESKTOPDIRECTORY"225226"CSIDL_COMMON_STARTUP"227"CSIDL_STARTUP"228229"CSIDL_COMMON_PROGRAMS"230"CSIDL_PROGRAMS"231232"CSIDL_FONTS"233```234235Если папку не удалось получить, возникает исключение [`OSError`](https://python-all.ru/3.8/library/exceptions.html#OSError).236237Какие папки доступны, зависит от конкретной версии Windows и, возможно, от конфигурации. Подробности см. в документации Microsoft по функции `SHGetSpecialFolderPath()`.238239#### `create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]])`240241Эта функция создает ярлык. *target* – путь к программе, которую запускает ярлык. *description* – описание ярлыка. *filename* – название ярлыка, которое увидит пользователь. *arguments* задает аргументы командной строки (если есть). *workdir* – рабочая директория программы. *iconpath* – файл, содержащий значок для ярлыка, а *iconindex* – индекс значка в файле *iconpath*. За подробностями обратитесь к документации Microsoft по интерфейсу `IShellLink`.242243## 5.4. Контроль учётных записей (UAC) в Windows Vista244245Начиная с Python 2.6, bdist\_wininst поддерживает `--user-access-control` опцию. Значение по умолчанию – 'none' (означает, что обработка UAC не выполняется), а другие допустимые значения – 'auto' (означает запрос повышения прав UAC, если Python был установлен для всех пользователей) и 'force' (означает всегда запрашивать повышение прав).246247> **Примечание**248>249> bdist\_wininst устарело начиная с Python 3.8.250