Глава 3. Быстрое портирование

Этот перевод может быть устаревшим. Для того, чтобы помочь с переводом, пожалуйста, обратитесь к Сервер переводов FreeBSD.

Содержание

В этом разделе описано, как быстро создать новый порт. Для случаев, когда этот быстрый метод не подходит, полный процесс "Медленного портирования" описан в разделе Медленное портирование.

Во-первых, скачайте оригинальный tar-файл и поместите его в каталог DISTDIR, который по умолчанию есть не что иное, как /usr/ports/distfiles.

Здесь предполагается, что программное обеспечение компилируется без проблем как есть, то есть для работы приложения на вашей системе FreeBSD не потребовалось абсолютно никаких изменений. Если требовалось что-то изменить, то вам придется обратиться также и к следующему разделу — Медленное портирование.

Перед началом портирования рекомендуется установить переменную make(1) DEVELOPER в /etc/make.conf.

# echo DEVELOPER=yes >> /etc/make.conf

Эта настройка включает "режим разработчика", в котором отображаются предупреждения при использовании устаревших конструкций и задействуются некоторые дополнительные проверки при вызове команды make.

3.1. Создание файла Makefile

Минимальный Makefile будет выглядеть примерно так:

PORTNAME=	oneko
DISTVERSION=	1.1b
CATEGORIES=	games
MASTER_SITES=	ftp://ftp.rediris.es/sites/ftp.freebsd.org/pub/FreeBSD/

MAINTAINER=	youremail@example.com
COMMENT=	Cat chasing a mouse all over the screen
WWW=		http://www.daidouji.com/oneko/

.include <bsd.port.mk>

Посмотрим, сможете ли вы его понять. Более подробный пример приведен в секции пример Makefile.

3.2. Создание информационных файлов

Имеется два информационных файла, которые требуются для любого порта, вне зависимости от того, является ли он пакетом или нет. Это pkg-descr и pkg-plist. Префикс pkg- отличает их от других файлов.

3.2.1. pkg-descr

Это более подробное краткое описание порта. От одного до нескольких абзацев, кратко описывающих, что представляет собой порт, будет достаточно.

Это не руководство и не подробное описание того, как использовать или компилировать порт! Пожалуйста, будьте осторожны при копировании из README или manpage. Очень часто они не содержат краткого описания порта или имеют неудобный формат. Например, manpages используют выравнивание по ширине, что особенно плохо выглядит с моноширинными шрифтами.

С другой стороны, содержимое файла pkg-descr должно быть длиннее, чем строка COMMENT из Makefile. Оно должно более подробно объяснять, что собой представляет данный порт.

Хорошо составленный pkg-descr описывает порт достаточно полно, чтобы пользователю не приходилось сверяться с документацией или посещать вебсайт для понимания того, что делает данное программное обеспечение, чем оно может быть полезно или какие хорошие функции у него имеются. Упоминание про определённые требования, такие как используемый графический инструментарий, тяжёлые зависимости, окружение для запуска или используемый язык программирования помогут пользователям определиться, будет ли этот порт для них работать.

URL, который ранее включался в последнюю строку файла pkg-descr, был перемещен в Makefile.

3.2.2. pkg-plist

Здесь перечисляются все файлы, устанавливаемые портом. Его также называют "списком для упаковки", потому что пакет генерируется упаковкой файлов, которые здесь указаны. Имена путей указываются относительно установочного префикса (обычно /usr/local).

Вот маленький пример:

bin/oneko
man/man1/oneko.1.gz
lib/X11/app-defaults/Oneko
lib/X11/oneko/cat1.xpm
lib/X11/oneko/cat2.xpm
lib/X11/oneko/mouse.xpm

Обратитесь к странице справочной системы по команде pkg-create(8) с подробным описанием формата списка упаковки.

Рекомендуется, чтобы имена файлов в этом списке были отсортированы в алфавитном порядке. Это позволит значительно облегчить сверку изменений при обновлении порта. Фреймворк делает это корректно, когда список пакета сгенерирован автоматически.

Создание списка упаковки вручную может оказаться весьма трудоёмкой задачей. Если порт устанавливает большое количество файлов, раздел об автоматическом построении списка упаковки может помочь сэкономить время.

Существует только одно исключение, когда у порта может отсутствовать pkg-plist. Если порт устанавливает лишь несколько файлов, а возможно, и каталогов, то они могут быть перечислены в переменных PLIST_FILES и PLIST_DIRS, соответственно, внутри файла Makefile порта. К примеру, мы можем обойтись без файла pkg-plist у приведённого выше порта oneko, добавив следующие строки в Makefile:

PLIST_FILES=	bin/oneko \
		man/man1/oneko.1.gz \
		lib/X11/app-defaults/Oneko \
		lib/X11/oneko/cat1.xpm \
		lib/X11/oneko/cat2.xpm \
		lib/X11/oneko/mouse.xpm

Использование PLIST_FILES не должно быть чрезмерным. При поиске происхождения файла обычно просматривают файлы pkg-plist в дереве портов с помощью grep. Указание файлов в PLIST_FILES в Makefile усложняет этот поиск.

Если порту требуется создать пустой каталог или он создает каталоги вне ${PREFIX} во время установки, обратитесь к разделу Очистка пустых каталогов для получения дополнительной информации.

Поскольку PLIST_FILES является переменной make(1), любая запись с пробелами должна быть заключена в кавычки. Например, при использовании ключевых слов, описанных в pkg-create(8) и Расширение списка пакетов с помощью ключевых слов, запись должна быть заключена в кавычки.

PLIST_FILES=	"@sample ${ETCDIR}/oneko.conf.sample"

Позже мы увидим, как pkg-plist и PLIST_FILES могут использоваться для выполнения более сложных задач.

3.3. Создание файла с контрольной суммой

Просто введите команду make makesum. Правила утилиты make автоматически сгенерируют файл distinfo. Не пытайтесь создавать этот файл вручную.

3.4. Тестирование порта

Вы должны удостовериться, что правила построения порта выполняют именно то, что вы хотите, включая создание пакета для порта. Вот те важные вещи, которые вы должны проверить:

  • pkg-plist не содержит ничего сверх того, что устанавливается портом.

  • pkg-plist содержит абсолютно все, что устанавливается портом.

  • Порт может быть установлен с помощью указания цели install. Это позволяет убедиться в правильной работе сценария установки.

  • Порт может быть правильным образом удалён с помощью указания цели deinstall. Это позволяет убедиться в правильной работе сценария удаления.

  • Порт имеет доступ к сетевым ресурсам только во время фазы цели fetch. Это важно для сборщиков пакетов, таких как ports-mgmt/poudriere.

  • Убедитесь, что команду make package можно выполнить от имени обычного пользователя (то есть не от root). Если это не работает, возможно, потребуется исправить программное обеспечение. См. также fakeroot и uidfix.

Procedure: Рекомендуемый порядок проверки

  1. make stage

  2. make check-orphans

  3. make package

  4. make install

  5. make deinstall

  6. make package (как пользователь)

Убедитесь, что на любом из этапов не выдается никаких предупреждений.

Тщательное автоматизированное тестирование можно выполнить с помощью ports-mgmt/poudriere из коллекции портов, дополнительную информацию см. в poudriere. Он поддерживает клетки, в которых можно протестировать все указанные выше шаги без воздействия на состояние основной системы.

3.5. Проверка вашего порта утилитой portlint

Будьте добры, пользуйтесь утилитой portlint для проверки того, что ваш порт соответствует нашим рекомендациям. Программа ports-mgmt/portlint является частью Коллекции Портов. В частности, вы можете захотеть проверить, правильно ли сформирован файл Makefile и соответствующим ли образом именован пакет.

Не следуйте слепо выводу portlint. Это статический инструмент для проверки, и иногда он ошибается.

3.6. Посылка нового порта

Перед посылкой нового порта прочитайте раздел о том, что можно и нельзя делать.

Когда вы наконец довольны своим первым портом, единственное, что осталось сделать, это включить его в основное дерево портов FreeBSD и осчастливить этим всех остальных.

Нам не нужны каталог work или пакет pkgname.txz, поэтому их можно удалить.

Далее создайте файл patch(1). Предположим, что порт называется oneko и находится в категории games.

Пример 1. Создание .diff для нового порта

Добавьте все файлы с помощью git add ., затем просмотрите изменения с помощью git diff. Например:

% git add .
% git diff --staged

Убедитесь, что все необходимые файлы включены, затем зафиксируйте изменение в вашей локальной ветке и создайте патч с помощью git format-patch

% git commit
% git format-patch origin/main

Патч, созданный с помощью git format-patch, будет содержать идентификатор автора и адреса электронной почты, что упрощает применение разработчиками (с помощью git am) и правильное указание авторства.

Чтобы упростить применение патча для коммиттеров в их рабочей копии дерева портов, пожалуйста, создайте файл .diff из корня вашего дерева портов.

Отправьте файл oneko.diff через форму отправки отчётов об ошибках. Укажите продукт "Ports & Packages", компонент "Individual Port(s)" и следуйте приведённым там инструкциям. Добавьте краткое описание программы в поле Description PR (например, сокращённую версию COMMENT) и не забудьте прикрепить файл oneko.diff.

Хорошее описание в заголовке сообщения о проблеме значительно облегчает работу коммиттеров портов. Для новых портов мы предпочитаем нечто вроде "[NEW PORT] категория/название_порта краткое описание порта". Следование этой схеме упрощает и ускоряет начало работы по добавлению нового порта.

После отправки порта, пожалуйста, потерпите. Время, необходимое для включения нового порта во FreeBSD, может занимать от нескольких дней до нескольких месяцев. Здесь можно увидеть список ожидающих PR для портов.

Чтобы получить список открытых PR для портов, выберите Open и Ports & Packages в форме поиска, затем нажмите Search.

После ознакомления с новым портом мы ответим, если это необходимо, и добавим его в дерево. Имя отправителя также будет добавлено в список Дополнительных участников FreeBSD и другие файлы.

Ранее можно было отправлять исправления для новых портов, используя файл shar(1); однако с развитием git(1) это больше не актуально. Коммиттеры больше не принимают файлы shar(1), так как их использование чревато ошибками и не добавляет соответствующую запись в Makefile категории.

Изменено: 18 сентября 2025 г. by Vladlen Popolitov

Главная