FreeBSD Porter's Handbook
前一頁 | 章 3. 打造 Port 快速上手篇 | 下一頁

# 3.2. 撰寫該軟體的說明檔

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

## 3.2.1. `pkg-descr`

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

> 注: 請注意，這檔絕非「該軟體的說明手冊」或是「如何編譯、使用該 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 的話，則要以類似 `MAN`n`=` 的方式寫在 `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) 會有詳解 。

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

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

只有在一種情況下可以省略不用生 `pkg-plist` 檔： 若安裝的 port 相當單純，只有裝一些檔案， 以及都在同一目錄下的話，那麼可以在 `Makefile` 內改用 `PLIST_FILES` 及 `PLIST_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_FILES`、 `PLIST_DIRS` 是必須付出代價： 不能使用 pkg_create(1) 內所說的 command sequences。 因此，這招僅適用於較簡單的 port ，以及簡化該 port 的作法。 此外，這招還有一個好處：可以減少 ports collection 的整體檔案總數。 所以，在考慮是否一定要用 `pkg-plist` 之前， 可以先斟酌這個替代方案看看。

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

前一頁 | 內容 | 下一頁
打造 Port 快速上手篇 | 上一層 | 產生 checksum 用途的 distinfo 檔

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