В первой части Makefile порта ему даётся название, указывается его номер версии и принадлежность к правильной категории.
В переменной PORTNAME вы должны указать основную часть имени вашего порта, а в переменной PORTVERSION - номер версии.
Переменная PORTREVISION представляет собой монотонно увеличивающееся число, которое обнуляется при каждом увеличении значения переменной PORTVERSION (то есть каждый раз, когда создателями выпускается новый официальный релиз), и добавляется к имени пакаджа, если оно не равно нулю. Значение PORTREVISION увеличивается каждый раз, когда в порте FreeBSD делаются изменения, которые достаточно сильно затрагивают содержимое или структуру соответствующего пакаджа.
Примеры случаев, когда значение PORTREVISION должно быть увеличено:
Добавление патчей для исправления пробелов в безопасности, ошибок, или добавления новой функциональности в порт FreeBSD.
Изменения в файле построения порта для включения и выключения параметров, определяемых при компиляции пакаджа.
Изменения в списке упаковки или в поведении пакаджа во время его установки (например, изменение скрипта, генерирующего начальные данные для пакаджа, такие, как ssh-ключи для хоста).
Увеличение версии динамической библиотеки, от которой зависит порт (в этом случае тот, кто попытается установить старый пакадж после установки более новой версии библиотеки, не сможет этого сделать, потому что при этом будет делаться поиск старой библиотеки libfoo.x, а не libfoo.(x+1)).
Большие функциональные изменения в дистрибутивном файле порта, происходящие без объявлений, и приводящие к большим изменениям, то есть изменения в дистрибутиве требуют корректировки файла distinfo без соответствующего изменения PORTVERSION, когда как команда diff -ru между новой и старой версиями показывает нетривиальные изменения в коде.
Примеры изменений, которые не требуют увеличения переменной PORTREVISION:
Изменения стиля в скелете порта без функциональных изменений в пакадже.
Изменения в переменной MASTER_SITES или другие функциональные изменения порта, которые не затрагивают получающегося пакаджа.
Тривиальные патчи к дистрибутивному файлу, такие, как исправления опечаток, которые не так уж важны, что пользователи пакаджа должны озаботиться обновлением.
Исправления, касающиеся этапа построения, которые делают возможным построение пакаджа, если ранее это было невозможно сделать (пока изменения не приводят к изменению работы на любых других платформах, на которых порт ранее строился). Так как PORTREVISION отражает содержимое пакаджа, то если ранее пакадж не строился, то нет нужды увеличивать PORTREVISION для отметки изменения.
Правило, которому нужно приблизительно следовать, заключается в том, что нужно спрашивать себя, является ли вносимое в порт изменение таким, что кто-либо и где-либо от него выиграет (в виде усовершенствования, исправления или благодаря тому, что новый пакадж будет реально работать). Если это так, то переменная PORTREVISION должна быть увеличена, чтобы автоматизированные инструменты (например, pkg_version) смогли обнаружить факт появления нового пакаджа.
Время от времени разработчик программного обеспечения или создатель порта FreeBSD делают что-то не так и выпускают версию программы, номер которой меньше предыдущей версии. Примером этого является порт, название которого меняется с foo-20000801 на foo-1.0 (изначально это не считалось бы более новой версией, так как 20000801 численно больше, чем 1).
В ситуациях, подобных этой, должно быть увеличено значение PORTEPOCH. Если значение PORTEPOCH не равно нулю, то оно добавляется к имени пакаджа, как описано в разделе выше. Значение PORTEPOCH никогда не уменьшается и не сбрасывается в ноль, потому что это приведёт к ошибке сравнения с пакаджем с меньшим номером эпохи (то есть то, что пакадж устарел, обнаружено не будет): номер новой версии (например, 1.0,1 в примере выше) останется меньше, чем номер предыдущей версии (20000801), однако суффикс ,1 интерпретируется различными автоматизированными утилитами особым образом, и окажется больше, чем предполагаемый суффикс ,0 более раннего пакаджа).
Предполагается, что в большинстве портов переменная 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 обнуляется (или удаляется из make-файла).
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
Note: Если значение PORTEPOCH этим обновлением было бы сброшено в 0, то кто-нибудь, имеющий установленный пакадж gtkmumble-0.10_1, не смог бы распознать пакадж gtkmumble-0.3 как более новый, так как 3 было бы меньше, чем 10.
Две необязательные переменные, PKGNAMEPREFIX и PKGNAMESUFFIX, объединяются со значениями PORTNAME и PORTVERSION для формирования PKGNAME в форме ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}. Добейтесь того, чтобы это соответствовало нашим рекомендациям по правильному выбору названий для пакаджей. В частности, в переменной PORTVERSION не разрешается использование дефиса (-). Кроме того, если в имени пакаджа присутствует часть language- или compiled.specifics, то используйте переменные PKGNAMEPREFIX и PKGNAMESUFFIX, соответственно. Не делайте их частью значения переменной PORTNAME.
Далее описаны некоторые соглашения, которым вы должны следовать в именовании ваших пакаджей. Они были разработаны для облегчения просмотра каталога, так как пакаджей уже имеется достаточно много и ещё больше их появляется, а пользователи отвернутся от нас, если список не понравится их взору!
Имя пакаджа должно иметь вид [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. Если программное обеспечение содержит в имени числа, дефисы или подчеркивания, то вы можете включить также и их (например, kinput2).
Если порт может быть построен с различными статически заданными значениями по умолчанию (обычно это часть имени каталога в семействе портов), то часть -compiled.specifics должна определять вкомпилированные значения по умолчанию (дефис не обязателен). Примерами являются размеры бумаги и шрифтов.
Часть compiled.specifics должна задаваться в переменной PKGNAMESUFFIX.
Строка с номером версии должна следовать за дефисом (-) и являться списком разделенных двоеточием чисел и букв в нижнем регистре. В частности, не разрешается иметь еще один дефис внутри строки с обозначением номера версии. Единственным исключением является строчка pl (означающая ``patchlevel''), которая может использоваться только тогда, когда у программного обеспечения нет старшего и младшего номера версии. Если в номер версии программного обеспечения включена строчка типа ``alpha'', ``beta'', ``rc'' или ``pre'', возьмите из неё первую букву и поставьте её непосредственно после точки. Если после таких строк номер версии ещё продолжается, то после буквы должно следовать число без дополнительной разделяющей точки.
Смысл такого формата заключается в удобстве сортировки портов по номеру версии. В частности, следите за тем, чтобы компоненты номера версии разделялись точкой, и если там присутствует дата, то используйте формат yyyy.mm.dd, но не dd.mm.yyyy или не совместимый с проблемой Г2000 yy.mm.dd.
Вот несколько (реальных) примеров того, как преобразовать имя из оригинального, придуманного авторами, к подходящему для имени пакаджа:
| Имя дистрибутива | PKGNAMEPREFIX | PORTNAME | PKGNAMESUFFIX | PORTVERSION | Обоснование |
|---|---|---|---|---|---|
| mule-2.2.2 | (пусто) | mule | (пусто) | 2.2.2 | Изменений не потребовалось |
| XFree86-3.3.6 | (пусто) | XFree86 | (пусто) | 3.3.6 | Изменений не потребовалось |
| 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 выше). В противном случае спросите автора программы или используйте дату (yyyy.mm.dd) в качестве номера версии.