5.2. 名前の付け方

5.2.2.1. PORTREVISION

PORTREVISION 変数は単調増加する値です。 PORTVERSION が増加した時 (つまり、 新しいオフィシャルベンダーリリースが行なわれた時) には いつでも 0 にリセットされます。 また、その値が 0 でない場合には package 名に追加されます。 PORTREVISION の変更は、(例えば pkg_version(1) 等の) 自動化ツールが、 新たな package が入手できることを示すのに使われます。

その port から作られる package の内容や構造に 大きな影響を与える変更を行なった時には、 PORTREVISION を増やしてください。

PORTREVISION を上げる必要がある変更の例:

• セキュリティ上の脆弱性やバグを修正するため、または その port に新しい機能を追加するためのパッチの追加。

• package のコンパイル時オプションの有効化や 無効化のための port の Makefile の変更。

• パッキングリストの変更や、package のインストール時の 挙動の変更 (たとえば、ssh のホストキーのような package の 初期データを生成するスクリプトの変更など)。

• その port が依存する共有ライブラリのバージョンを 上げる場合 (新しいバージョンの共有ライブラリが インストールされた後に、そのライブラリに依存していた 古い package をインストールを試みる場合、 その package は新しい libfoo.(x+1) ではなく 古い libfoo.x を探そうとするため、インストールに失敗します。 (訳注: そのため、PORTREVISION を上げた package を 作成する必要があるわけです))。

• ひそかに port 配布ファイルの変更が行なわれ、 その機能に大きな変化があった場合。 つまり、distinfo の修正を 必要とするような配布ファイルの変更が行なわれ、 新旧のバージョンの diff -ru を取ると 些細とは言えない変更が認められるにもかかわらず、 オリジナルのバージョン番号が変更されていないことから PORTVERSION の変更は難しい場合。

PORTREVISION を上げる必要の無い変更の例:

• 生成される package に機能の変化が起らないような port スケルトンのスタイル変更。

• 生成される package に影響しないような MASTER_SITES その他の port に対する機能変更。

• 誤植の修正などの些細な変更で、その package のユーザが アップグレードを必要とするほどには重要でないパッチ。

• 以前にはコンパイルが通らなかった package を ビルド可能にするための修正 (その port が以前にビルド可能だった プラットフォームにおいて、その変更により何らかの機能的な 違いが発生しない場合に限ります)。 PORTREVISION は package の内容を反映したものなので、その package が以前にビルド可能でなかったのなら、変更を示すために、 PORTREVISION を 増やす必要はありません。

経験的な判断方法としては、ある port にコミットされた変更が (それが強化や修正によるものであれ、新しい package による 実質的な効能であれ)、アップデートすることにより、 誰もが利益を受けるような何かかどうか、また定期的に ports ツリーを更新している人に更新を強制するということに値するか自問してみることです。 もし答がイエスであれば、 PORTREVISION を上げるべきでしょう。

5.2.2.2. PORTEPOCH

ソフトウェアのベンダや FreeBSD の port 作成者は、 以前のものよりも小さい数字のバージョン番号をつけたソフトウェアをリリースするといった、 何か馬鹿げたことをすることが時々あります。 例をあげると、ある port が foo-20000801 から foo-1.0 になるといった具合です (数字として見ると 20000801 は 1 よりも大きいため、 間違って前者の方が新しいバージョンとして扱われてしまいます)。

このような場合には PORTEPOCH バージョンを増やしてください。 上のセクション 0 で説明したように、 PORTEPOCH がゼロでない場合には、 それがパッケージ名の後ろにつけられます。絶対に PORTEPOCH を減らしたり、ゼロにリセットしてはいけません。 さもないと、以前に作成された package との比較に失敗する (つまり、その package が古くなっていることがわからない) ためです: 新しいバージョン番号 (上の例では1.0,1) は 依然として前のバージョン番号 (20000801) よりも 数字としては小さいのですが、自動化ツールが サフィックス ,1 を特別扱いすることで、 以前の package には明示されていないサフィックス ,0 よりも新しいことがわかります。

誤って PORTEPOCH を削除したりリセットしたりすると、終わりのない悲劇に見舞われます。 上記の議論を理解できないなら、 わかるまで議論をたどるかメーリングリストで質問してください。

大多数の ports では、PORTEPOCH が 必要になることは まず無いものと考えられています。 また、注意深く PORTVERSION を使用することで、 そのソフトウェアの将来のリリースがバージョン構造を変更する必要が出てきた場合にも、 多くの場合前もって対応しておくことができるでしょう。 しかし、``スナップショット''リリースのように、 オフィシャルなバージョン番号を持たないベンダーリリースが行なわれた時には、 FreeBSD 版の port 作者によるケアが必要になります。 そういったリリースに対し、 リリース日付を使ったラベルを付けたいという誘惑にかられることがあるでしょうが、 そうすると新しい``オフィシャル''リリースが行なわれた時に、 上の例で示したような問題が起きることでしょう。

例えば、あるソフトウェアのスナップショットリリースが 20000917 に行なわれ、以前のバージョン番号が 1.2 だったとすると、 そのスナップショットの PORTVERSION には 20000917 ではなく 1.2.20000917 か何か、そのような番号を 指定するのが良いでしょう。 そうしておけば、例えばバージョン番号 1.3 として後続のリリースが 行なわれた場合にも、大小関係が崩されずにすむわけです。

5.2.2.3. PORTREVISION と PORTEPOCH の使い方の例

gtkmumble の port, バージョン 0.10 が ports collection にコミットされます。

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.9 の次という意味ではなく''、 実際には 0.1.0 のつもりで 使用していたことがわかります - あらら、今さら遅すぎる)。 新しいマイナーバージョン 2 は数字として以前のバージョン番号 10 より小さいので、 強制的に新しい package ``の方が新しい''と認識させるため PORTEPOCH を増やす必要があります。 これは新しいベンダーリリースなので、 PORTREVISION は 0 にリセット (または 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 になります。