# echo DEVELOPER=yes >> /etc/make.conf
章 3. 打造 Port 快速上手篇
目錄
本節主要介紹如何來快速打造 port,然而實際應用時這快速方法可能不足,完整的 "慢速打造 Port" 的步驟在 Slow Porting 詳述。
首先取得該應用程式的原始程式碼壓縮檔(tarball),並把它放到 DISTDIR
,預設路徑應該是 /usr/ports/distfiles.
這些步驟假設軟體可以直接編譯。也就是不需要任何修改就可以直接在 FreeBSD 上執行。如果需要修改,請參見Slow Porting。 |
在 porting 之前,建議在 /etc/make.conf 設定 這個設定開啟了 "developer mode" ,顯示已棄用警告並在使用 |
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
|
如果 port 需要創建空的目錄,或者安裝時在 ${PREFIX} 之外創建目錄,請參考 Cleaning Up Empty Directories 來獲得更多資訊。 |
因為 PLIST_FILES= "@sample ${ETCDIR}/oneko.conf.sample" |
後面會介紹到如何運用 pkg-plist、 PLIST_FILES
這些技巧以因應更複雜的狀況。
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: 建議的測試順序
make stage
make check-orphans
make package
make install
make deinstall
pkg add package-filename
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 是否有正確命名。
不要盲目的相信 |
3.6. 提交新的 Port
提交新的 Port 前,請閱讀 DOs and DON’Ts 章節。
現在你很高興終於打造出 port 來囉,唯一剩下要做的就是把它正式放到 FreeBSD ports tree 內,才能讓每個人都能分享使用這個 port。
我們不需要 work 目錄或是檔名像 pkgname.tgz 的 package ,請現在刪除他們。 |
下一步,創建一個 patch(1) ,一個文件,假設此 port 叫做 oneko
並且屬於 games
類別。
透過 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
) 以及給予回饋。
透過 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 的例子。
前往 port 所在的目錄,使用 `tar`創建 shar archive:
% cd ..
% tar cf oneko.shar --format shar oneko
可以使用跟提交 oneko.diff 一樣的方式來提交 oneko.shar 。
最後修改於: February 10, 2023 由 Wang Yan Hao