path: root/documentation/content/ru/books/porters-handbook/quick-porting/_index.adoc

---
title: Глава 3. Быстрое портирование
prev: books/porters-handbook/new-port
next: books/porters-handbook/slow-porting
showBookMenu: true
weight: 3
path: "/books/porters-handbook/"
---

[[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::[]

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

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

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

[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]
....
# $FreeBSD$

PORTNAME=	oneko
PORTVERSION=	1.1b
CATEGORIES=	games
MASTER_SITES=	ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/

MAINTAINER=	youremail@example.com
COMMENT=	Cat chasing a mouse all over the screen

.include <bsd.port.mk>
....

[NOTE]
====
В некоторых случаях в заголовке [.filename]#Makefile# существующего порта могут содержаться дополнительные строки, такие как название порта и дата его создания. Эта дополнительная информация была объявлена устаревшей и находится в процессе удаления.
====

Посмотрим, сможете ли вы его понять. Не обращайте внимание на содержимое строчки `$FreeBSD$`, она будет заполнена автоматически системой Subversion, когда порт будет импортирован в наше дерево портов. Вы можете найти более подробный пример в разделе <<porting-samplem,пример Makefile>>.

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

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

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

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

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

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

Включите сюда URL официальной домашней страницы Интернет. Перед _одним_ из сайтов (выберите основной) добавьте `WWW:` (с последующим единичным пробелом) для того, чтобы вспомогательные утилиты работали правильно. Если URI является корнем сайта или каталогом, то значение должно быть дополнено косой чертой.

[NOTE]
====
Если указанная для порта веб-страница не доступна, попытайтесь сперва поискать, был ли официальный сайт перемещён, переименован или размещён в другом месте.
====

Следующий пример показывает, как должен выглядеть ваш [.filename]#pkg-descr#:

[.programlisting]
....
This is a port of oneko, in which a cat chases a poor mouse all over
the screen.
 :
(etc.)

WWW: http://www.oneko.org/
....

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

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

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

[.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
@dirrm lib/X11/oneko
....

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

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

[NOTE]
====
Создание списка упаковки вручную может оказаться весьма трудоёмкой задачей. Если порт устанавливает большое количество файлов, раздел об <<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
PLIST_DIRS=	lib/X11/oneko
....

Конечно, переменная `PLIST_DIRS` не должна задаваться, если порт не устанавливает никаких каталогов.

[NOTE]
====
Несколько портов могут совместно использовать общий каталог. В этом случае `PLIST_DIRS` следует заменить на `PLIST_DIRSTRY`, так чтобы каталог удалялся только если он пуст, а иначе игнорировался. Использование `PLIST_DIRS` и `PLIST_DIRSTRY` аналогично `@dirrm` и `@dirrmtry` в [.filename]#pkg-plist#, описание которых входит в crossref:plist[plist-dir-cleaning,Очистка пустых каталогов].
====

Обратной стороной такого способа перечисления файлов и каталогов порта является невозможность использования последовательностей команд, описанных в man:pkg-create[8]. Поэтому он подходит для простых портов, что делает их ещё более простыми. Одновременно с этим положительным моментом является уменьшение количества файлов в коллекции портов. Пожалуйста, подумайте над использованием этой техники, прежде чем создавать [.filename]#pkg-plist#.

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

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

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

Если у извлекаемого файла регулярно меняется контрольная сумма и вы не сомневаетесь в надежности источника (т.е. он получен из CD производителя, либо ежедневно обновляется документация), то вы должны указать эти файлы в переменной `IGNOREFILES`. Тогда контрольная сумма при выполнении `make makesum` для этого файла создаваться не будет, а вместо этого для него будет установлено значение `IGNORE`.

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

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

* [.filename]#pkg-plist# не содержит ничего сверх того, что устанавливается портом
* [.filename]#pkg-plist# содержит абсолютно все, что устанавливается портом
* Порт может быть установлен с помощью указания цели `install`. Это позволяет убедиться в правильной работе сценария установки.
* Порт может быть правильным образом удалён с помощью указания цели `deinstall`. Это позволяет убедиться в правильной работе сценария удаления.
* Следует убедиться, что `make package` можно запустить из-под обычного пользователя (то есть, не из-под `root`). Если это не так, в [.filename]#Makefile# порта должно быть добавлено `NEED_ROOT=yes`.

[.procedure]
====
*Procedure: Рекомендуемый порядок проверки*

. `make stage`
. `make check-orphans`
. `make package`
. `make install`
. `make deinstall`
. `pkg add package-filename`
. `make package` (из-под пользователя)
====

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

Основательное автоматизированное тестирование может быть выполнено при помощи package:ports-mgmt/tinderbox[] или package:ports-mgmt/poudriere[] из Коллекции Портов. Эти приложения используют `jails`, в которых проверяются все перечисленные выше этапы без изменения состояния основной системы.

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

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

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

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

Когда вы наконец довольны своим первым портом, единственное, что осталось сделать, это включить его в основное дерево портов FreeBSD и осчастливить этим всех остальных. Нам не нужен ни каталог [.filename]#work#, ни пакет [.filename]#pkgname.tgz#, так что удалите их прямо сейчас.

Затем получите файл man:shar[1]. Предполагая, что порт называется oneko, перейдите в каталог выше, где находится каталог `oneko`, и наберите: `shar find oneko > oneko.shar`

Включите [.filename]#oneko.shar# в сообщение об ошибке и пошлите его с помощью man:send-pr[1]. Обратитесь к разделу extref:{contributing}[Сообщения об ошибках и общие замечания, CONTRIB-GENERAL] для получения подробной информации о man:send-pr[1]).

Укажите в сообщении категорию `ports` и класс `change-request`. _Не_ указывайте, что сообщение имеет статус `confidential`! Добавьте краткое описание программы в поле "Description" отправляемого PR (например, содержимое `COMMENT` в сокращённом варианте) и сам файл в виде архива [.filename]#.shar# в поле "Fix".

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

Повторим ещё раз, что __не нужно включать ни оригинальный файл с дистрибутивом, ни каталог [.filename]#work#, ни пакет, построенный вами командой ``make package``__; для новых портов используйте man:shar[1], но не man:diff[1].

После отправки порта, пожалуйста, потерпите. Время, необходимое для включения нового порта во FreeBSD, может занимать от нескольких дней до нескольких месяцев. http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports[ Здесь] можно увидеть список ожидающих PR для портов.

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