Переменная 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 в примере выше) останется меньше, чем номер предыдущей версии (2000801), однако суффикс ,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.
По вопросам связанным с системой
портов для FreeBSD, пишите по адресу <ports@freebsd.org>.
По вопросам связанным с этом документацией, пишите по адресу
<doc@freebsd.org>.