From owner-svn-doc-all@freebsd.org Tue Mar 29 01:37:54 2016 Return-Path: Delivered-To: svn-doc-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id D3E97AE1489; Tue, 29 Mar 2016 01:37:54 +0000 (UTC) (envelope-from kevlo@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 7CFBC15B4; Tue, 29 Mar 2016 01:37:54 +0000 (UTC) (envelope-from kevlo@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id u2T1bru1001510; Tue, 29 Mar 2016 01:37:53 GMT (envelope-from kevlo@FreeBSD.org) Received: (from kevlo@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id u2T1brrn001508; Tue, 29 Mar 2016 01:37:53 GMT (envelope-from kevlo@FreeBSD.org) Message-Id: <201603290137.u2T1brrn001508@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: kevlo set sender to kevlo@FreeBSD.org using -f From: Kevin Lo Date: Tue, 29 Mar 2016 01:37:53 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r48496 - head/zh_TW.UTF-8/books/porters-handbook X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 29 Mar 2016 01:37:54 -0000 Author: kevlo (src,ports committer) Date: Tue Mar 29 01:37:53 2016 New Revision: 48496 URL: https://svnweb.freebsd.org/changeset/doc/48496 Log: Push recent translations. Submitted by: https://reviews.freebsd.org/D5570 Reviewed by: wblock Differential Revision: https://reviews.freebsd.org/D5570 Added: head/zh_TW.UTF-8/books/porters-handbook/zh_TW.po (contents, props changed) Modified: head/zh_TW.UTF-8/books/porters-handbook/book.xml Modified: head/zh_TW.UTF-8/books/porters-handbook/book.xml ============================================================================== --- head/zh_TW.UTF-8/books/porters-handbook/book.xml Mon Mar 28 21:34:21 2016 (r48495) +++ head/zh_TW.UTF-8/books/porters-handbook/book.xml Tue Mar 29 01:37:53 2016 (r48496) @@ -1,1225 +1,1513 @@ - + + - - FreeBSD Porter's Handbook - +--> + + + + + + + + + + + + + + + + +]> + + + + FreeBSD Porter 手冊 - FreeBSD 文件計劃 + The FreeBSD Documentation Project - April 2000 + $FreeBSD$ - - 2000 - 2001 - 2002 - 2003 - 2004 - 2005 - 2006 - 2007 - 2008 - FreeBSD 文件計劃 - + 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 The FreeBSD Documentation Project - &trademarks; + + + 版權所有 - &legalnotice; + Redistribution and use in source (XML DocBook) and 'compiled' + forms (XML, HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions are + met: + + + + Redistributions of source code (XML DocBook) must retain the + above copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + + + Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must + reproduce the above copyright notice, this list of conditions and + the following disclaimer in the documentation and/or other + materials provided with the distribution. + + + + + THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION + PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, + BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL + THE FREEBSD DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, + INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, + BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS + OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR + TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE + USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH + DAMAGE. + + + + + + FreeBSD 是 FreeBSD 基金會的註冊商標。 + UNIX 是 The Open Group 在美國和其他國家的註冊商標。 + Sun, Sun Microsystems, Java, Java Virtual Machine, JDK, JRE, JSP, JVM, Netra, OpenJDK, Solaris, StarOffice, SunOS 和 VirtualBox 是 Sun Microsystems, Inc. 在美國和其他國家的註冊商標。 + Many of the designations used by + manufacturers and sellers to distinguish their products are claimed + as trademarks. Where those designations appear in this document, + and the FreeBSD Project was aware of the trademark claim, the + designations have been followed by the ™ or the + ® symbol. + $FreeBSD$ - - 楔子 + + + - - 本文內所提及的環境變數 - (VAR)部份， - 只有一些可以替換(overridden)。大部份的環境變數(非全部)通常都會寫在 - /usr/ports/Mk/bsd.port.mk 內，其他的也是差不多。 - 請注意：該檔並非使用一般的 tab 設定值，而是採用 1 個 tab 等於 4 個 - space。 Emacs 與 - Vim 應該都會在載入該檔時順便讀取相關設定值。 - &man.vi.1; 及 &man.ex.1; 這兩個程式也都可以打 - :set tabstop=4 以修改設定值。 - - + 楔子 - - 打造 Port 快速上手篇 + 幾乎每個 FreeBSD 愛用者都是透過 FreeBSD Ports Collection 來裝各式應用程式("ports")。如同 FreeBSD 的其他部分一樣， 這些 ports 都主要來自許多志工的努力成果，所以在閱讀這份文件時， 請務必感恩在心。 - 本節主要介紹如何來快速打造 port，然而， - 很多時候這些內容並不是很夠用，建議閱讀本文件中更深奧的地方。 + 在 FreeBSD 上面，每個人都可以提交新的 port， 或假如該 port 並沒有人維護的話，可以自願維護 —— 這點並不需要任何 commit 的權限，就可以來做這件事情。 + - 首先取得該應用程式的原始程式碼壓縮檔(tarball)，並把它放到 - DISTDIR，預設路徑應該是 - /usr/ports/distfiles。 - - 下面的例子，是假設並不需要再修改該應用程式的原始碼，就可以在 - FreeBSD 上編譯成功的；假如還需要另外修改才能成功編譯的話， - 那麼請參考下一章的說明。 - + + - - 編寫 <filename>Makefile</filename> + - 最簡單的 Makefile 大概是像這樣： + 製作新的 Port - # New ports collection makefile for: oneko -# Date created: 5 December 1994 -# Whom: asami -# -# $FreeBSD$ -# + 開始對製作新的 port 或更新現有 port 有一些興趣了嗎？太好囉！ + + 下面將介紹一些建立 port 時該注意的事項。如果是想升級現有的 port ，那麼也請參閱 說明。 + + 因為這份文件可能講得不是十分詳細，可能需要參考 /usr/ports/Mk/bsd.port.mk 這檔是所有 port 的 Makefile 檔都會用到的。就算你不是每天不斷 hacking Makefile，也可以也可以從中獲得很多相關知識。 此外，若有其他特定 port 的問題，也可以到 FreeBSD ports mailing list 來獲得答案。 + + + 本文內所提及的環境變數 (VAR)部份， 只有一些可以替換(overridden)。大部份的環境變數(非全部)通常都會寫在 /usr/ports/Mk/bsd.port.mk 內，其他的也是差不多。 請注意：該檔並非使用一般的 tab 設定值，而是採用 1 個 tab 等於 4 個 space。 Emacs 與 Vim 應該都會在載入該檔時順便讀取相關設定值。 vi1 及 ex1 這兩個程式也都可以打 :set tabstop=4 以修改設定值。 + + + 想要找簡單的開始上手嗎？ 到 請求協助的 ports 清單 瞧瞧，看看是否有你可以幫上忙的。 + + + + + + + + 打造 Port 快速上手篇 + + 本節主要介紹如何來快速打造 port，然而實際應用時這快速方法可能不足，完整的 慢速打造 Port 的步驟在 詳述。 + + 首先取得該應用程式的原始程式碼壓縮檔(tarball)，並把它放到 DISTDIR，預設路徑應該是 /usr/ports/distfiles. + + + 這些步驟假設軟體可以直接編譯。也就是不需要任何修改就可以直接在 FreeBSD 上執行。如果需要修改，請參見。 + + + + It is recommended to set the DEVELOPER + make1 variable in /etc/make.conf + before getting into porting. + + # echo DEVELOPER=yes >> /etc/make.conf + + This setting enables the developer mode + that displays deprecation warnings and activates some further + quality checks on calling make. + + + + 編寫 <filename>Makefile</filename> + + 最簡單的 Makefile 大概是像這樣： + + # $FreeBSD$ + +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> - 嗯，大致就是這樣，看看你已經領略多少了呢？ - 看到 $FreeBSD$ 這一行的話，別想太多 - ，它是 RCS ID 用途，當該 port 正式進入 port tree 時， - CVS 就會自動轉換為相關字串囉。 有關這點的細節部份，可以參閱 sample Makefile 章節。 - - - - 撰寫該軟體的說明檔 - - 無論是否打算再加工做成 package，有 2 個檔案是任何實體 port (Slave - port則不一定)都必須要具備的。 這 2 個檔分別是 - pkg-descr 檔及 pkg-plist - 檔。 這兩個檔案檔名前面都有 pkg- - 以跟其他檔案做區別。 + + In some cases, the Makefile of an + existing port may contain additional lines in the header, + such as the name of the port and the date it was created. + This additional information has been declared obsolete, and + is being phased out. + + + 嗯，大致就是這樣，看看你已經領略多少了呢？ 看到 $FreeBSD$ 這一行的話，別想太多 ，當該 port 正式進入 port tree 時， Subversion 就會自動轉換為相關字串囉。 有關這點的細節部份，可以參閱 sample Makefile 章節。 + + + + 撰寫說明檔 - - <filename>pkg-descr</filename> + 無論是否打算再加工做成 package，有兩個檔案是任何 port 都必須要具備的。 這兩個檔分別是 pkg-descr 及 pkg-plist 。 他們檔名前面都有 pkg- 以跟其他檔案做區別。 - 這是此 port 的詳細說明檔，請用一段或幾段文字來說明該 port - 的作用，並附上 WWW 網址(若有的話)。 + + <filename>pkg-descr</filename> - - 請注意，這檔絕非「該軟體的說明手冊」或是「如何編譯、使用該 - port 的說明」。 若是從該軟體的 README - 或 manpage 直接複製過來的話，請注意，因為它們通常都寫得太詳細、 - 格式較特別(比如 manpage 會自動調整空白)， - 請儘量避免這些冗長贅詞或採用特殊格式。若該軟體有官方版首頁的話， - 請在此列出來。 每個網址請用 WWW: 作為開頭， - 這樣子相關工具程式就會自動處理完畢。 - + 這是此 port 的詳細說明檔，請用一段或幾段文字來說明該 port 的作用 - 該 port 的 pkg-descr 內容，大致如下面例子 - ： + + 請注意，這檔絕非「該軟體的說明手冊」或是「如何編譯、使用該 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. + - This is a port of oneko, in which a cat chases a poor mouse all over + 這是 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/ - + - - <filename>pkg-plist</filename> + + <filename>pkg-plist</filename> - 這是該 port 所會裝的所有檔案清單，另外因為 package - 會由這清單所產生，因此也被稱為『packing list - (打包清單)』。 以 ${PREFIX} 為基準點， - 而用相對路徑表示。(${PREFIX} 通常是 - /usr/local 或 /usr/X11R6) - 但是如果該程式有安裝 man page 的話，則要以類似 - MANn= 的方式寫在 - Makefile 內，不能列在 - pkg-plist 哦。 - 除了列出檔案以外，也要把該 port 所會建立的目錄也列進去， - 方式有兩種：一種是寫在 pkg-plist 內的方式， - 比如：@dirrm。 至於另外一種方式，則是寫在 - Makefile 內，比如： - PLIST_FILES= 之類的方式。 + 這是該 port 所會裝的所有檔案清單，另外因為 package 會由這清單所產生，因此也被稱為『packing list (打包清單)』。路徑是相對於安裝的 prefix (通常是 /usr/local )。 - 該 port 的 pkg-plist 內容， - 大致如下面例子: + 這是一個簡單的例子： - bin/oneko + 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 -@dirrm lib/X11/oneko +lib/X11/oneko/mouse.xpm - 關於 packing list 方面，可以參閱 &man.pkg.create.1; 會有詳解 - 。 + 關於 packing list 方面，可以詳閱 pkg-create8 manual page 。 - - 建議清單內的檔名，依照字母順序作排序，那麼下次要升級時， - 會比較清楚、方便來更新這份清單。 - + + 建議清單內的檔名，依照字母順序作排序，那麼下次要升級時， 會比較清楚、方便來更新這份清單。 + - - 手動生這份清單實在太苦了。尤其若該 port 會裝一大堆檔案的話， - 請多善用 自動產生 packing - list 會比較省時省力唷。 - + + 手動產生這份清單實在太苦了。尤其若該 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. + - 只有在一種情況下可以省略不用生 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 是必須付出代價： - 不能使用 &man.pkg.create.1; 內所說的 command sequences。 - 因此，這招僅適用於較簡單的 port ，以及簡化該 port 的作法。 - 此外，這招還有一個好處：可以減少 ports collection 的整體檔案總數。 - 所以，在考慮是否一定要用 pkg-plist 之前， - 可以先斟酌這個替代方案看看。 - - 後面會介紹到如何運用 pkg-plist、 - PLIST_FILES 這些技巧以因應 更複雜的狀況。 - - - - - 產生 checksum 用途的 distinfo 檔 - - 只要打『make makesum』就好了， - 接下來就會自動產生相對應的 distinfo 檔了唷 - 。 - + + If a port needs to create an empty directory, or creates + directories outside of ${PREFIX} during + installation, refer to + for more information. + - - 檢驗 port 是否完整、可行 + 然而，使用這個方法列出 port 的檔案和目錄是必須付出代價： 不能使用 pkg-create8 和 描述的關鍵字。 因此，這招僅適用於較簡單的 port ，以及簡化該 port 的作法。 此外，這招還有一個好處：可以減少 ports collection 的整體檔案總數。 所以，在考慮是否要用 pkg-plist 之前， 可以先斟酌這個替代方案看看。 - 接下來，必須檢驗是否有符合 port 的遊戲規則，包括打包該 port - 為 package。 以下有幾個需要確認的重要地方： + 後面會介紹到如何運用 pkg-plist、 PLIST_FILES 這些技巧以因應更複雜的狀況。 + + - + + 產生 checksum 檔 + + 只要打 make makesum 就好了， 接下來就會自動產生相對應的 distinfo 檔了唷 。 + + + + 測試 Port + + 接下來，必須檢驗是否有符合 port 的遊戲規則，包括打包該 port 為 package。 以下有幾個需要確認的重要地方： + + + + 若該 port 沒裝的東西，不要列在 pkg-plist 內。 + + + + 若該 port 有裝的東西，請務必列在 pkg-plist 內。 + + + + The port can be installed using the + install target. This verifies + that the install script works correctly. + + + + The port can be deinstalled properly using the + deinstall target. This + verifies that the deinstall script works correctly. + + + + The port does not access network resources after the + fetch target. This is important + for package builders, such as ports-mgmt/poudriere. + + + + Make sure that make package can be + run as a normal user (that is, not as + root). If that + fails, NEED_ROOT=yes must be added to + the port Makefile. + + + + + 建議的測試順序 + + + make stage + + + + make check-orphans + + + + make package + + + + make install + + + + make deinstall + + + + pkg add package-filename + + + + make package (as user) + + + + 確認在任何階段都沒有任何警告出現。 + + Thorough automated testing can be done with + ports-mgmt/tinderbox or + ports-mgmt/poudriere from the + Ports Collection. These applications maintain + jails where all of the steps shown above + can be tested without affecting the state of the host + system. + + + + 以 <command>portlint</command> 來作檢查 Port + + 請用 portlint 來檢查該 port 是否有遵循我們的規則。 ports-mgmt/portlint 是 ports collection 的其中一個套件。 它主要可以用來檢驗 Makefile 內容是否正確以及 package 是否有正確命名。 + + + + 提交新的 Port + + 提交新的 Port 前，請閱讀 DOs and DON'Ts 章節。 + + 現在你很高興終於打造出 port 來囉，唯一剩下要做的就是把它正式放到 FreeBSD ports tree 內，才能讓每個人都能分享使用這個 port。 我們不需要 work 目錄或是檔名像 pkgname.tgz 的 package ，請現在刪除他們。 + + Next, build the shar1 file. Assuming the port is + called oneko, cd to the + directory above where the oneko directory + is located, and then type: + shar `find oneko` > oneko.shar + + + + To submit oneko.shar, use the bug submit + form (category Ports Tree). + Add a short + description of the program to the Description field of the PR + (perhaps a short version of COMMENT), and + do not forget to add oneko.shar as an + attachment. + + + Giving a good description in the summary of the problem + report makes the work of port committers a lot easier. We + prefer something like New port: + category/portname short description of + the port for new ports. Using this + scheme makes it easier and faster to begin the work of + committing the new port. + + + 再次強調一點：不必附上原始 source 的 distfile ，也就是 work 目錄。 同時，也不必附上 make package 時產生的 package。新的 port 請使用 shar1 ，不要用 diff1 。 + + 送出 port 之後，請耐心等候佳音。 有時候可能需要等個幾天或幾個月時間，才會在 FreeBSD ports tree 上正式出現。 等待中的 port PR 清單可以在 查閱。 + + 在看過新的 port 之後，如果需要的話，我們會回覆您，然後會將它提交到 port tree 。 您的大名會被列在 Additional FreeBSD Contributors 列表上，以及其他檔案中。 + + + + + + + + Slow Porting + + Ok...事實上並不太可能這麼簡單，port 方面可能需要作些修改才能正常使用。 因此， 本節將一步一步來介紹如何修改上一章的樣本以正常使用。 + + + How Things Work + + First, this is the sequence of events which occurs when the + user first types make in the port's + directory. Having + bsd.port.mk in another window while + reading this really helps to understand it. + + 別太擔心，不是很多人都真的了解 bsd.port.mk 在做什麼... :-) + + + + The fetch target is run. The + fetch target is responsible for + making sure that the tarball exists locally in + DISTDIR. If + fetch cannot find the required + files in DISTDIR it will look up the URL + MASTER_SITES, which is set in the + Makefile, as well as our FTP mirrors where we put distfiles + as backup. It will then attempt to fetch the named + distribution file with FETCH, assuming + that the requesting site has direct access to the Internet. + If that succeeds, it will save the file in + DISTDIR for future use and + proceed. + + + + The extract target is run. + It looks for the port's distribution file (typically a + gzipped tarball) in + DISTDIR and unpacks it into a temporary + subdirectory specified by WRKDIR + (defaults to work). + + + + The patch target is run. + First, any patches defined in PATCHFILES + are applied. Second, if any patch files named + patch-* are + found in PATCHDIR (defaults to the + files subdirectory), they are applied + at this time in alphabetical order. + + + + The configure target is run. + This can do any one of many different things. + + - 若該 port 沒裝的東西，不要列在 pkg-plist - 內。 + If it exists, scripts/configure + is run. - 若該 port 有裝的東西，請務必列在 - pkg-plist 內。 + If HAS_CONFIGURE or + GNU_CONFIGURE is set, + WRKSRC/configure is run. + + + + + The build target is run. + This is responsible for descending into the port's private + working directory (WRKSRC) and building + it. + + + + The stage target is run. + This puts the final set of built files into a temporary + directory (STAGEDIR, see + ). The hierarchy of this directory + mirrors that of the system on which the package will be + installed. + + + + The package target is run. + This creates a package using the files from the temporary + directory created during the + stage target and the port's + pkg-plist. + + + + The install target is run. + This installs the package created during the + package target into the host + system. + + + + The above are the default actions. In addition, + define targets + pre-something + or + post-something, + or put scripts with those names, in the + scripts subdirectory, and they will be + run before or after the default actions are done. + + For example, if there is a + post-extract target defined in the + Makefile, and a file + pre-build in the + scripts subdirectory, the + post-extract target will be called + after the regular extraction actions, and + pre-build will be executed before + the default build rules are done. It is recommended to + use Makefile targets if the actions are + simple enough, because it will be easier for someone to figure + out what kind of non-default action the port requires. + + The default actions are done by the + do-something + targets from bsd.port.mk. + For example, the commands to extract a port are in the target + do-extract. If + the default target does not do the job right, redefine the + do-something + target in the Makefile. + + + The main targets (for example, + extract, + configure, etc.) do nothing more + than make sure all the stages up to that one are completed and + call the real targets or scripts, and they are not intended to + be changed. To fix the extraction, fix + do-extract, but never ever change + the way extract operates! + Additionally, the target + post-deinstall is invalid and is + not run by the ports infrastructure. + + + Now that what goes on when the user types make + install is better understood, let us go through the + recommended steps to create the perfect port. + + + + 取得原始碼 + + Get the original sources (normally) as a compressed tarball + (foo.tar.gz or + foo.tar.bz2) and + copy it into DISTDIR. Always use + mainstream sources when and where + possible. + + Set the variable + MASTER_SITES to reflect where the original + tarball resides. Shorthand definitions exist + for most mainstream sites in bsd.sites.mk. + Please use these sites—and the associated + definitions—if at all possible, to help avoid the problem + of having the same information repeated over again many times in + the source base. As these sites tend to change over time, this + becomes a maintenance nightmare for everyone involved. See + for details. + + If there is no FTP/HTTP site that is well-connected to + the net, or can only find sites that have irritatingly + non-standard formats, put a copy on a reliable + FTP or HTTP server (for example, a home + page). + + If a convenient and reliable place to put + the distfile cannot be found, we can house it ourselves on + ftp.FreeBSD.org; however, this is the + least-preferred solution. The distfile must be placed into + ~/public_distfiles/ of someone's + freefall account. Ask the person who + commits the port to do this. This person will also set + MASTER_SITES to + LOCAL/username + where username is + their FreeBSD cluster login. + + If the port's distfile changes all the time without any + kind of version update by the author, consider putting the + distfile on a home page and listing it as the first + MASTER_SITES. Try to talk the + port author out of doing this; it really does help to establish + some kind of source code control. Hosting a specific version will + prevent users from getting + checksum mismatch errors, and also reduce + the workload of maintainers of our FTP site. Also, if there is + only one master site for the port, it is recommended to + house a backup on a home page and list it as the second + MASTER_SITES. + + If the port requires additional patches that are + available on the Internet, fetch them too and put them in + DISTDIR. Do not worry if they come from a + site other than where the main source tarball comes, we have a + way to handle these situations (see the description of PATCHFILES below). + + + + Modifying the Port + + Unpack a copy of the tarball in a private directory and make + whatever changes are necessary to get the port to compile + properly under the current version of FreeBSD. Keep + careful track of steps, as they will be + needed to automate the process shortly. Everything, including + the deletion, addition, or modification of files has to be + doable using an automated script or patch file when the port is + finished. + + If the port requires significant user + interaction/customization to compile or install, take + a look at one of Larry Wall's classic + Configure scripts and perhaps do + something similar. The goal of the new ports + collection is to make each port as plug-and-play + as possible for the end-user while using a minimum of disk + space. + + + Unless explicitly stated, patch files, scripts, and other + files created and contributed to the FreeBSD ports + collection are assumed to be covered by the standard BSD + copyright conditions. + + + + + Patching + + In the preparation of the port, files that have been added + or changed can be recorded with diff1 for later feeding + to patch1. Doing this with a typical file involves + saving a copy of the original file before making any changes + using a .orig suffix. + + % cp file file.orig + + After all changes have been made, cd back + to the port directory. Use make makepatch to + generate updated patch files in the files + directory. + + + General Rules for Patching + + Patch files are stored in PATCHDIR, + usually files/, from where they will be + automatically applied. All patches must be relative to + WRKSRC. Typically + WRKSRC is a subdirectory of + WRKDIR, the directory where the distfile is + extracted. Use make -V WRKSRC to see the + actual path. The patch names are to follow these + rules: + + + + Avoid having more than one patch modify the same file. + For example, having both + patch-foobar.c and + patch-foobar.c2 making changes to + ${WRKSRC}/foobar.c makes them fragile + and difficult to debug. + + + + When creating names for patch files, replace each + underscore (_) with two underscores + (__) and each slash + (/) with one underscore + (_). For example, to patch a file + named src/freeglut_joystick.c, name + the corresponding patch + patch-src_freeglut__joystick.c. Do + not name patches like patch-aa or + patch-ab. Always use the path and + file name in patch names. Using make + makepatch automatically generates the correct + names. + + + + A patch may modify multiple files if the changes are + related and the patch is named appropriately. For + example, + patch-add-missing-stdlib.h. + + + + Only use characters [-+._a-zA-Z0-9] + for naming patches. In particular, do not use + :: as a path separator, + use _ instead. + + + + + Minimize the amount of non-functional whitespace changes + in patches. It is common in the Open Source world for + projects to share large amounts of a code base, but obey + different style and indenting rules. When taking a working + piece of functionality from one project to fix similar areas + in another, please be careful: the resulting patch may be full + of non-functional changes. It not only increases the size of + the ports repository but makes it hard to find out what + exactly caused the problem and what was changed at all. + + If a file must be deleted, do it in the + post-extract target rather than as + part of the patch. + + + + + Manual Patch Generation + + + Manual patch creation is usually not necessary. + Automatic patch generation as described earlier in this + section is the preferred method. However, manual patching *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***