3.2. 撰寫說明檔

無論是否打算再加工做成 package,有兩個檔案是任何 port 都必須要具備的。 這兩個檔分別是 pkg-descrpkg-plist 。 他們檔名前面都有 pkg- 以跟其他檔案做區別。

3.2.1. pkg-descr

這是此 port 的詳細說明檔,請用一段或幾段文字來說明該 port 的作用

注意:

請注意,這檔絕非「該軟體的說明手冊」或是「如何編譯、使用該 port 的說明」! 若是從該軟體的 README 或 manpage 直接複製過來的話,請注意。他們常常不是正確的 port 描述或是格式並不適合。例如,manpage會對齊空白,這用monospace字型來看會特別糟糕。

A well-written pkg-descr describes the port completely enough that users would not have to consult the documentation or visit the website to understand what the software does, how it can be useful, or what particularly nice features it has. Mentioning certain requirements like a graphical toolkit, heavy dependencies, runtime environment, or implementation languages help users decide whether this port will work for them.

Include a URL to the official WWW homepage. Prepend one of the websites (pick the most common one) with WWW: (followed by single space) so that automated tools will work correctly. If the URI is the root of the website or directory, it must be terminated with a slash.

注意:

If the listed webpage for a port is not available, try to search the Internet first to see if the official site moved, was renamed, or is hosted elsewhere.

這是 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 (通常是 /usr/local )。

這是一個簡單的例子:

bin/oneko
man/man1/oneko.1.gz
lib/X11/app-defaults/Oneko
lib/X11/oneko/cat1.xpm
lib/X11/oneko/cat2.xpm
lib/X11/oneko/mouse.xpm

關於 packing list 方面,可以詳閱 pkg-create(8) manual page 。

注意:

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

提示:

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

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

PLIST_FILES=	bin/oneko \
		man/man1/oneko.1.gz \
		lib/X11/app-defaults/Oneko \
		lib/X11/oneko/cat1.xpm \
		lib/X11/oneko/cat2.xpm \
		lib/X11/oneko/mouse.xpm

注意:

Usage of PLIST_FILES should not be abused. When looking for the origin of a file, people usually try to grep through the pkg-plist files in the ports tree. Listing files in PLIST_FILES in the Makefile makes that search more difficult.

提示:

If a port needs to create an empty directory, or creates directories outside of ${PREFIX} during installation, refer to 節 7.2.1, “Cleaning Up Empty Directories” for more information.

然而,使用這個方法列出 port 的檔案和目錄是必須付出代價: 不能使用 pkg-create(8)節 7.6, “Expanding Package List with Keywords” 描述的關鍵字。 因此,這招僅適用於較簡單的 port ,以及簡化該 port 的作法。 此外,這招還有一個好處:可以減少 ports collection 的整體檔案總數。 所以,在考慮是否要用 pkg-plist 之前, 可以先斟酌這個替代方案看看。

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

本文及其他文件,可由此下載: ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/

若有 FreeBSD 方面疑問,請先閱讀 FreeBSD 相關文件,如不能解決的話,再洽詢 <questions@FreeBSD.org>。

關於本文件的問題,請洽詢 <doc@FreeBSD.org>。