---
description: 'Как быстро создать новый порт FreeBSD'
next: books/porters-handbook/slow-porting
params:
  path: /books/porters-handbook/quick-porting/
prev: books/porters-handbook/new-port
showBookMenu: 'true'
tags: ["quick porting", "guide", "port", "ports collection", "how-to"]
title: 'Глава 3. Быстрое портирование'
weight: 3
---

[[quick-porting]]
= Быстрое портирование
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:sectnumoffset: 3
:partnums:
:source-highlighter: rouge
:experimental:
:images-path: books/porters-handbook/

ifdef::env-beastie[]
ifdef::backend-html5[]
:imagesdir: ../../../../images/{images-path}
endif::[]
ifndef::book[]
include::shared/authors.adoc[]
include::shared/mirrors.adoc[]
include::shared/releases.adoc[]
include::shared/attributes/attributes-{{% lang %}}.adoc[]
include::shared/{{% lang %}}/teams.adoc[]
include::shared/{{% lang %}}/mailing-lists.adoc[]
include::shared/{{% lang %}}/urls.adoc[]
toc::[]
endif::[]
ifdef::backend-pdf,backend-epub3[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
endif::[]

ifndef::env-beastie[]
toc::[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]

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

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

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

[NOTE]
====
Перед началом портирования рекомендуется установить переменную man:make[1] `DEVELOPER` в [.filename]#/etc/make.conf#.

[source, shell]
....
# echo DEVELOPER=yes >> /etc/make.conf
....

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

[[porting-makefile]]
== Создание файла [.filename]#Makefile#

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

[.programlisting]
....
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>
....

Посмотрим, сможете ли вы его понять. Более подробный пример приведен в секции crossref:porting-samplem[porting-samplem,пример Makefile].

[[porting-desc]]
== Создание информационных файлов

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

[[porting-pkg-descr]]
=== [.filename]#pkg-descr#

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

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

С другой стороны, содержимое файла [.filename]#pkg-descr# должно быть длиннее, чем crossref:makefiles[makefile-comment,строка `COMMENT` из Makefile]. Оно должно более подробно объяснять, что собой представляет данный порт.
====

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

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

[[porting-pkg-plist]]
=== [.filename]#pkg-plist#

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

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

[.programlisting]
....
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
....

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

[NOTE]
====
Рекомендуется, чтобы имена файлов в этом списке были отсортированы в алфавитном порядке. Это позволит значительно облегчить сверку изменений при обновлении порта. Фреймворк делает это корректно, когда список пакета crossref:plist[plist-autoplist,сгенерирован автоматически].
====

[TIP]
====
Создание списка упаковки вручную может оказаться весьма трудоёмкой задачей. Если порт устанавливает большое количество файлов, раздел об crossref:plist[plist-autoplist,автоматическом построении списка упаковки] может помочь сэкономить время.
====

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

[.programlisting]
....
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
....

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

[TIP]
====
Если порту требуется создать пустой каталог или он создает каталоги вне [.filename]#${PREFIX}# во время установки, обратитесь к разделу crossref:plist[plist-dir-cleaning,Очистка пустых каталогов] для получения дополнительной информации.
====

[TIP]
====
Поскольку `PLIST_FILES` является переменной man:make[1], любая запись с пробелами должна быть заключена в кавычки. Например, при использовании ключевых слов, описанных в man:pkg-create[8] и crossref:plist[plist-keywords,Расширение списка пакетов с помощью ключевых слов], запись должна быть заключена в кавычки.

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

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

[[porting-checksum]]
== Создание файла с контрольной суммой

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

[[porting-testing]]
== Тестирование порта

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

* [.filename]#pkg-plist# не содержит ничего сверх того, что устанавливается портом.
* [.filename]#pkg-plist# содержит абсолютно все, что устанавливается портом.
* Порт может быть установлен с помощью указания цели `install`. Это позволяет убедиться в правильной работе сценария установки.
* Порт может быть правильным образом удалён с помощью указания цели `deinstall`. Это позволяет убедиться в правильной работе сценария удаления.
* Порт имеет доступ к сетевым ресурсам только во время фазы цели `fetch`. Это важно для сборщиков пакетов, таких как package:ports-mgmt/poudriere[].
* Убедитесь, что команду `make package` можно выполнить от имени обычного пользователя (то есть не от `root`). Если это не работает, возможно, потребуется исправить программное обеспечение. См. также crossref:uses[uses-fakeroot,`fakeroot`] и crossref:uses[uses-uidfix,`uidfix`].

[.procedure]
.*Procedure: Рекомендуемый порядок проверки*
. `make stage`
. `make check-orphans`
. `make package`
. `make install`
. `make deinstall`
. `make package` (как пользователь)

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

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

[[porting-portlint]]
== Проверка вашего порта утилитой `portlint`

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

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

[[porting-submitting]]
== Посылка нового порта

Перед посылкой нового порта прочитайте раздел о том, что crossref:porting-dads[porting-dads,можно и нельзя] делать.

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

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

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

[[porting-submitting-diff]]
.Создание [.filename]#.diff# для нового порта
[example]
====
Добавьте все файлы с помощью `git add .`, затем просмотрите изменения с помощью `git diff`. Например:

[source, shell]
....
% git add .
% git diff --staged
....

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

[source, shell]
....
% git commit
% git format-patch origin/main
....

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

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

====

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

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

После отправки порта, пожалуйста, потерпите. Время, необходимое для включения нового порта во FreeBSD, может занимать от нескольких дней до нескольких месяцев. https://bugs.freebsd.org/bugzilla/query.cgi[ Здесь] можно увидеть список ожидающих PR для портов.

Чтобы получить список _открытых_ PR для портов, выберите _Open_ и _Ports & Packages_ в форме поиска, затем нажмите btn:[Search].

После ознакомления с новым портом мы ответим, если это необходимо, и добавим его в дерево. Имя отправителя также будет добавлено в список extref:{contributors}[Дополнительных участников FreeBSD, contrib-additional] и другие файлы.

[IMPORTANT]
====
Ранее можно было отправлять исправления для новых портов, используя файл man:shar[1]; однако с развитием man:git[1] это больше не актуально. Коммиттеры больше не принимают файлы man:shar[1], так как их использование чревато ошибками и не добавляет соответствующую запись в [.filename]#Makefile# категории.
====