3.2 撰寫該軟體的說明檔

無論是否打算再加工做成 package,有 2 個檔案是任何實體 port (Slave port則不一定)都必須要具備的。 這 2 個檔分別是 pkg-descr 檔及 pkg-plist 檔。 這兩個檔案檔名前面都有 pkg- 以跟其他檔案做區別。

3.2.1 pkg-descr

這是此 port 的詳細說明檔,請用一段或幾段文字來說明該 port 的作用,並附上 WWW 網址(若有的話)。

Note: 請注意,這檔絕非「該軟體的說明手冊」或是「如何編譯、使用該 port 的說明」。 若是從該軟體的 README 或 manpage 直接複製過來的話,請注意,因為它們通常都寫得太詳細、 格式較特別(比如 manpage 會自動調整空白), 請儘量避免這些冗長贅詞或採用特殊格式。若該軟體有官方版首頁的話, 請在此列出來。 每個網址請用 WWW: 作為開頭, 這樣子相關工具程式就會自動處理完畢。

該 port 的 pkg-descr 內容,大致如下面例子 :

This is a port of oneko, in which a cat chases a poor mouse all over
the screen.
 :
(etc.)

WWW: http://www.oneko.org/

3.2.2 pkg-plist

這是該 port 所會裝的所有檔案清單,另外因為 package 會由這清單所產生,因此也被稱為『packing list (打包清單)』。 以 ${PREFIX} 為基準點, 而用相對路徑表示。(${PREFIX} 通常是 /usr/local/usr/X11R6) 但是如果該程式有安裝 man page 的話,則要以類似 MANn= 的方式寫在 Makefile 內,不能列在 pkg-plist 哦。 除了列出檔案以外,也要把該 port 所會建立的目錄也列進去, 方式有兩種:一種是寫在 pkg-plist 內的方式, 比如:@dirrm。 至於另外一種方式,則是寫在 Makefile 內,比如: PLIST_FILES= 之類的方式。

該 port 的 pkg-plist 內容, 大致如下面例子:

bin/oneko
lib/X11/app-defaults/Oneko
lib/X11/oneko/cat1.xpm
lib/X11/oneko/cat2.xpm
lib/X11/oneko/mouse.xpm
@dirrm lib/X11/oneko

關於 packing list 方面,可以參閱 pkg_create(1) 會有詳解 。

Note: 建議清單內的檔名,依照字母順序作排序,那麼下次要升級時, 會比較清楚、方便來更新這份清單。

Note: 手動生這份清單實在太苦了。尤其若該 port 會裝一大堆檔案的話, 請多善用 自動產生 packing list 會比較省時省力唷。

只有在一種情況下可以省略不用生 pkg-plist 檔: 若安裝的 port 相當單純,只有裝一些檔案, 以及都在同一目錄下的話,那麼可以在 Makefile 內改用 PLIST_FILESPLIST_DIRS 來取代。 比如,可以在上述的 oneko port 內不必附上 pkg-plist ,而只需在 Makefile 內加入下列幾行:

PLIST_FILES=    bin/oneko \
                lib/X11/app-defaults/Oneko \
                lib/X11/oneko/cat1.xpm \
                lib/X11/oneko/cat2.xpm \
                lib/X11/oneko/mouse.xpm
PLIST_DIRS=     lib/X11/oneko

當然,若該 port 並無安裝自屬的目錄的話,就不必設 PLIST_DIRS 囉。

然而,使用 PLIST_FILESPLIST_DIRS 是必須付出代價: 不能使用 pkg_create(1) 內所說的 command sequences。 因此,這招僅適用於較簡單的 port ,以及簡化該 port 的作法。 此外,這招還有一個好處:可以減少 ports collection 的整體檔案總數。 所以,在考慮是否一定要用 pkg-plist 之前, 可以先斟酌這個替代方案看看。

後面會介紹到如何運用 pkg-plistPLIST_FILES 這些技巧以因應 更複雜的狀況

For questions about the FreeBSD ports system, e-mail <ports@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.