章 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

Home