5.2. 名前の付け方

Port の Makefile のはじめの部分で port に名前をつけ、バージョン番号を記述し、適切なカテゴリに載せます。

5.2.1. PORTNAME および PORTVERSION

PORTNAME には port の名前の基幹部分を入れ、 PORTVERSION には port のバージョン番号を入れます。

5.2.2. PORTREVISION および PORTEPOCH

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. PORTREVISIONPORTEPOCH の使い方の例

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

PORTNAME=       gtkmumble
PORTVERSION=    0.10

PKGNAMEgtkmumble-0.10 になります。

ローカルな FreeBSD パッチを必要とする セキュリティホールが発見されました。 それに合わせて PORTREVISION を増やします。

PORTNAME=       gtkmumble
PORTVERSION=    0.10
PORTREVISION=   1

PKGNAMEgtkmumble-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

PKGNAMEgtkmumble-0.2,1 になります。

次のリリースは 0.3 です。 PORTEPOCH は減少することが無いため、 今度のバージョン変数は次のようになります:

PORTNAME=       gtkmumble
PORTVERSION=    0.3
PORTEPOCH=      1

PKGNAMEgtkmumble-0.3,1 になります。

注意: もし、このアップグレードによって PORTEPOCH0 に リセットされたとすると、3 は数字として 10 よりも小さいため、 gtkmumble-0.10_1 の package をインストールした誰かは gtkmumble-0.3 の package の方が新しいことに気がつかないことになるでしょう。 これが、そもそも PORTEPOCH が導入された肝心な理由です。

5.2.3. PKGNAMEPREFIX および PKGNAMESUFFIX

二つのオプション変数 PKGNAMEPREFIXPKGNAMESUFFIX は、 PORTNAME および PORTVERSION と結合され、 PKGNAME${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION} として定義します。 この時、適切な package 名を選ぶための ガイドラインに沿っているかどうかを確認してください。 特に、PORTVERSION 中に ハイフン (-) を使用することは禁止されています。 また、package 名に language- もしくは -compiled.specifics 部分が 含まれる場合、それぞれ PKGNAMEPREFIXPKGNAMESUFFIX を使用してください。 これらを PORTNAME の一部としてはいけません。

5.2.4. package 名についての規則

package の名前は以下のルールにしたがってつけてください。 これは package のディレクトリを見やすくするためで、 既に何千ものパッケージがありますし、 目を痛めてしまうようだとユーザはそっぽを向くでしょう。

package の名前は以下のようにしてください。 言語-名前-オプションバージョン.番号

package 名は ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION} というように定義されています。 変数がこの書式と適合していることを確認してください。

  1. FreeBSD はユーザの慣れ親しんだ言語のサポートに力を入れています。 特定の言語のための port の package 名には 言語- に ISO-639 で定義されている言語名の略称を入れてください。 たとえば日本語なら ja、 ロシア語なら ru、 ベトナム語なら vi、 中国語なら zh、 韓国語ならば ko、 ドイツ語なら de といった具合です。

    port がある言語地域に特化したものである場合には、 さらに二文字の国名コードを付加してください。 たとえば合衆国英語圏は en_US となり、 スイスのフランス語圏は fr_CH となります。

    言語- 部分は、 PKGNAMEPREFIX 変数に 定義されなければなりません。

  2. 名前の部分の最初の文字は 小文字でなければなりません。 (名前の残りの部分は大文字を含んでいても構わないため、 大文字を含んだソフトウェア名を変換する際の規則は、 あなた自身の裁量に任されています。) perl 5 のモジュールでは先頭に p5- を付け、 二重コロン (::) のセパレータをハイフン (-) に置きかえる習慣になっています。 たとえば Data::Dumperp5-Data-Dumper になります。 また、そのソフトウェアの名前として通常使われるものに番号、 ハイフン、あるいは下線が入っている場合には、 それらを使うことも構いません (kinput2など)。

  3. コンパイル時に環境変数や make の引数などでハードコードされたデフォルトを変えてコンパイルできる場合、 -compiled.specifics にそのコンパイル時のデフォルトを入れてください (ハイフンはあってもなくてもかまいません)。 用紙のサイズ、あるいはフォントの解像度などがこれにあたります。

    -compiled.specifics 部分は、 PKGNAMESUFFIX 変数に定義されなければなりません。

  4. バージョン番号は数字とアルファベットからなり、 ピリオド (.) で区切ります。 アルファベットは二文字以上続けてはいけません。 唯一の例外は``パッチレベル''を意味する文字列 pl で、 それ以外にバージョン番号がまったくついていない場合にのみ使うことができます。 もしソフトウェアのバージョンに ``alpha'', ``beta'', ``rc'' や ``pre'' といった文字列が含まれるなら、 ピリオドの後に最初の一文字をとってください。 これらの後に、さらにバージョン文字列が続く場合には、 一文字のアルファベットの後にピリオドをつけずに番号を続けます。

    この考え方は、 バージョン文字列を見て簡単に ports を並べられるようにするためのものです。 特に、バージョン番号の各部分が必ずピリオドで区切られていること、 また日付の部分がバージョン文字列の一部となっている場合には yyyy.mm.dd という書式を使っていることを確認してください。 dd.mm.yyyy や、2000 年問題に対応していない yy.mm.dd という書式を使ってはいけません。

では、DISTNAMEを正しい PKGNAME に直す例を見てみましょう:

以下は、ソフトウェアの作者が決めた名前から 適切な package 名に変換する方法を示した (実際の) 例です。

配布名 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 alpha のような文字列は使えない
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フォント用の package

オリジナルのソースにまったくバージョン情報が見当たらず、 また原作者が新しいバージョンをリリースする可能性が低いときには、 バージョン番号として 1.0 を使えばいいでしょう (上記の piewm の例がこれにあたります)。 そうでない場合には原作者に聞くか、日付 (yyyy.mm.dd) を使うなどしてください。

FreeBSD ports システムに関する質問は、(英語で) <ports@FreeBSD.org> へ、
この文書の原文に関するお問い合わせは、(英語で) <doc@FreeBSD.org> までお願いします。