В первой части Makefile порта ему даётся название, указывается его номер версии и принадлежность к правильной категории.
В переменной PORTNAME вы должны указать основную часть имени вашего порта, а в переменной PORTVERSION - номер версии.
Переменная PORTREVISION представляет собой монотонно увеличивающееся число, которое обнуляется при каждом увеличении значения переменной PORTVERSION (то есть каждый раз, когда создателями выпускается новый официальный релиз), и добавляется к имени пакета, если оно не равно нулю. Изменения в PORTREVISION используются автоматизированными инструментами (например, pkg_version(1)) для определения факта появления нового пакета.
Значение PORTREVISION должно увеличиваться каждый раз, когда в порте FreeBSD делаются изменения, которые достаточно сильно затрагивают содержимое или структуру соответствующего пакета.
Примеры случаев, когда значение PORTREVISION должно быть увеличено:
Добавление патчей для исправления уязвимостей, ошибок, или добавления новой функциональности в порт.
Изменения в файле Makefile порта для включения и выключения параметров, определяемых при компиляции пакета.
Изменения в списке упаковки или в поведении пакета во время его установки (например, изменение скрипта, генерирующего начальные данные для пакета, такие, как ssh-ключи для хоста).
Увеличение версии динамической библиотеки, от которой зависит порт (в этом случае тот, кто попытается установить старый пакет после установки более новой версии библиотеки, не сможет этого сделать, потому что при этом будет делаться поиск старой библиотеки libfoo.x, а не libfoo.(x+1)).
Большие функциональные изменения в дистрибутивном файле порта, происходящие без объявлений, и приводящие к большим изменениям, то есть изменения в дистрибутиве требуют корректировки файла distinfo без соответствующего изменения PORTVERSION, когда как команда diff -ru между новой и старой версиями показывает нетривиальные изменения в коде.
Примеры изменений, которые не требуют увеличения переменной PORTREVISION:
Изменения стиля в скелете порта без функциональных изменений в пакете.
Изменения в переменной MASTER_SITES или другие функциональные изменения порта, которые не затрагивают получающегося пакета.
Тривиальные патчи к дистрибутивному файлу, такие, как исправления опечаток, которые не так уж важны, что пользователи пакета должны озаботиться обновлением.
Исправления, касающиеся этапа построения, которые делают возможным построение пакета, если ранее это было невозможно сделать (пока изменения не приводят к изменению работы на любых других платформах, на которых порт ранее строился). Так как PORTREVISION отражает содержимое пакета, то, если ранее пакет не строился, то нет нужды увеличивать PORTREVISION для отметки изменения.
Правило, которому нужно приблизительно следовать, заключается в том, что нужно спрашивать себя, является ли вносимое в порт изменение таким, что от него выиграют все (в виде усовершенствования, исправления или благодаря тому, что новый пакет будет вообще работоспособным), и примите во внимание тот факт, что при этом все, кто регулярно обновляют своё дерево портов, будут обязаны это сделать. Если это так, то переменная PORTREVISION должна быть увеличена.
Время от времени разработчик программного обеспечения или создатель порта FreeBSD делают что-то не так и выпускают версию программы, номер которой меньше предыдущей версии. Примером этого является порт, название которого меняется с foo-20000801 на foo-1.0 (изначально это не считалось бы более новой версией, так как 20000801 численно больше, чем 1).
В ситуациях, подобных этой, должно быть увеличено значение PORTEPOCH. Если значение PORTEPOCH не равно нулю, то оно добавляется к имени пакета, как описано в разделе выше. Значение PORTEPOCH никогда не должно уменьшаться или сбрасываться в ноль, потому что это приведёт к ошибке сравнения с пакетом с меньшим номером эпохи (то есть то, что пакет устарел, обнаружено не будет): номер новой версии (например, 1.0,1 в примере выше) останется меньше, чем номер предыдущей версии (20000801), однако суффикс ,1 интерпретируется различными автоматизированными утилитами особым образом, и окажется больше, чем предполагаемый суффикс ,0 более раннего пакета).
Некорректное уменьшение или сброс PORTEPOCH приводит к печальным последствиям; если вы не поняли, о чём шла речь ранее, пожалуйста, всё же разберитесь с этим, либо спросите в списках рассылки.
Предполагается, что в большинстве портов переменная PORTEPOCH использоваться не будет, но при корректном использовании PORTVERSION может появиться необходимость её иметь, если в будущих релизах программное обеспечение должно изменить структуру номера версии. Однако создателям портов нужно быть внимательными, когда разработчик выпускает релиз без официального номера версии — эдакие ``промежуточные'' релизы. Имеется соблазн пометить релиз датой его выхода, что может вызвать проблемы, как и в примере выше, когда будет выпущен новый ``официальный'' релиз.
Например, если промежуточный релиз помечен датой 20000917, а предыдущая версия программного обеспечения имела номер 1.2, то промежуточному релизу должно быть поставлено в соответствие значение PORTVERSION, равное 1.2.20000917 или что-то похожее, но не 20000917, так как последующий релиз, скажем, 1.3, должен иметь численно большее значение.
Выполнен коммит порта gtkmumble, версии 0.10, в коллекцию портов.
PORTNAME= gtkmumble PORTVERSION= 0.10
Значение PKGNAME станет равным gtkmumble-0.10.
Обнаружена брешь в безопасности, исправление которой потребовало создания локального патча для FreeBSD. Соответственно было увеличено значение переменной PORTREVISION.
PORTNAME= gtkmumble PORTVERSION= 0.10 PORTREVISION= 1
PKGNAME принимает значение gtkmumble-0.10_1
Разработчиком выпущена новая версия с номером 0.2 (оказалось, что под номером 0.10 автор имел в виду 0.1.0, а не ``то, что будет выпущено после версии 0.9'' - извините, теперь уже поздно). Так как новый младший номер версии 2 по значению меньше, чем номер предыдущей версии 10, то должно быть увеличено значение PORTEPOCH для того, чтобы заставить распознавать вновь создаваемый пакет как ``более новый''. Так как это новый релиз программы, то PORTREVISION обнуляется (или удаляется из файла Makefile).
PORTNAME= gtkmumble PORTVERSION= 0.2 PORTEPOCH= 1
PKGNAME принимает значение gtkmumble-0.2,1
Следующий релиз имеет номер версии 0.3. Так как значение переменной PORTEPOCH никогда не уменьшается, что переменные, определяющие версии, теперь выглядят так:
PORTNAME= gtkmumble PORTVERSION= 0.3 PORTEPOCH= 1
PKGNAME принимает значение gtkmumble-0.3,1
Замечание: Если значение PORTEPOCH этим обновлением было бы сброшено в 0, то кто-нибудь, имеющий установленный пакет gtkmumble-0.10_1, не смог бы опознать пакет gtkmumble-0.3 как более новый, так как 3 было бы меньше, чем 10. Помните, что в первую очередь это касается PORTEPOCH.
Две необязательные переменные, PKGNAMEPREFIX и PKGNAMESUFFIX, объединяются со значениями PORTNAME и PORTVERSION для формирования PKGNAME в форме ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}. Добейтесь того, чтобы это соответствовало нашим рекомендациям по правильному выбору названий для пакетов. В частности, в переменной PORTVERSION не разрешается использование дефиса (-). Кроме того, если в имени пакета присутствует часть language- или -compiled.specifics (смотрите ниже), то используйте переменные PKGNAMEPREFIX и PKGNAMESUFFIX, соответственно. Не делайте их частью значения переменной PORTNAME.
LATEST_LINK задает в процессе построения пакета короткое имя ссылки, которые могут использоваться при выполнении команды pkg_add -r. Это позволяет, к примеру, установить последнюю версию perl, используя pkg_add -r perl, без знания точного номера версии. Такое имя должно быть уникальным и очевидным для пользователей.
В некоторых случаях в коллекции портов может присутствовать несколько версий программы одновременно. Обе системы, построения индексов и построения пакетов, нуждаются в способности их видеть как разные, независимые порты, хотя все они могут иметь схожее значение для PORTNAME, PKGNAMEPREFIX и даже PKGNAMESUFFIX. В этих случаях для всех портов кроме ``главного'' следует присвоить различные значения для необязательной переменной LATEST_LINK — чтобы получить пример ее использования, смотрите порты lang/gcc46 и lang/gcc, а также семейство www/apache*. При установке NO_LATEST_LINK ссылки не создаются; эта необязательная переменная может быть указана во всех версиях, кроме ``главной''. Обратите внимание, как выбирать ``главную'' версию — ``самую популярную'', ``самую поддерживаемую'', ``с наименьшими изменениями'' и так далее — это выходит за рамки рекомендаций этого руководства; мы всего лишь сообщаем вам, как указывать версии других портов после того, как вы выбрали ``главный''.
Далее описаны некоторые соглашения, которым вы должны следовать в именовании ваших пакетов. Они были разработаны для облегчения просмотра каталога, так как имеется уже тысячи пакетов, а пользователи отвернутся от нас, если список не понравится их взору!
Имя пакета должно иметь вид [language[_region]]-name[[-]compiled.specifics]-version.numbers.
Имя пакета определяется как ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}. Вы должны задавать значения переменных в соответствии с этим форматом.
FreeBSD пытается поддерживать языки, на которых разговаривают её пользователи. Часть language- должна быть двухсимвольным сокращением от названия языка по стандарту ISO-639, если порт специфичен для конкретного языка. Примерами являются ja для японского, ru для русского, vi для вьетнамского, zh для китайского, ko для корейского и de для немецкого языков.
Если ваш порт специфичен для конкретного региона внутри области использования языка, добавьте также двухсимвольный код страны. Примерами являются en_US для US English и fr_CH для Swiss French.
Часть language- должна задаваться в переменной PKGNAMEPREFIX.
Первая буква части name должна быть в нижнем регистре. (Оставшаяся часть названия может содержать буквы в верхнем регистре, так что принимайте решение сами, когда преобразуете имя программного пакета, содержащего в имени некоторое количество заглавных букв.) Существует традиция именовать модули для Perl 5, добавляя впереди p5- и преобразуя пару двоеточий в дефис; например, модуль Data::Dumper будет именоваться p5-Data-Dumper.
Убедитесь, что имя порта и версия четко отделены и размещаются в переменных PORTNAME и PORTVERSION. Единственная причина, по которой PORTNAME содержит версионную часть, это если полученный дистрибутив сам назван таким образом, как это сделано для портов textproc/libxml2 или japanese/kinput2-freewnn. В противном случае PORTNAME не должен содержать никакой информации, указывающей на версию. То, что некоторые порты имеют одинаковый PORTNAME, является вполне нормальным, как для портов www/apache*; в этом случае различные версии (и различные записи в индексе) отличаются по значениям PKGNAMEPREFIX, PKGNAMESUFFIX и LATEST_LINK.
Если порт может быть построен с различными статически заданными значениями по умолчанию (обычно это часть имени каталога в семействе портов), то часть -compiled.specifics должна определять вкомпилированные значения по умолчанию (дефис не обязателен). Примерами являются размеры бумаги и шрифтов.
Часть -compiled.specifics должна задаваться в переменной PKGNAMESUFFIX.
Строка с номером версии должна следовать за дефисом (-) и являться списком разделенных двоеточием чисел и букв в нижнем регистре. В частности, не разрешается иметь еще один дефис внутри строки с обозначением номера версии. Единственным исключением является строчка pl (означающая ``patchlevel''), которая может использоваться только тогда, когда у программного обеспечения нет старшего и младшего номера версии. Если в номер версии программного обеспечения включена строчка типа ``alpha'', ``beta'', ``rc'' или ``pre'', возьмите из неё первую букву и поставьте её непосредственно после точки. Если после таких строк номер версии ещё продолжается, то после буквы должно следовать число без дополнительной разделяющей точки.
Смысл такого формата заключается в удобстве сортировки портов по номеру версии. В частности, следите за тем, чтобы компоненты номера версии разделялись точкой, и если там присутствует дата, то используйте формат 0.0.yyyy.mm.dd, но не dd.mm.yyyy или не совместимый с проблемой Y2K yy.mm.dd. Добавление к версии префикса 0.0. является важным, в случае если выпущен релиз с присвоением настоящей версии, которая в числовом представлении, конечно же, будет ниже, чем yyyy.
Вот несколько (реальных) примеров того, как преобразовать имя из оригинального, придуманного авторами, к подходящему для имени пакета:
| Имя дистрибутива | PKGNAMEPREFIX | PORTNAME | PKGNAMESUFFIX | PORTVERSION | Обоснование |
|---|---|---|---|---|---|
| mule-2.2.2 | (пусто) | mule | (пусто) | 2.2.2 | Изменений не потребовалось |
| EmiClock-1.0.2 | (пусто) | emiclock | (пусто) | 1.0.2 | Для отдельных программ имена с заглавными буквами запрещены |
| rdist-1.3alpha | (пусто) | rdist | (пусто) | 1.3.a | Строчки типа alpha запрещены |
| es-0.9-beta1 | (пусто) | es | (пусто) | 0.9.b1 | Строчки типа beta запрещены |
| mailman-2.0rc3 | (пусто) | mailman | (пусто) | 2.0.r3 | Строчки типа rc запрещены |
| v3.3beta021.src | (пусто) | tiff | (пусто) | 3.3 | Что это такое было вообще? |
| tvtwm | (пусто) | tvtwm | (пусто) | pl11 | Всегда требуется указание номера версии |
| piewm | (пусто) | piewm | (пусто) | 1.0 | Всегда требуется указание номера версии |
| xvgr-2.10pl1 | (пусто) | xvgr | (пусто) | 2.10.1 | pl разрешено только при отсутствии старшего/младшего номера версии |
| gawk-2.15.6 | ja- | gawk | (пусто) | 2.15.6 | Версия на японском языке |
| psutils-1.13 | (пусто) | psutils | -letter | 1.13 | Размер бумаги задается статически во время построения пакета |
| pkfonts | (пусто) | pkfonts | 300 | 1.0 | пакет для шрифтов 300dpi |
Если в исходном коде абсолютно нет информации о номере версии и не похоже, что автор собирается выпускать другую версию, то в качестве номера версии задайте просто 1.0 (как в примере с piewm выше). В противном случае спросите автора программы или используйте дату (0.0.yyyy.mm.dd) в качестве номера версии.
| Пред. | Начало | След. |
| Настройка файла Makefile | Уровень выше | Разделение по категориям |