12. FAQ по работе с портами

1. Добавление нового порта
12.1.1. Как добавить новый порт?
12.1.2. Что еще следует сделать, добавляя новый порт?
2. Удаление порта
12.2.1. Как удалить существующий порт?
3. Репозиторное копирование
12.3.1. Когда требуется репозиторное копирование?
12.3.2. Когда репозиторное копирование не требуется?
12.3.3. Что нужно делать?
4. Заморозка портов
12.4.1. Что такое ''заморозка портов''?
12.4.2. Сколько длится заморозка?
12.4.3. Что это значит для меня?
12.4.4. Откуда я узнаю о начале периода заморозки?
12.4.5. Как узнать, когда период заморозки портов закончился?
5. Создание новой категории
12.5.1. Какова процедура создания новой категории портов?
12.5.2. Как устроен процесс?
6. Прочие вопросы
12.6.1. Как мне проверить, что мой порт корректно собирается?
12.6.2. Я добавил новый порт. Нужно ли добавлять его в файл INDEX?
12.6.3. Какие еще файлы я не должен трогать?
12.6.4. Каков корректный порядок обновления порта, когда его исходный архив поменялся, но не сменил имя?

1. Добавление нового порта

12.1.1. Как добавить новый порт?

Для начала прочитайте раздел, посвященный репозиторному копированию.

Самым простым будет использовать скрипт addport на машине freefall. Он добавит порт из указанного вами каталоге, определив нужную категорию из файла Makefile, добавит строку в файл CVSROOT/modules и в файл Makefile для нужной категории. Скрипт был написан Michael Haro и Will Andrews ; вопросы и исправления по поводу addport следует отправлять Уиллу, как текущему мейнтейнеру.

12.1.2. Что еще следует сделать, добавляя новый порт?

Проверьте его. Желательно убедиться в том, что порт и соответствующий пакет корректно собираются. Рекомендуемая последовательность действий такова:

# make install
# make package
# make deinstall
# pkg_add имя собранного пакета
# make deinstall
# make reinstall
# make package
	   

Более подробные инструкции можно найти в Руководстве FreeBSD по созданию портов.

Пользуйтесь portlint(1) для проверки корректности порта. Не обязательно добиваться полного отсутствия предупреждений, но по крайней мере исправьте простейшие из них.

Если новый порт прислал человек, еще не упомянутый в Списке прочих участников, добавьте его имя туда.

Закройте PR, если новый порт пришел в виде PR. Для этого воспользуйтесь командой edit-pr PR# на машине freefall и измените значение в строке state с open на closed. Затем опишите причину смены статуса, и на этом работа закончена.

2. Удаление порта

12.2.1. Как удалить существующий порт?

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

  • Убедитесь, что другие порты не зависят от удаляемого:

    • Имя пакета (PKGNAME) должно встречаться в свежем файле INDEX ровно один раз.

    • В файлах Makefile* других портов не должно встречаться ни одной ссылки на каталог удаляемого порта или имя его пакета (PKGNAME).

  • Удалите порт:

    1. Удалите файлы порта командой cvs remove.

    2. Удалите строку SUBDIR для удаляемого порта из файла Makefile категории.

    3. Удалите запись для порта из файла модулей CVSROOT/modules.

    4. Добавьте соответствующую строку в файл ports/MOVED.

    5. Если порт упоминается в файле ports/LEGAL, удалите его оттуда.

Вы можете воспользоваться скриптом rmport из каталога ports/Tools/scripts. Этот скрипт написал Vasil Dimov , и он же его поддерживает, так что вопросы, исправления и замечания по поводу rmport следует посылать непосредственно ему.

3. Репозиторное копирование

12.3.1. Когда требуется репозиторное копирование?

При необходимости добавления порта, имеющего отношение к другому, уже находящемуся в репозитории в другом каталоге, необходимо произвести репозиторное копирование. В данном случае имеющий отношение означает другую версию или небольшую модификацию. Примерами могут служить различные версии print/ghostscript* и английская и локализованные версии x11-wm/windowmaker*.

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

12.3.2. Когда репозиторное копирование не требуется?

Если нет истории, которую стоило бы сохранять. Для порта, добавленного в неправильную категорию и сразу же перемещенного, будет вполне достаточно выполнить команды cvs remove для старого варианта и addport для нового.

12.3.3. Что нужно делать?

Создайте в GNATS PR, описав причины репозиторного копирования. Поменяйте ответственного на portmgr и установите статус (state) в состояние repocopy. Если ваш запрос будет одобрен группой Группа Менеджеров Дерева Портов FreeBSD , он будет переадресован на pcvs. Группа Менеджеров Дерева Портов FreeBSD может произвести копирование каталогов самостоятельно; в противном случае группа Администраторы Репозитория Портов произведет собственно копирование и вернет вам ваш PR. После этого, вам необходимо проделать следующее:

  • После репозиторного копирования порта:

    1. Обновите новый вариант порта до новой версии. Не забудьте изменить строку LATEST_LINK, чтобы не получить двух портов с одним именем. В некоторых исключительных случаях может быть необходимо изменить переменную PORTNAME вместо LATEST_LINK, но это должно быть сделано только тогда когда это действительно нужно. Например, при использовании существующего порта в качестве основы для весьма похожей программы с другим именем или при обновлении порта до новой основной версии программы, при котором изменяется имя самого дистрибутива, как в случае перехода с textproc/libxml на textproc/libxml2. В большинстве случаев изменение LATEST_LINK должно быть достаточно.

    2. Добавьте новый каталог в список SUBDIR в родительском файле Makefile. Для проверки вы можете воспользоваться командой make checksubdirs.

    3. Если порт менял категорию, измените строку CATEGORIES в файле Makefile.

    4. Добавьте строку для нового модуля в CVSROOT/modules.

    5. Добавьте строку в файл ports/MOVED, в случае если вы удалили первоначальный порт.

  • При удалении порта:

    1. Тщательно проверьте коллекцию на предмет портов, зависящих от удаляемого и обновите их при необходимости. Выполнение команды grep по содержимому файла INDEX недостаточно, поскольку некоторые порты могут быть сконфигурированы на этапе сборки. Рекомендуется использовать полный поиск при помощи команды grep -r.

    2. Удалите старый порт, запись SUBDIR и строку, описывающую модуль.

    3. Добавьте строку в файл ports/MOVED.

  • После репозиторного перемещения (операции ''переименования'', когда после копирования старый вариант удаляется):

    1. Используйте процедуры из предыдущих двух пунктов для активации нового порта и удаления старого.

4. Заморозка портов

12.4.1. Что такое ''заморозка портов''?

Перед выпуском релиза для сохранения целостности различных частей системы требуется на некоторое время ограничить коммиты в дерево портов. Этот процесс и называется ''заморозкой портов''.

За дополнительной информацией по поводу правил поведения во время заморозки обращайтесь к документу Задачи контроля качества для Группы управления портами.

12.4.2. Сколько длится заморозка?

Обычно неделю или две.

12.4.3. Что это значит для меня?

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

В период заморозки не все изменения могут быть внесены в дерево. За подробностями обращайтесь к документу Задачи контроля качества для Группы управления портами.

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

12.4.4. Откуда я узнаю о начале периода заморозки?

Обычно за 2-3 недели до начала периода заморозки кто-либо из группы порт-менеджеров посылает письмо с предупреждением об этом в Список рассылки, посвящённый Портам FreeBSD и Список рассылки коммиттеров FreeBSD. Точное время начала периода заморозки определяется за несколько дней до собственно релиза, поскольку фиксируемое дерево портов должно быть синхронизировано с релизом, а точная дата выпуска определяется по ходу дела.

Разумеется, после начала периода заморозки в Список рассылки коммиттеров FreeBSD будет отправлено еще одно предупреждение.

12.4.5. Как узнать, когда период заморозки портов закончился?

Завершение периода заморозки анонсируется группой порт-менеджеров посылкой письма в Список рассылки, посвящённый Портам FreeBSD и Список рассылки коммиттеров FreeBSD через несколько часов после релиза. Отметим, что факт выпуска релиза не означает автоматического завершения заморозки. Нам потребуется убедиться, что в последние минуты не произошло ничего непредвиденного, что заставило бы перевыпускать релиз.

5. Создание новой категории

12.5.1. Какова процедура создания новой категории портов?

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

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

Обратитесь к разделу Proposing a New Category Руководства по созданию портов. После передачи PR группе Группа Менеджеров Дерева Портов FreeBSD решение о создании категории остается за ней. В случае утверждения новой категории кто-либо из Группа Менеджеров Дерева Портов FreeBSD делает следующее:

  1. Производит нужные репозиторные копирования.

  2. Обновляет определения VALID_CATEGORIES в файле ports/Mk/bsd.port.mk.

  3. Возвращает PR вам.

12.5.2. Как устроен процесс?

Процедура является надстройкой над уже описанной процедурой репозиторного копирования отдельного порта.

  1. Обновите файлы Makefile для всех перенесенных портов. Пока не добавляйте новую категорию в процесс построения индекса.

    Для этого вам необходимо:

    1. Сменить для всех портов значение переменной CATEGORIES (это и было нашей целью, не правда ли?) Новая категория должна быть указано в списке первой, это поможет проверить, правильно ли установлена переменная PKGORIGIN.

    2. Выполните команду make describe. Поскольку процедура построения главного индекса make index, которую вам предстоит выполнить несколько позже, использует именно make describe, обнаружение ошибок сейчас сэкономит вам немало времени в будущем.

    3. Если вы хотите быть совсем честным, самое время запустить portlint(1).

  2. Проверьте корректность переменных PKGORIGIN. Система работы с портами использует значение переменной CATEGORIES для установки переменной PKGORIGIN, которая затем используется для связи установленных пакетов с каталогами дерева портов. Если эта связь установлена неправильно, перестанут правильно функционировать утилиты работы с портами, такие как pkg_version(1) и portupgrade(1).

    Для проверки следует использовать скрипт chkorigin.sh: env PORTSDIR=/path/to/ports sh -e /path/to/ports/Tools/scripts/chkorigin.sh . Эта команда проверит каждый порт в дереве, в том числе и те, что не включены в процесс сборки, так что ее можно использовать сразу после репозиторного копирования. Совет: не забудьте проверить PKGORIGIN для зависимых от изменяемых вами портов!

  3. Протестируйте изменения локально, на вашей машине: закомментируйте строки SUBDIR для старых портов, затем разрешите обработку новой категории в файле ports/Makefile. Запустите make checksubdirs в затрагиваемых категориях. Наконец, выполните в каталоге ports/ команду make index. Ее выполнение может занять до 40 минут даже на современной машине, однако, это необходимые затраты для того, чтобы не создать проблем для других.

  4. После завершения этой операции вы можете вносить в репозиторий изменения ports/Makefile для включения новой категории в процесс сборки, а также производить коммит изменений Makefile для старых категорий.

  5. Добавьте в файл CVSROOT-ports/modules строку

    ports_categoryname   categoryname
    


    Поля должны быть разделены табуляцией.

    Если categoryname содержит дефисы, замените их на подчеркивания.

  6. Поменяйте строки для затронутых модулей в файле CVSROOT-ports/modules.

  7. Добавьте нужные строки в файл ports/MOVED.

  8. Обновите инструкции для cvsup(1):

    • Добавьте категорию в файл distrib/cvsup/sup/README

    • Добавьте в каталог distrib/cvsup/sup/ports-categoryname два файла: list.cvs и releases.

    • Добавьте категорию в файл src/share/examples/cvsup/ports-supfile

    (Обратите внимание: эти файлы расположены в репозитории src, а не ports). Если вы не являетесь коммиттером src, вам потребуется создать PR.

  9. Обновите список категорий, используемый в sysinstall(8) в src/usr.sbin/sysinstall.

  10. Обновите документацию:

    (Внимание: все эти файлы находятся в репозитории документации. Если вы не являетесь коммиттером в этой области, создайте PR в категории документации (doc).

  11. Старые варианты портов могут быть удалены из репозитория только после того, как все описанные процедуры будут завершены, и никто не жалуется на новую структуру.

Специально обновлять веб-страницу портов при добавлении новой категории не нужно: изменение файла www/en/ports/categories будет учтено при ежедневной перестройке списка портов (INDEX) автоматически.

6. Прочие вопросы

12.6.1. Как мне проверить, что мой порт корректно собирается?

В первую очередь проверьте свой порт по адресу http://pointyhat.FreeBSD.org/errorlogs/. Там вы найдете журналы сборки пакетов на всех поддерживаемых архитектурах для большинства последних ветвей разработки.

Впрочем, отсутствие вашего порта среди журналов с ошибками еще не значит, что он успешно собирается (например, может не собираться один из зависимых портов). Необходимую информацию вы можете найти на машине pointyhat в каталогах /a/portbuild/<arch>/<major_version>. Каждая пара архитектуры и базовой версии содержит следующие подкаталоги:

errors        журналы ошибок последней сборки версии <major_version> на платформе <arch>
logs          все журналы последней сборки версии <major_version> на платформе <arch>
packages      свежесобранные пакеты для версии <major_version> на платформе <arch>
bak/errors    журналы ошибок последней полной сборки версии <major_version> на платформе <arch>
bak/logs      все журналы последней полной сборки версии <major_version> на платформе <arch>
bak/packages  пакеты последней полной сборки версии <major_version> на платформе <arch>

Общее правило: пакет, присутствующий в каталоге packages или каталоге logs, и при этом отсутствующий в errors, собрался успешно. (Именно каталоги errors вы видите на веб-сервере pointyhat).

12.6.2. Я добавил новый порт. Нужно ли добавлять его в файл INDEX?

Нет. INDEX больше не хранится в CVS репозитории. Данный файл может быть сгенерирован с помощью команды make index или уже сгенерированная версия может быть загружена с помощью make fetchindex.

12.6.3. Какие еще файлы я не должен трогать?

Любой файл в на верхнем уровне ports/, а также все файлы в каталогах, имена которых начинаются с прописной буквы (например, Mk/, Tools/ и т.п.). В частности, упаси вас Бог трогать файлы ports/Mk/bsd.port*.mk, если вы не хотите привести порт-менеджеров в ярость!

12.6.4. Каков корректный порядок обновления порта, когда его исходный архив поменялся, но не сменил имя?

При возникновении ситуации, когда автор обновляет дистрибутивный архив без изменения идентификатора версии, сообщение о коммите должно содержать аннотацию различий между предыдущим и обновленным состоянием архива, чтобы можно было убедиться, что архив не испорчен и не подменен злоумышленником. Если текущая версия порта существовала достаточное время, копии архива будут доступны на ftp-серверах проекта; в противном случае следует связаться с автором или мейнтейнером порта для выяснения причин замены архива.

Этот, и другие документы, могут быть скачаны с ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

По вопросам, связанным с FreeBSD, прочитайте документацию прежде чем писать в <questions@FreeBSD.org>.
По вопросам, связанным с этой документацией, пишите <doc@FreeBSD.org>.
По вопросам, связанным с русским переводом документации, пишите в рассылку <frdp@FreeBSD.org.ua>.
Информация по подписке на эту рассылку находится на сайте проекта перевода.