builtdist.md

1> **Источник:** https://python-all.ru/3.0/distutils/builtdist.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Создание собранных дистрибутивов89«Готовый дистрибутив» – это то, что обычно понимают как «бинарный пакет» или «установщик» (в зависимости от контекста). При этом он не обязательно является бинарным, поскольку может содержать только исходный код Python и/или байт-код; его не называют пакетом, так как это слово уже занято в Python. (А «установщик» – термин, относящийся к миру обычных настольных систем.)1011Готовый дистрибутив – это способ максимально упростить задачу установки вашего дистрибутива модуля: для пользователей RPM-систем Linux это бинарный RPM; для пользователей Windows – исполняемый установщик; для пользователей Debian-систем Linux – пакет Debian и так далее. Очевидно, что один человек не сможет создавать готовые дистрибутивы для всех платформ мира, поэтому Distutils спроектированы так, чтобы разработчики модулей могли сосредоточиться на своей специализации – написании кода и создании исходных дистрибутивов, – а тем временем появляется промежуточное звено, называемое *упаковщиками (packagers)*, которые превращают исходные дистрибутивы в готовые для стольких платформ, сколько существует упаковщиков.1213Разумеется, разработчик модуля может сам быть упаковщиком; или упаковщиком может быть волонтёр, имеющий доступ к платформе, которой нет у разработчика; или это может быть программа, которая периодически забирает новые дистрибутивы исходников и превращает их в сборки для как можно большего числа доступных платформ. Кем бы ни был упаковщик, он использует скрипт setup и семейство команд **bdist** для создания сборок.1415В качестве простого примера: если выполнить следующую команду в дереве исходного кода Distutils:1617```python18python setup.py bdist19```2021затем Distutils собирает мой дистрибутив модуля (в данном случае сам Distutils), выполняет «фиктивную» установку (также в каталог `build`) и создаёт собранный дистрибутив типа по умолчанию для моей платформы. Формат по умолчанию для собранных дистрибутивов – «простой» tar-файл в Unix и простой исполняемый установщик в Windows. (Этот tar-файл считается «простым», потому что для работы его нужно распаковать в определённое место.)2223Таким образом, указанная выше команда в Unix-системе создаёт `Distutils-1.0.plat.tar.gz`; распаковка этого tarball'а из правильного места устанавливает Distutils так же, как если бы вы загрузили исходный дистрибутив и выполнили `python setup.py install`. («Правильное место» – это либо корень файловой системы, либо каталог `prefix` Python, в зависимости от параметров, переданных команде **bdist\_dumb**; по умолчанию простые дистрибутивы создаются относительно `prefix`.)2425Очевидно, что для чистых дистрибутивов Python это не проще, чем просто выполнить `python setup.py install` – но для несчистых дистрибутивов, включающих расширения, которые необходимо компилировать, это может означать разницу между тем, смогут ли пользователи использовать ваши расширения или нет. А создание «интеллектуальных» собранных дистрибутивов, таких как RPM-пакет или исполняемый установщик для Windows, гораздо удобнее для пользователей, даже если ваш дистрибутив не содержит никаких расширений.2627Команда **bdist** имеет опцию *--formats*, аналогичную команде **sdist**, которую можно использовать для выбора типов создаваемого собранного дистрибутива: например,2829```python30python setup.py bdist --format=zip31```3233при выполнении в Unix-системе создаст `Distutils-1.0.plat.zip` – этот архив также будет распакован из корневого каталога для установки Distutils.3435Доступные форматы для готовых дистрибутивов:3637| Формат | Описание | Примечания |38| --- | --- | --- |39| `gztar` | gzip-сжатый tar-файл (`.tar.gz`) | (1),(3) |40| `ztar` | сжатый tar-файл (`.tar.Z`) | (3) |41| `tar` | tar-файл (`.tar`) | (3) |42| `zip` | zip-файл (`.zip`) | (4) |43| `rpm` | RPM | (5) |44| `pkgtool` | Solaris **pkgtool** |  |45| `sdux` | HP-UX **swinstall** |  |46| `rpm` | RPM | (5) |47| `wininst` | самораспаковывающийся ZIP-файл для Windows | (2),(4) |4849Примечания:50511. по умолчанию на Unix522. по умолчанию на Windows5354   **\*\*** Сделать! **\*\***553. требует внешних утилит: **tar** и, возможно, одной из **gzip**, **bzip2** или **compress**564. требует либо внешнюю утилиту **zip**, либо модуль [`zipfile`](https://python-all.ru/3.0/library/zipfile.html#module-zipfile) (входит в стандартную библиотеку Python, начиная с Python 1.6)575. требует внешней утилиты **rpm** версии 3.0.4 или выше (используйте `rpm --version`, чтобы узнать установленную версию)5859Необязательно использовать команду **bdist** с опцией *--formats*; можно также напрямую использовать команду, реализующую нужный формат. Некоторые из этих «подкоманд» **bdist** на самом деле генерируют несколько похожих форматов; например, команда **bdist\_dumb** создаёт все «простые» форматы архивов (`tar`, `ztar`, `gztar` и `zip`), а **bdist\_rpm** создаёт как бинарные, так и исходные RPM. Подкоманды **bdist** и создаваемые ими форматы перечислены ниже:6061| Команда | Форматы |62| --- | --- |63| **bdist\_dumb** | tar, ztar, gztar, zip |64| **bdist\_rpm** | rpm, srpm |65| **bdist\_wininst** | wininst |6667В следующих разделах приводятся подробности о каждой команде **bdist\_\***.6869## Создание простых собранных дистрибутивов7071**\*\*** Нужно задокументировать различие между абсолютными и относительными к префиксу пакетами здесь, но сначала это нужно реализовать! **\*\***7273## Создание RPM-пакетов7475Формат RPM используется во многих популярных дистрибутивах Linux, включая Red Hat, SuSE и Mandrake. Если один из них (или любой другой дистрибутив на основе RPM) является привычной средой, создание RPM-пакетов для других пользователей того же дистрибутива не составляет труда. В зависимости от сложности распространяемого модуля и различий между дистрибутивами Linux может быть также возможно создание RPM, работающих на разных дистрибутивах на основе RPM.7677Обычный способ создания RPM для распространяемого модуля – выполнить команду **bdist\_rpm**:7879```python80python setup.py bdist_rpm81```8283или команда **bdist** с опцией *--format*:8485```python86python setup.py bdist --formats=rpm87```8889Первая позволяет указывать параметры, специфичные для RPM; вторая позволяет легко указать несколько форматов за один запуск. Если нужно сделать и то и другое, можно явно указать несколько команд **bdist\_\*** и их параметры:9091```python92python setup.py bdist_rpm --packager="John Doe <jdoe@example.org>" \93                bdist_wininst --target_version="2.0"94```9596Создание RPM-пакетов управляется файлом `.spec`, примерно так же, как Distutils управляется скриптом установки. Чтобы упростить вам жизнь, команда **bdist\_rpm** обычно создаёт файл `.spec` на основе информации, которую вы предоставляете в скрипте установки, в командной строке и в любых конфигурационных файлах Distutils. Различные опции и разделы в файле `.spec` берутся из опций скрипта установки следующим образом:9798| Опция или раздел файла RPM `.spec` | Параметр сценария setup Distutils |99| --- | --- |100| Имя | *имя* |101| Summary (в преамбуле) | *описание* |102| Версия | *версия* |103| Поставщик | *author* и *author\_email*, или – & *maintainer* и *maintainer\_email* |104| Авторские права | *лицензия* |105| URL | *url* |106| %description (раздел) | *long\_description* |107108Кроме того, в файлах `.spec` есть много опций, которым нет соответствующих опций в скрипте установки. Большинство из них обрабатываются через опции команды **bdist\_rpm** следующим образом:109110| RPM `.spec` опция или раздел | Параметр команды **bdist\_rpm** | значение по умолчанию |111| --- | --- | --- |112| Версия | *release* | “1” |113| Группа | *group* | “Разработка/Библиотеки” |114| Поставщик | *vendor* | (см. выше) |115| Упаковщик | *packager* | (нет) |116| Предоставляет | *provides* | (нет) |117| Требует | *требует* | (нет) |118| Конфликтует | *конфликтует* | (нет) |119| Заменяет | *заменяет* | (нет) |120| Дистрибутив | *distribution\_name* | (нет) |121| Зависимости сборки | *build\_requires* | (нет) |122| Иконка | *иконка* | (нет) |123124Очевидно, что передача даже нескольких таких параметров в командной строке была бы утомительной и чреватой ошибками, поэтому обычно лучше поместить их в конфигурационный файл установки, `setup.cfg` – см. раздел [*Написание конфигурационного файла установки*](https://python-all.ru/3.0/distutils/configfile.html#setup-config). Если распространяется или пакуется множество дистрибутивов модулей Python, может оказаться удобным поместить параметры, применимые ко всем ним, в личный конфигурационный файл Distutils (`~/.pydistutils.cfg`).125126Для сборки бинарного RPM-пакета необходимо выполнить три шага, все из которых aвтоматически обрабатываются Distutils:1271281. создаёт файл `.spec`, который описывает пакет (аналогично скрипту установки Distutils; на самом деле большая часть информации из скрипта установки попадает в файл `.spec`)1292. создать исходный RPM1303. создать «бинарный» RPM (который может содержать или не содержать двоичный код, в зависимости от того, содержит ли дистрибутив модуля расширения Python)131132Обычно RPM объединяет последние два шага; при использовании Distutils все три шага обычно объединяются.133134При желании вы можете разделить эти три шага. Используйте опцию *--spec-only*, чтобы команда **bdist\_rpm** только создала файл `.spec` и завершилась; в этом случае файл `.spec` будет записан в «каталог распространения» – обычно `dist/`, но настраивается опцией *--dist-dir*. (Обычно файл `.spec` оказывается глубоко в «дереве сборки», во временном каталоге, созданном командой **bdist\_rpm**.)135136## Создание установщиков Windows137138Исполняемые установщики – естественный формат для двоичных дистрибутивов на Windows. Они отображают удобный графический интерфейс, показывают информацию о распространяемом модуле, взятую из метаданных в сценарии установки, позволяют пользователю выбрать несколько параметров и запустить или отменить установку.139140Поскольку метаданные берутся из сценария установки, создание установщиков для Windows обычно сводится к выполнению команды:141142```python143python setup.py bdist_wininst144```145146или команда **bdist** с опцией *--formats*:147148```python149python setup.py bdist --formats=wininst150```151152Если у вас дистрибутив из чистых модулей (содержит только чистые модули и пакеты Python), результирующий установщик будет не зависеть от версии и будет иметь имя вроде `foo-1.0.win32.exe`. Такие установщики можно создавать даже на платформах Unix или Mac OS X.153154Если у вас дистрибутив не из чистых модулей, расширения можно создать только на платформе Windows, и они будут зависеть от версии Python. Имя файла установщика будет это отражать и теперь имеет форму `foo-1.0.win32-py2.0.exe`. Вам нужно создавать отдельный установщик для каждой версии Python, которую вы хотите поддерживать.155156Установщик попытается скомпилировать чистые модули в [*байт-код*](https://python-all.ru/3.0/glossary.html#term-bytecode) после установки в целевой системе в обычном и оптимизирующем режиме. Если вы по какой-то причине не хотите, чтобы это происходило, вы можете запустить команду **bdist\_wininst** с опцией *--no-target-compile* и/или опцией *--no-target-optimize*.157158По умолчанию установщик показывает крутой логотип «Python Powered» при запуске, но вы также можете указать собственное растровое изображение в формате `.bmp` Windows с помощью опции *--bitmap*.159160При запуске установщик также отображает крупный заголовок в окне фона рабочего стола, который формируется из названия дистрибутива и номера версии. Его можно заменить другим текстом с помощью параметра *--title*.161162Файл установщика записывается в «каталог дистрибутива» – обычно это `dist/`, но его можно изменить с помощью параметра *--dist-dir*.163164## Кросс-компиляция в Windows165166Начиная с Python 2.6, distutils поддерживает кросс-компиляцию между платформами Windows. На практике это означает, что при наличии установленных правильных инструментов можно использовать 32-битную версию Windows для создания 64-битных расширений и наоборот.167168Чтобы выполнить сборку для другой платформы, укажите параметр *--plat-name* команды build. Допустимые значения: «win32», «win-amd64» и «win-ia64». Например, в 32-разрядной версии Windows можно выполнить:169170```python171python setup.py build --plat-name=win-amd64172```173174для сборки 64-разрядной версии вашего расширения. Установщики Windows также поддерживают этот параметр, поэтому команда:175176```python177python setup.py build --plat-name=win-amd64 bdist_wininst178```179180создаст 64-битный установочный исполняемый файл в 32-битной версии Windows.181182Для кросс-компиляции необходимо загрузить исходный код Python и скомпилировать сам Python для целевой платформы – это невозможно из бинарной установки Python (так как файлы .lib и т. д. для других платформ не включены). На практике это означает, что пользователю 32-разрядной операционной системы потребуется открыть решение `PCBuild/PCbuild.sln` в Visual Studio 2008 в дереве исходных кодов Python и собрать конфигурацию «x64» проекта «pythoncore», прежде чем станет возможной кросс-компиляция расширений.183184Обратите внимание, что по умолчанию Visual Studio 2008 не устанавливает 64-битные компиляторы или инструменты. Возможно, потребуется повторно запустить процесс установки Visual Studio и выбрать эти инструменты (использование Панели управления -\> «Установка и удаление программ» – удобный способ проверить или изменить существующую установку.)185186### Сценарий после установки187188Начиная с Python 2.3, можно указать сценарий после установки с помощью опции *--install-script*. Базовое имя сценария должно быть указано, а имя файла сценария также должно быть перечислено в аргументе scripts функции setup.189190Этот сценарий будет запущен на целевой системе во время установки после копирования всех файлов, при этом `argv[1]` устанавливается в *-install*, и повторно во время удаления перед удалением файлов, при этом `argv[1]` устанавливается в *-remove*.191192Сценарий установки выполняется в составе установщика Windows, весь вывод (`sys.stdout`, `sys.stderr`) перенаправляется в буфер и отображается в графическом интерфейсе после завершения сценария.193194Некоторые функции, особенно полезные в этом контексте, доступны как дополнительные встроенные функции в сценарии установки.195196#### `[directory_created]directory_created(path)`197198#### `file_created(path)`199200Эти функции следует вызывать, когда каталог или файл создается сценарием после установки во время установки. Они регистрируют201202*path*203204в программе удаления, чтобы он был удален при удалении дистрибутива. Для безопасности каталоги удаляются только в том случае, если они пусты.205206#### `[get_special_folder_path]get_special_folder_path(csidl_string)`207208Эта функция позволяет получить расположение специальных папок в Windows, таких как меню «Пуск» или рабочий стол. Она возвращает полный путь к папке. Параметр *csidl\_string* должен быть одной из следующих строк:209210```python211"CSIDL_APPDATA"212213"CSIDL_COMMON_STARTMENU"214"CSIDL_STARTMENU"215216"CSIDL_COMMON_DESKTOPDIRECTORY"217"CSIDL_DESKTOPDIRECTORY"218219"CSIDL_COMMON_STARTUP"220"CSIDL_STARTUP"221222"CSIDL_COMMON_PROGRAMS"223"CSIDL_PROGRAMS"224225"CSIDL_FONTS"226```227228Если папку не удаётся получить, возникает исключение [`OSError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.OSError).229230Доступные папки зависят от конкретной версии Windows и, вероятно, также от конфигурации. Подробнее см. в документации Microsoft по функции `SHGetSpecialFolderPath`.231232## Контроль учётных записей (UAC) в Vista233234Начиная с Python 2.6, bdist\_wininst поддерживает опцию *--user-access-control*. Значение по умолчанию – ‘none’ (означает, что обработка UAC не выполняется), а другие допустимые значения: ‘auto’ (означает запрос повышения прав UAC, если Python был установлен для всех пользователей) и ‘force’ (означает всегда запрашивать повышение).235236#### `[create_shortcut]create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]])`237238Эта функция создаёт ярлык.239240*target*241242– путь к программе, запускаемой ярлыком.243244*description*245246– описание ярлыка.247248*filename*249250– название ярлыка, которое увидит пользователь.251252*arguments*253254задаёт аргументы командной строки (если есть).255256*workdir*257258– рабочая папка программы.259260*iconpath*261262– файл, содержащий значок ярлыка, а263264*iconindex*265266– индекс значка в файле267268*iconpath*269270. Опять же, за подробностями обращайтесь к документации Microsoft по интерфейсу271272`IShellLink`273274.275