# 章 3. 打造 Port 快速上手篇

This translation may be out of date. To help with the translations please access the FreeBSD translations instance.

本節主要介紹如何來快速打造 port，然而實際應用時這快速方法可能不足，完整的 "慢速打造 Port" 的步驟在 Slow Porting 詳述。

首先取得該應用程式的原始程式碼壓縮檔(tarball)，並把它放到 `DISTDIR`，預設路徑應該是 /usr/ports/distfiles.

| 這些步驟假設軟體可以直接編譯。也就是不需要任何修改就可以直接在 FreeBSD 上執行。如果需要修改，請參見Slow Porting。

| 在 porting 之前，建議在 /etc/make.conf 設定 `DEVELOPER` make(1) 變數。
    # echo DEVELOPER=yes >> /etc/make.conf
這個設定開啟了 "developer mode" ，顯示已棄用警告並在使用 `make` 時檢查品質。

## 3.1. 編寫 Makefile

最簡單的 Makefile 大概是像這樣：

    # $FreeBSD: head/zh_TW.UTF-8/books/porters-handbook/book.xml 48496 2016-03-29 01:37:53Z kevlo $

    PORTNAME=	oneko
    PORTVERSION=	1.1b
    CATEGORIES=	games
    MASTER_SITES=	ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/

    MAINTAINER=	youremail@example.com
    COMMENT=	Cat chasing a mouse all over the screen

    .include <bsd.port.mk>

嘗試了解此檔案，有關這點的細節部份，可以參閱 sample Makefile 章節。

## 3.2. 撰寫說明檔

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

### 3.2.1. pkg-descr

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

| 請注意，這檔_絕非_「該軟體的說明手冊」或是「如何編譯、使用該 port 的說明」！ 若是從該軟體的 README 或 manpage 直接複製過來的話，請注意。他們常常不是正確的 port 描述或是格式並不適合。例如，manpage會對齊空白，這用monospace字型來看會特別糟糕。 另一方面， pkg-descr 的內容必須比 COMMENT line from the Makefile 還要詳細，要能詳細解釋此 port 相關的內容。

一個良好的 pkg-descr 可以讓使用者清楚的了解軟體的功能而無須查詢文件或者訪問網站，提及特定的需求像是圖形工具、依賴、執行的環境跟實作的語言，能大大的幫助使用者了解這個 port 是怎麼運作的。

| 過去在 pkg-descr 文件最後一行引入的 URL 已經移到 Makefile 裡面了。

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

| `PLIST_FILES` 的使用不應該被濫用，人們通常透過在 ports tree 的 pkg-plist 文件來了解 port ，在 Makefile 中使用 `PLIST_FILES` 敘述會增加搜尋的難度。

| 如果 port 需要創建空的目錄，或者安裝時在 ${PREFIX} 之外創建目錄，請參考 Cleaning Up Empty Directories 來獲得更多資訊。

| 因為 `PLIST_FILES` 是 make(1) 的變數，任何在此條目的 sapce 都必須被引入。舉例來說，如果使用 pkg-create(8) 和 Expanding Package List with Keywords 描述的關鍵字，以下的條目必須被引入。
    PLIST_FILES=	"@sample ${ETCDIR}/oneko.conf.sample"

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

## 3.3. 產生 checksum 檔

只要打 `make makesum` 就好了， 接下來就會自動產生相對應的 distinfo 檔了唷 。

## 3.4. 測試 Port

接下來，必須檢驗是否有符合 port 的遊戲規則，包括打包該 port 為 package。 以下有幾個需要確認的重要地方：

- 若該 port 沒裝的東西，不要列在 pkg-plist 內。

- 若該 port 有裝的東西，請務必列在 pkg-plist 內。

- port 可以透過 `install` 來安裝，這可以確保安裝的 script 是正常運作的。

- port 可以透過 `uninstall` 來移除，這可以確保安裝的 script 是正常運作的。

- port 只有在 `featch` 目標時才能使用網路，這對 package builders 很重要，像是 ports-mgmt/poudriere.

- 確保 `make package` 可以被一般使用者執行 (也就是說，非 `root` 使用者)，如果上述執行失敗，軟體很可能需要修改，請參考 `fakeroot` 和 `uidfix`。

Procedure: 建議的測試順序

1. `make stage`

2. `make check-orphans`

3. `make package`

4. `make install`

5. `make deinstall`

6. `pkg add package-filename`

7. `make package` (as user)

確認在任何階段都沒有任何警告出現。

可以透過 ports-mgmt/tinderbox 或者 Ports Collection 的 ports-mgmt/poudriere 工具來完成自動化測試，參考 Poudriere 獲得更多的資訊。她維護 `jails` ，可以在不影響系統的情況下執行上述所有的測試。

## 3.5. 以 `portlint` 來作檢查 Port

請用 `portlint` 來檢查該 port 是否有遵循我們的規則。 ports-mgmt/portlint 是 ports collection 的其中一個套件。 它主要可以用來檢驗 Makefile 內容是否正確以及 package 是否有正確命名。

| 不要盲目的相信 `portlint` 的輸出，他是一個 static lint 工具，並且有可能會出錯。

## 3.6. 提交新的 Port

提交新的 Port 前，請閱讀 DOs and DON’Ts 章節。

現在你很高興終於打造出 port 來囉，唯一剩下要做的就是把它正式放到 FreeBSD ports tree 內，才能讓每個人都能分享使用這個 port。

| 我們不需要 work 目錄或是檔名像 pkgname.tgz 的 package ，請現在刪除他們。

下一步，創建一個 patch(1) ，一個文件，假設此 port 叫做 `oneko` 並且屬於 `games` 類別。

例 1. 為新的 Port 創建 .diff

透過 `git add .` 加入所有的檔案，然後透過 `git diff` 來檢查不同處，如下。

    % git add .
    % git diff --staged

確保所有需要的檔案都被引入了，將更改提交到你本地分支並使用 `git format-patch` 產生 patch。

    % git commit
    % git format-patch origin/main

使用 `git format-patch` 產生的 patch 會包含作者以及電子郵件，讓其他開發者更容易使用 (with `git am`) 以及給予回饋。

為了讓開發者更容易在他們的 ports tree 使用此 patch ，請基於你的 ports tree 來產生 .diff 。

透過 bug submission form 繳交 oneko.diff 。使用 "Ports & Packages" 產品和 "Individual Port(s)" 組件，然後跟著這裡的教學走，在 PR 的描述欄位 (也許是較短的 `COMMENT` ) 加入簡短的敘述，並且記得在附件中加入 oneko.diff 。

| 在問題回報系統中給一個好的總結可以讓 port 開發者更輕鬆的處理此 port ，我們預期的描述形式為 "[NEW PORT] category/portname short description of the port" ，使用此形式能讓我們更快的部屬新的 port 。

送出 port 之後，請耐心等候佳音。 有時候可能需要等個幾天或幾個月時間，才會在 FreeBSD ports tree 上正式出現。 等待中的 port PR 清單可以在 http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports 查閱。

在搜尋表單中選擇 Open and Ports & Packages 來獲得 open port PRs 的清單。

在看過新的 port 之後，如果需要的話，我們會回覆您，然後會將它提交到 port tree 。 您的大名會被列在 Additional FreeBSD Contributors 列表上，以及其他檔案中。

也可以透過 shar(1) 檔案來提交 port ，請使用之前 `oneko` port 的例子。

例 2. 為新的 Port 創建 .shar

前往 port 所在的目錄，使用 `tar`創建 shar archive:

    % cd ..
    % tar cf oneko.shar --format shar oneko

可以使用跟提交 oneko.diff 一樣的方式來提交 oneko.shar 。

最後修改於: March 9, 2024 由 Danilo G. Baio

Prev
Home
Next