Date: Tue, 29 Mar 2016 01:37:53 +0000 (UTC) From: Kevin Lo <kevlo@FreeBSD.org> 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 Message-ID: <201603290137.u2T1brrn001508@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 @@ <?xml version="1.0" encoding="utf-8"?> -<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" - "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">; +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [ +<!ENTITY values.uses SYSTEM "uses.xml"> +<!ENTITY values.versions SYSTEM "versions.xml"> <!-- The FreeBSD Documentation Project $FreeBSD$ - Original Revision: 1.954 ---> -<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_tw"> - <info><title>FreeBSD Porter's Handbook</title> - +--><!ENTITY % chapters SYSTEM "chapters.ent"> +<!-- + Creates entities for each chapter in the Porters Handbook. Each entity + is named chap.foo, where foo is the value of the id attribute on that + chapter, and corresponds to the name of the directory in which that + chapter's .xml file is stored. + + Chapters should be listed in the order in which they are referenced. + + $FreeBSD$ +--><!ENTITY chap.porting-why SYSTEM "porting-why/chapter.xml"> +<!ENTITY chap.new-port SYSTEM "new-port/chapter.xml"> +<!ENTITY chap.quick-porting SYSTEM "quick-porting/chapter.xml"> +<!ENTITY chap.slow-porting SYSTEM "slow-porting/chapter.xml"> +<!ENTITY chap.makefiles SYSTEM "makefiles/chapter.xml"> +<!ENTITY chap.special SYSTEM "special/chapter.xml"> +<!ENTITY chap.plist SYSTEM "plist/chapter.xml"> +<!ENTITY chap.pkg-files SYSTEM "pkg-files/chapter.xml"> +<!ENTITY chap.testing SYSTEM "testing/chapter.xml"> +<!ENTITY chap.upgrading SYSTEM "upgrading/chapter.xml"> +<!ENTITY chap.security SYSTEM "security/chapter.xml"> +<!ENTITY chap.porting-dads SYSTEM "porting-dads/chapter.xml"> +<!ENTITY chap.porting-samplem SYSTEM "porting-samplem/chapter.xml"> +<!ENTITY chap.keeping-up SYSTEM "keeping-up/chapter.xml"> +<!ENTITY chap.uses SYSTEM "uses/chapter.xml"> +<!ENTITY chap.versions SYSTEM "versions/chapter.xml"> +]> +<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_TW"> + + <info> + <title>FreeBSD Porter 手冊</title> <authorgroup> - <author><orgname>FreeBSD 文件計劃</orgname></author> + <author><orgname>The FreeBSD Documentation Project</orgname></author> </authorgroup> - <pubdate>April 2000</pubdate> + <pubdate>$FreeBSD$</pubdate> - <copyright> - <year>2000</year> - <year>2001</year> - <year>2002</year> - <year>2003</year> - <year>2004</year> - <year>2005</year> - <year>2006</year> - <year>2007</year> - <year>2008</year> - <holder role="mailto:doc@FreeBSD.org">FreeBSD 文件計劃</holder> - </copyright> + <copyright><year>2000</year> <year>2001</year> <year>2002</year> <year>2003</year> <year>2004</year> <year>2005</year> <year>2006</year> <year>2007</year> <year>2008</year> <year>2009</year> <year>2010</year> <year>2011</year> <year>2012</year> <year>2013</year> <year>2014</year> <year>2015</year> <year>2016</year> <holder role="mailto:doc@FreeBSD.org">The FreeBSD Documentation Project</holder></copyright> - &trademarks; + +<legalnotice xml:id="legalnotice"> + <title>版權所有</title> - &legalnotice; + <para xml:lang="en">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:</para> + + <orderedlist> + <listitem> + <para xml:lang="en">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.</para> + </listitem> + + <listitem> + <para xml:lang="en">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.</para> + </listitem> + </orderedlist> + + <important> + <para xml:lang="en">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.</para> + </important> +</legalnotice> + + + <legalnotice xml:id="trademarks" role="trademarks"> + <para>FreeBSD 是 FreeBSD 基金會的註冊商標。</para> + <para>UNIX 是 The Open Group 在美國和其他國家的註冊商標。</para> + <para>Sun, Sun Microsystems, Java, Java Virtual Machine, JDK, JRE, JSP, JVM, Netra, OpenJDK, Solaris, StarOffice, SunOS 和 VirtualBox 是 Sun Microsystems, Inc. 在美國和其他國家的註冊商標。</para> + <para xml:lang="en">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 <quote>™</quote> or the + <quote>®</quote> symbol.</para> + </legalnotice> <releaseinfo>$FreeBSD$</releaseinfo> </info> - <chapter xml:id="why-port"> - <title>楔子</title> + +<!-- + The FreeBSD Documentation Project - <para>幾乎每個 FreeBSD 愛用者都是透過 FreeBSD Ports Collection - 來裝各式應用程式("ports")。如同 FreeBSD 的其他部分一樣， - 這些 ports 都主要來自許多志工的努力成果，所以在閱讀這份文件時， - 請務必感恩在心。</para> - - <para>在 FreeBSD 上面，每個人都可以提交新的 port， - 或假如該 port 並沒有人維護的話，可以自願維護 — - 這點並不需要任何 commit 的權限，就可以來做這件事情。</para> - - </chapter> - - <chapter xml:id="own-port"> - <title>自行打造 port</title> - - <para>那麼，開始對自行製作 port 或更新有一些興趣了嗎？太好囉！</para> - - <para>下面將介紹一些建立 port 時該注意的事項。如果是想升級現有的 port - ，那麼也請參閱 <xref linkend="port-upgrading"/> 說明。</para> - - <para>因為這份文件可能講得不是十分詳細，可能需要參考 - <filename>/usr/ports/Mk/bsd.port.mk</filename> 這檔是所有 port 的 - Makefile 檔都會用到的。 就算你不是每天不斷 hacking Makefiles - ，也都可以藉由它來對整個 port 機制、Makefile 更瞭解， - 裡面的註釋相當詳細。 此外，若有其他特定 port 的問題，也可以到 - &a.ports; 來獲得答案。</para> + $FreeBSD$ +--> +<chapter version="5.0" xml:id="why-port"> - <note> - <para>本文內所提及的環境變數 - (<varname><replaceable>VAR</replaceable></varname>)部份， - 只有一些可以替換(overridden)。大部份的環境變數(非全部)通常都會寫在 - <filename>/usr/ports/Mk/bsd.port.mk</filename> 內，其他的也是差不多。 - 請注意：該檔並非使用一般的 tab 設定值，而是採用 1 個 tab 等於 4 個 - space。 <application>Emacs</application> 與 - <application>Vim</application> 應該都會在載入該檔時順便讀取相關設定值。 - &man.vi.1; 及 &man.ex.1; 這兩個程式也都可以打 - <command>:set tabstop=4</command> 以修改設定值。</para> - </note> - </chapter> + <title>楔子</title> - <chapter xml:id="quick-porting"> - <title>打造 Port 快速上手篇</title> + <para>幾乎每個 FreeBSD 愛用者都是透過 FreeBSD Ports Collection 來裝各式應用程式("ports")。如同 FreeBSD 的其他部分一樣， 這些 ports 都主要來自許多志工的努力成果，所以在閱讀這份文件時， 請務必感恩在心。</para> - <para>本節主要介紹如何來快速打造 port，然而， - 很多時候這些內容並不是很夠用，建議閱讀本文件中更深奧的地方。</para> + <para>在 FreeBSD 上面，每個人都可以提交新的 port， 或假如該 port 並沒有人維護的話，可以自願維護 —— 這點並不需要任何 commit 的權限，就可以來做這件事情。</para> +</chapter> - <para>首先取得該應用程式的原始程式碼壓縮檔(tarball)，並把它放到 - <varname>DISTDIR</varname>，預設路徑應該是 - <filename>/usr/ports/distfiles</filename>。</para> - <note> - <para>下面的例子，是假設並不需要再修改該應用程式的原始碼，就可以在 - FreeBSD 上編譯成功的；假如還需要另外修改才能成功編譯的話， - 那麼請參考下一章的說明。</para> - </note> + +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> - <sect1 xml:id="porting-makefile"> - <title>編寫 <filename>Makefile</filename></title> +<chapter version="5.0" xml:id="own-port"> - <para>最簡單的 <filename>Makefile</filename> 大概是像這樣：</para> + <title>製作新的 Port</title> - <programlisting># New ports collection makefile for: oneko -# Date created: 5 December 1994 -# Whom: asami -# -# $FreeBSD$ -# + <para>開始對製作新的 port 或更新現有 port 有一些興趣了嗎？太好囉！</para> + + <para>下面將介紹一些建立 port 時該注意的事項。如果是想升級現有的 port ，那麼也請參閱 <xref linkend="port-upgrading"/> 說明。</para> + + <para>因為這份文件可能講得不是十分詳細，可能需要參考 <filename>/usr/ports/Mk/bsd.port.mk</filename> 這檔是所有 port 的 <filename>Makefile</filename> 檔都會用到的。就算你不是每天不斷 hacking <filename>Makefile</filename>，也可以也可以從中獲得很多相關知識。 此外，若有其他特定 port 的問題，也可以到 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports">FreeBSD ports mailing list</link> 來獲得答案。</para> + + <note> + <para>本文內所提及的環境變數 (<varname><replaceable>VAR</replaceable></varname>)部份， 只有一些可以替換(overridden)。大部份的環境變數(非全部)通常都會寫在 <filename>/usr/ports/Mk/bsd.port.mk</filename> 內，其他的也是差不多。 請注意：該檔並非使用一般的 tab 設定值，而是採用 1 個 tab 等於 4 個 space。 <application>Emacs</application> 與 <application>Vim</application> 應該都會在載入該檔時順便讀取相關設定值。 <citerefentry><refentrytitle>vi</refentrytitle><manvolnum>1</manvolnum></citerefentry> 及 <citerefentry><refentrytitle>ex</refentrytitle><manvolnum>1</manvolnum></citerefentry> 這兩個程式也都可以打 <command>:set tabstop=4</command> 以修改設定值。</para> + </note> + + <para>想要找簡單的開始上手嗎？ 到 <link xlink:href="http://wiki.freebsd.org/WantedPorts">請求協助 ports 清單</link> 瞧瞧，看看是否有你可以幫上忙的。</para> +</chapter> + + + +<!-- + The FreeBSD Documentation Project -PORTNAME= oneko -PORTVERSION= 1.1b -CATEGORIES= games -MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ - -MAINTAINER= asami@FreeBSD.org -COMMENT= A cat chasing a mouse all over the screen - -MAN1= oneko.1 -MANCOMPRESSED= yes -USE_IMAKE= yes + $FreeBSD$ +--> +<chapter version="5.0" xml:id="quick-porting"> + + <title>打造 Port 快速上手篇</title> + + <para>本節主要介紹如何來快速打造 port，然而實際應用時這快速方法可能不足，完整的 <quote>慢速打造 Port</quote> 的步驟在 <xref linkend="slow-porting"/> 詳述。</para> + + <para>首先取得該應用程式的原始程式碼壓縮檔(tarball)，並把它放到 <varname>DISTDIR</varname>，預設路徑應該是 <filename>/usr/ports/distfiles</filename>.</para> + + <note> + <para>這些步驟假設軟體可以直接編譯。也就是不需要任何修改就可以直接在 FreeBSD 上執行。如果需要修改，請參見<xref linkend="slow-porting"/>。</para> + </note> + + <note> + <para xml:lang="en">It is recommended to set the <varname>DEVELOPER</varname> + <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> variable in <filename>/etc/make.conf</filename> + before getting into porting.</para> + + <screen xml:lang="en"><prompt>#</prompt> <userinput>echo DEVELOPER=yes >> /etc/make.conf</userinput></screen> + + <para xml:lang="en">This setting enables the <quote>developer mode</quote> + that displays deprecation warnings and activates some further + quality checks on calling <command>make</command>.</para> + </note> + + <sect1 xml:id="porting-makefile"> + <title>編寫 <filename>Makefile</filename></title> + + <para>最簡單的 <filename>Makefile</filename> 大概是像這樣：</para> + + <programlisting># $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></programlisting> - <para>嗯，大致就是這樣，看看你已經領略多少了呢？ - 看到 <literal>$FreeBSD$</literal> 這一行的話，別想太多 - ，它是 RCS ID 用途，當該 port 正式進入 port tree 時， - CVS 就會自動轉換為相關字串囉。 有關這點的細節部份，可以參閱 <link linkend="porting-samplem">sample Makefile</link> 章節。</para> - </sect1> - - <sect1 xml:id="porting-desc"> - <title>撰寫該軟體的說明檔</title> - - <para>無論是否打算再加工做成 package，有 2 個檔案是任何實體 port (Slave - port則不一定)都必須要具備的。 這 2 個檔分別是 - <filename>pkg-descr</filename> 檔及 <filename>pkg-plist</filename> - 檔。 這兩個檔案檔名前面都有 <filename>pkg-</filename> - 以跟其他檔案做區別。</para> + <note> + <para xml:lang="en">In some cases, the <filename>Makefile</filename> 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.</para> + </note> + + <para>嗯，大致就是這樣，看看你已經領略多少了呢？ 看到 <literal>$FreeBSD$</literal> 這一行的話，別想太多 ，當該 port 正式進入 port tree 時， <application>Subversion</application> 就會自動轉換為相關字串囉。 有關這點的細節部份，可以參閱 <link linkend="porting-samplem">sample Makefile</link> 章節。</para> + </sect1> + + <sect1 xml:id="porting-desc"> + <title>撰寫說明檔</title> - <sect2> - <title><filename>pkg-descr</filename></title> + <para>無論是否打算再加工做成 package，有兩個檔案是任何 port 都必須要具備的。 這兩個檔分別是 <filename>pkg-descr</filename> 及 <filename>pkg-plist</filename> 。 他們檔名前面都有 <filename>pkg-</filename> 以跟其他檔案做區別。</para> - <para>這是此 port 的詳細說明檔，請用一段或幾段文字來說明該 port - 的作用，並附上 WWW 網址(若有的話)。</para> + <sect2 xml:id="porting-pkg-descr"> + <title><filename>pkg-descr</filename></title> - <note> - <para>請注意，這檔絕非「該軟體的說明手冊」或是「如何編譯、使用該 - port 的說明」。 若是從該軟體的 <filename>README</filename> - 或 manpage 直接複製過來的話，請注意，因為它們通常都寫得太詳細、 - 格式較特別(比如 manpage 會自動調整空白)， - 請儘量避免這些冗長贅詞或採用特殊格式。若該軟體有官方版首頁的話， - 請在此列出來。 每個網址請用 <literal>WWW:</literal> 作為開頭， - 這樣子相關工具程式就會自動處理完畢。</para> - </note> + <para>這是此 port 的詳細說明檔，請用一段或幾段文字來說明該 port 的作用</para> - <para>該 port 的 <filename>pkg-descr</filename> 內容，大致如下面例子 - ：</para> + <note> + <para>請注意，這檔<emphasis>絕非</emphasis>「該軟體的說明手冊」或是「如何編譯、使用該 port 的說明」！ <emphasis>若是從該軟體的 <filename>README</filename> 或 manpage 直接複製過來的話，請注意</emphasis>。他們常常不是正確的 port 描述或是格式並不適合。例如，manpage會對齊空白，這用monospace字型來看會特別糟糕。</para> + </note> + + <para xml:lang="en">A well-written <filename>pkg-descr</filename> 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.</para> + + <para xml:lang="en">Include a URL to the official WWW homepage. Prepend + <emphasis>one</emphasis> of the websites (pick the most + common one) with <literal>WWW:</literal> (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.</para> + + <note> + <para xml:lang="en">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.</para> + </note> - <programlisting>This is a port of oneko, in which a cat chases a poor mouse all over + <para>這是 <filename>pkg-descr</filename> 內容的例子 ：</para> + + <programlisting>This is a port of oneko, in which a cat chases a poor mouse all over the screen. : (etc.) WWW: http://www.oneko.org/</programlisting>; - </sect2> + </sect2> - <sect2> - <title><filename>pkg-plist</filename></title> + <sect2 xml:id="porting-pkg-plist"> + <title><filename>pkg-plist</filename></title> - <para>這是該 port 所會裝的所有檔案清單，另外因為 package - 會由這清單所產生，因此也被稱為『packing list - (打包清單)』。 以 <literal>${PREFIX}</literal> 為基準點， - 而用相對路徑表示。(<literal>${PREFIX}</literal> 通常是 - <filename>/usr/local</filename> 或 <filename>/usr/X11R6</filename>) - 但是如果該程式有安裝 man page 的話，則要以類似 - <varname>MAN<replaceable>n</replaceable>=</varname> 的方式寫在 - <filename>Makefile</filename> 內，不能列在 - <filename>pkg-plist</filename> 哦。 - 除了列出檔案以外，也要把該 port 所會建立的目錄也列進去， - 方式有兩種：一種是寫在 <filename>pkg-plist</filename> 內的方式， - 比如：<literal>@dirrm</literal>。 至於另外一種方式，則是寫在 - <filename>Makefile</filename> 內，比如： - <literal>PLIST_FILES=</literal> 之類的方式。</para> + <para>這是該 port 所會裝的所有檔案清單，另外因為 package 會由這清單所產生，因此也被稱為『<quote>packing list (打包清單)</quote>』。路徑是相對於安裝的 prefix (通常是 <filename>/usr/local</filename> )。</para> - <para>該 port 的 <filename>pkg-plist</filename> 內容， - 大致如下面例子:</para> + <para>這是一個簡單的例子：</para> - <programlisting>bin/oneko + <programlisting>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</programlisting> +lib/X11/oneko/mouse.xpm</programlisting> - <para>關於 packing list 方面，可以參閱 &man.pkg.create.1; 會有詳解 - 。</para> + <para>關於 packing list 方面，可以詳閱 <citerefentry><refentrytitle>pkg-create</refentrytitle><manvolnum>8</manvolnum></citerefentry> manual page 。</para> - <note> - <para>建議清單內的檔名，依照字母順序作排序，那麼下次要升級時， - 會比較清楚、方便來更新這份清單。 </para> - </note> + <note> + <para>建議清單內的檔名，依照字母順序作排序，那麼下次要升級時， 會比較清楚、方便來更新這份清單。 </para> + </note> - <note> - <para>手動生這份清單實在太苦了。尤其若該 port 會裝一大堆檔案的話， - 請多善用 <link linkend="plist-autoplist">自動產生 packing - list</link> 會比較省時省力唷。</para> - </note> + <tip> + <para>手動產生這份清單實在太苦了。尤其若該 port 會裝一大堆檔案的話， 請多善用 <link linkend="plist-autoplist">自動產生 packing list</link> 會比較省時省力唷。</para> + </tip> + + <para>只有在一種情況下可以省略 <filename>pkg-plist</filename> 檔： 若安裝的 port 相當單純，只有裝一些檔案，那麼可以在 <filename>Makefile</filename> 內改用 <varname>PLIST_FILES</varname> 來取代。 比如，可以在上述的 <filename>oneko</filename> port 內不必附上 <filename>pkg-plist</filename> ，而只需在 <filename>Makefile</filename> 內加入下列幾行：</para> + + <programlisting>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</programlisting> + + <note> + <para xml:lang="en">Usage of <varname>PLIST_FILES</varname> should not be + abused. When looking for the origin of a file, people + usually try to <application>grep</application> through the + <filename>pkg-plist</filename> files in the ports tree. + Listing files in <varname>PLIST_FILES</varname> in the + <filename>Makefile</filename> makes that search more + difficult.</para> + </note> - <para>只有在一種情況下可以省略不用生 <filename>pkg-plist</filename> - 檔： 若安裝的 port 相當單純，只有裝一些檔案， - 以及都在同一目錄下的話，那麼可以在 <filename>Makefile</filename> - 內改用 <varname>PLIST_FILES</varname> 及 - <varname>PLIST_DIRS</varname> 來取代。 - 比如，可以在上述的 <filename>oneko</filename> port 內不必附上 - <filename>pkg-plist</filename> ，而只需在 - <filename>Makefile</filename> 內加入下列幾行：</para> - - <programlisting>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</programlisting> - - <para>當然，若該 port 並無安裝自屬的目錄的話，就不必設 - <varname>PLIST_DIRS</varname> 囉。</para> - - <para>然而，使用 <varname>PLIST_FILES</varname>、 - <varname>PLIST_DIRS</varname> 是必須付出代價： - 不能使用 &man.pkg.create.1; 內所說的 command sequences。 - 因此，這招僅適用於較簡單的 port ，以及簡化該 port 的作法。 - 此外，這招還有一個好處：可以減少 ports collection 的整體檔案總數。 - 所以，在考慮是否一定要用 <filename>pkg-plist</filename> 之前， - 可以先斟酌這個替代方案看看。</para> - - <para>後面會介紹到如何運用 <filename>pkg-plist</filename>、 - <varname>PLIST_FILES</varname> 這些技巧以因應 <link linkend="plist">更複雜的狀況</link>。</para> - </sect2> - </sect1> - - <sect1 xml:id="porting-checksum"> - <title>產生 checksum 用途的 distinfo 檔</title> - - <para>只要打『<command>make makesum</command>』就好了， - 接下來就會自動產生相對應的 <filename>distinfo</filename> 檔了唷 - 。</para> - </sect1> + <tip> + <para xml:lang="en">If a port needs to create an empty directory, or creates + directories outside of <filename>${PREFIX}</filename> during + installation, refer to <xref linkend="plist-dir-cleaning"/> + for more information.</para> + </tip> - <sect1 xml:id="porting-testing"> - <title>檢驗 port 是否完整、可行</title> + <para>然而，使用這個方法列出 port 的檔案和目錄是必須付出代價： 不能使用 <citerefentry><refentrytitle>pkg-create</refentrytitle><manvolnum>8</manvolnum></citerefentry> 和 <xref linkend="plist-keywords"/> 描述的關鍵字。 因此，這招僅適用於較簡單的 port ，以及簡化該 port 的作法。 此外，這招還有一個好處：可以減少 ports collection 的整體檔案總數。 所以，在考慮是否要用 <filename>pkg-plist</filename> 之前， 可以先斟酌這個替代方案看看。</para> - <para>接下來，必須檢驗是否有符合 port 的遊戲規則，包括打包該 port - 為 package。 以下有幾個需要確認的重要地方：</para> + <para>後面會介紹到如何運用 <filename>pkg-plist</filename>、 <varname>PLIST_FILES</varname> 這些技巧以因應<link linkend="plist">更複雜的狀況</link>。</para> + </sect2> + </sect1> - <itemizedlist> + <sect1 xml:id="porting-checksum"> + <title>產生 checksum 檔</title> + + <para>只要打 <command>make makesum</command> 就好了， 接下來就會自動產生相對應的 <filename>distinfo</filename> 檔了唷 。</para> + </sect1> + + <sect1 xml:id="porting-testing"> + <title>測試 Port</title> + + <para>接下來，必須檢驗是否有符合 port 的遊戲規則，包括打包該 port 為 package。 以下有幾個需要確認的重要地方：</para> + + <itemizedlist> + <listitem> + <para>若該 port 沒裝的東西，不要列在 <filename>pkg-plist</filename> 內。</para> + </listitem> + + <listitem> + <para>若該 port 有裝的東西，請務必列在 <filename>pkg-plist</filename> 內。</para> + </listitem> + + <listitem> + <para xml:lang="en">The port can be installed using the + <buildtarget xml:lang="en">install</buildtarget> target. This verifies + that the install script works correctly.</para> + </listitem> + + <listitem> + <para xml:lang="en">The port can be deinstalled properly using the + <buildtarget xml:lang="en">deinstall</buildtarget> target. This + verifies that the deinstall script works correctly.</para> + </listitem> + + <listitem> + <para xml:lang="en">The port does not access network resources after the + <buildtarget xml:lang="en">fetch</buildtarget> target. This is important + for package builders, such as <package role="port">ports-mgmt/poudriere</package>.</para> + </listitem> + + <listitem> + <para xml:lang="en">Make sure that <command>make package</command> can be + run as a normal user (that is, not as + <systemitem class="username">root</systemitem>). If that + fails, <literal>NEED_ROOT=yes</literal> must be added to + the port <filename>Makefile</filename>.</para> + </listitem> + </itemizedlist> + + <procedure> + <title>建議的測試順序</title> + + <step> + <para><command>make stage</command></para> + </step> + + <step> + <para><command>make check-orphans</command></para> + </step> + + <step> + <para><command>make package</command></para> + </step> + + <step> + <para><command>make install</command></para> + </step> + + <step> + <para><command>make deinstall</command></para> + </step> + + <step> + <para><command>pkg add <replaceable>package-filename</replaceable></command></para> + </step> + + <step> + <para xml:lang="en"><command>make package</command> (as user)</para> + </step> + </procedure> + + <para>確認在任何階段都沒有任何警告出現。</para> + + <para xml:lang="en">Thorough automated testing can be done with + <package role="port">ports-mgmt/tinderbox</package> or + <package role="port">ports-mgmt/poudriere</package> from the + Ports Collection. These applications maintain + <literal>jails</literal> where all of the steps shown above + can be tested without affecting the state of the host + system.</para> + </sect1> + + <sect1 xml:id="porting-portlint"> + <title>以 <command>portlint</command> 來作檢查 Port</title> + + <para>請用 <command>portlint</command> 來檢查該 port 是否有遵循我們的規則。 <package role="port">ports-mgmt/portlint</package> 是 ports collection 的其中一個套件。 它主要可以用來檢驗 <link linkend="porting-samplem">Makefile</link> 內容是否正確以及 <link linkend="porting-pkgname">package</link> 是否有正確命名。</para> + </sect1> + + <sect1 xml:id="porting-submitting"> + <title>提交新的 Port</title> + + <para>提交新的 Port 前，請閱讀 <link linkend="porting-dads">DOs and DON'Ts</link> 章節。</para> + + <para>現在你很高興終於打造出 port 來囉，唯一剩下要做的就是把它正式放到 FreeBSD ports tree 內，才能讓每個人都能分享使用這個 port。 我們不需要 <filename>work</filename> 目錄或是檔名像 <filename>pkgname.tgz</filename> 的 package ，請現在刪除他們。</para> + + <para xml:lang="en">Next, build the <citerefentry><refentrytitle>shar</refentrytitle><manvolnum>1</manvolnum></citerefentry> file. Assuming the port is + called <literal>oneko</literal>, <command>cd</command> to the + directory above where the <literal>oneko</literal> directory + is located, and then type: + <command>shar `find oneko` > oneko.shar</command></para> + + <!-- The link here is wrong, but, I have no idea where + to point it now, so commenting the whole paragraph. + + <para>Include <filename>oneko.shar</filename> in a bug + report and submit it. See <link + xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug + Reports and General Commentary</link> for more information + submitting problem reports.</para> --> + + <para xml:lang="en">To submit <filename>oneko.shar</filename>, use the <link xlink:href="https://bugs.freebsd.org/submit/">bug submit + form</link> (category <literal>Ports Tree</literal>). + Add a short + description of the program to the Description field of the PR + (perhaps a short version of <varname>COMMENT</varname>), and + do not forget to add <filename>oneko.shar</filename> as an + attachment.</para> + + <note> + <para xml:lang="en">Giving a good description in the summary of the problem + report makes the work of port committers a lot easier. We + prefer something like <quote>New port: + <replaceable>category</replaceable>/<replaceable>portname</replaceable> <replaceable>short description of + the port</replaceable></quote> for new ports. Using this + scheme makes it easier and faster to begin the work of + committing the new port.</para> + </note> + + <para>再次強調一點：<emphasis>不必附上原始 source 的 distfile ，也就是 <filename>work</filename> 目錄。 同時，也不必附上 <command>make package</command> 時產生的 package</emphasis>。新的 port 請使用 <citerefentry><refentrytitle>shar</refentrytitle><manvolnum>1</manvolnum></citerefentry> ，不要用 <citerefentry><refentrytitle>diff</refentrytitle><manvolnum>1</manvolnum></citerefentry> 。</para> + + <para>送出 port 之後，請耐心等候佳音。 有時候可能需要等個幾天或幾個月時間，才會在 FreeBSD ports tree 上正式出現。 等待中的 port <acronym>PR</acronym> 清單可以在 <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports"/>; 查閱。</para> + + <para>在看過新的 port 之後，如果需要的話，我們會回覆您，然後會將它提交到 port tree 。 您的大名會被列在 <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/contributors/contrib-additional.html">Additional FreeBSD Contributors</link> 列表上，以及其他檔案中。</para> + </sect1> +</chapter> + + +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> +<chapter version="5.0" xml:id="slow-porting"> + + <title xml:lang="en">Slow Porting</title> + + <para>Ok...事實上並不太可能這麼簡單，port 方面可能需要作些修改才能正常使用。 因此， 本節將一步一步來介紹如何修改上一章的樣本以正常使用。</para> + + <sect1 xml:id="slow-work"> + <title xml:lang="en">How Things Work</title> + + <para xml:lang="en">First, this is the sequence of events which occurs when the + user first types <command>make</command> in the port's + directory. Having + <filename>bsd.port.mk</filename> in another window while + reading this really helps to understand it.</para> + + <para>別太擔心，不是很多人都真的了解 <filename>bsd.port.mk</filename> 在做什麼... <emphasis>:-)</emphasis></para> + + <procedure> + <step> + <para xml:lang="en">The <buildtarget xml:lang="en">fetch</buildtarget> target is run. The + <buildtarget xml:lang="en">fetch</buildtarget> target is responsible for + making sure that the tarball exists locally in + <varname>DISTDIR</varname>. If + <buildtarget xml:lang="en">fetch</buildtarget> cannot find the required + files in <varname>DISTDIR</varname> it will look up the URL + <varname>MASTER_SITES</varname>, 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 <varname>FETCH</varname>, assuming + that the requesting site has direct access to the Internet. + If that succeeds, it will save the file in + <varname>DISTDIR</varname> for future use and + proceed.</para> + </step> + + <step> + <para xml:lang="en">The <buildtarget xml:lang="en">extract</buildtarget> target is run. + It looks for the port's distribution file (typically a + <command>gzip</command>ped tarball) in + <varname>DISTDIR</varname> and unpacks it into a temporary + subdirectory specified by <varname>WRKDIR</varname> + (defaults to <filename>work</filename>).</para> + </step> + + <step> + <para xml:lang="en">The <buildtarget xml:lang="en">patch</buildtarget> target is run. + First, any patches defined in <varname>PATCHFILES</varname> + are applied. Second, if any patch files named + <filename>patch-<replaceable>*</replaceable></filename> are + found in <varname>PATCHDIR</varname> (defaults to the + <filename>files</filename> subdirectory), they are applied + at this time in alphabetical order.</para> + </step> + + <step> + <para xml:lang="en">The <buildtarget xml:lang="en">configure</buildtarget> target is run. + This can do any one of many different things.</para> + + <orderedlist> <listitem> - <para>若該 port 沒裝的東西，不要列在 <filename>pkg-plist</filename> - 內。</para> + <para xml:lang="en">If it exists, <filename>scripts/configure</filename> + is run.</para> </listitem> <listitem> - <para>若該 port 有裝的東西，請務必列在 - <filename>pkg-plist</filename> 內。</para> + <para xml:lang="en">If <varname>HAS_CONFIGURE</varname> or + <varname>GNU_CONFIGURE</varname> is set, + <filename>WRKSRC/configure</filename> is run.</para> </listitem> + </orderedlist> + </step> + + <step> + <para xml:lang="en">The <buildtarget xml:lang="en">build</buildtarget> target is run. + This is responsible for descending into the port's private + working directory (<varname>WRKSRC</varname>) and building + it.</para> + </step> + + <step> + <para xml:lang="en">The <buildtarget xml:lang="en">stage</buildtarget> target is run. + This puts the final set of built files into a temporary + directory (<varname>STAGEDIR</varname>, see + <xref linkend="staging"/>). The hierarchy of this directory + mirrors that of the system on which the package will be + installed.</para> + </step> + + <step> + <para xml:lang="en">The <buildtarget xml:lang="en">package</buildtarget> target is run. + This creates a package using the files from the temporary + directory created during the + <buildtarget xml:lang="en">stage</buildtarget> target and the port's + <filename>pkg-plist</filename>.</para> + </step> + + <step> + <para xml:lang="en">The <buildtarget xml:lang="en">install</buildtarget> target is run. + This installs the package created during the + <buildtarget xml:lang="en">package</buildtarget> target into the host + system.</para> + </step> + </procedure> + + <para xml:lang="en">The above are the default actions. In addition, + define targets + <buildtarget xml:lang="en">pre-<replaceable>something</replaceable></buildtarget> + or + <buildtarget xml:lang="en">post-<replaceable>something</replaceable></buildtarget>, + or put scripts with those names, in the + <filename>scripts</filename> subdirectory, and they will be + run before or after the default actions are done.</para> + + <para xml:lang="en">For example, if there is a + <buildtarget xml:lang="en">post-extract</buildtarget> target defined in the + <filename>Makefile</filename>, and a file + <filename>pre-build</filename> in the + <filename>scripts</filename> subdirectory, the + <buildtarget xml:lang="en">post-extract</buildtarget> target will be called + after the regular extraction actions, and + <filename>pre-build</filename> will be executed before + the default build rules are done. It is recommended to + use <filename>Makefile</filename> 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.</para> + + <para xml:lang="en">The default actions are done by the + <buildtarget xml:lang="en">do-<replaceable>something</replaceable></buildtarget> + targets from <filename>bsd.port.mk</filename>. + For example, the commands to extract a port are in the target + <buildtarget xml:lang="en">do-extract</buildtarget>. If + the default target does not do the job right, redefine the + <buildtarget xml:lang="en">do-<replaceable>something</replaceable></buildtarget> + target in the <filename>Makefile</filename>.</para> + + <note> + <para xml:lang="en">The <quote>main</quote> targets (for example, + <buildtarget xml:lang="en">extract</buildtarget>, + <buildtarget xml:lang="en">configure</buildtarget>, 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 + <buildtarget xml:lang="en">do-extract</buildtarget>, but never ever change + the way <buildtarget xml:lang="en">extract</buildtarget> operates! + Additionally, the target + <buildtarget xml:lang="en">post-deinstall</buildtarget> is invalid and is + not run by the ports infrastructure.</para> + </note> + + <para xml:lang="en">Now that what goes on when the user types <command>make + install</command> is better understood, let us go through the + recommended steps to create the perfect port.</para> + </sect1> + + <sect1 xml:id="slow-sources"> + <title>取得原始碼</title> + + <para xml:lang="en">Get the original sources (normally) as a compressed tarball + (<filename>foo.tar.gz</filename> or + <filename><replaceable>foo</replaceable>.tar.bz2</filename>) and + copy it into <varname>DISTDIR</varname>. Always use + <emphasis>mainstream</emphasis> sources when and where + possible.</para> + + <para xml:lang="en">Set the variable + <varname>MASTER_SITES</varname> to reflect where the original + tarball resides. Shorthand definitions exist + for most mainstream sites in <filename>bsd.sites.mk</filename>. + 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 + <xref linkend="makefile-master_sites"/> for details.</para> + + <para xml:lang="en">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).</para> + + <para xml:lang="en">If a convenient and reliable place to put + the distfile cannot be found, we can <quote>house</quote> it ourselves on + <systemitem>ftp.FreeBSD.org</systemitem>; however, this is the + least-preferred solution. The distfile must be placed into + <filename>~/public_distfiles/</filename> of someone's + <systemitem>freefall</systemitem> account. Ask the person who + commits the port to do this. This person will also set + <varname>MASTER_SITES</varname> to + <literal>LOCAL/<replaceable>username</replaceable></literal> + where <literal><replaceable>username</replaceable></literal> is + their FreeBSD cluster login.</para> + + <para xml:lang="en">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 + <varname>MASTER_SITES</varname>. 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 + <errorname>checksum mismatch</errorname> 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 + <varname>MASTER_SITES</varname>.</para> + + <para xml:lang="en">If the port requires additional patches that are + available on the Internet, fetch them too and put them in + <varname>DISTDIR</varname>. 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 <link linkend="porting-patchfiles">PATCHFILES</link> below).</para> + </sect1> + + <sect1 xml:id="slow-modifying"> + <title xml:lang="en">Modifying the Port</title> + + <para xml:lang="en">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 + <emphasis>careful track</emphasis> 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.</para> + + <para xml:lang="en">If the port requires significant user + interaction/customization to compile or install, take + a look at one of Larry Wall's classic + <application>Configure</application> scripts and perhaps do + something similar. The goal of the new ports + collection is to make each port as <quote>plug-and-play</quote> + as possible for the end-user while using a minimum of disk + space.</para> + + <note> + <para xml:lang="en">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.</para> + </note> + </sect1> + + <sect1 xml:id="slow-patch"> + <title xml:lang="en">Patching</title> + + <para xml:lang="en">In the preparation of the port, files that have been added + or changed can be recorded with <citerefentry><refentrytitle>diff</refentrytitle><manvolnum>1</manvolnum></citerefentry> for later feeding + to <citerefentry><refentrytitle>patch</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Doing this with a typical file involves + saving a copy of the original file before making any changes + using a <filename>.orig</filename> suffix.</para> + + <screen><prompt>%</prompt> <userinput>cp <replaceable>file</replaceable> <replaceable>file</replaceable>.orig</userinput></screen> + + <para xml:lang="en">After all changes have been made, <command>cd</command> back + to the port directory. Use <command>make makepatch</command> to + generate updated patch files in the <filename>files</filename> + directory.</para> + + <sect2 xml:id="slow-patch-rules"> + <title xml:lang="en">General Rules for Patching</title> + + <para xml:lang="en">Patch files are stored in <varname>PATCHDIR</varname>, + usually <filename>files/</filename>, from where they will be + automatically applied. All patches must be relative to + <varname>WRKSRC</varname>. Typically + <varname>WRKSRC</varname> is a subdirectory of + <varname>WRKDIR</varname>, the directory where the distfile is + extracted. Use <command>make -V WRKSRC</command> to see the + actual path. The patch names are to follow these + rules:</para> + + <itemizedlist> + <listitem> + <para xml:lang="en">Avoid having more than one patch modify the same file. + For example, having both + <filename>patch-foobar.c</filename> and + <filename>patch-foobar.c2</filename> making changes to + <filename>${WRKSRC}/foobar.c</filename> makes them fragile + and difficult to debug.</para> + </listitem> + + <listitem> + <para xml:lang="en">When creating names for patch files, replace each + underscore (<literal>_</literal>) with two underscores + (<literal>__</literal>) and each slash + (<literal>/</literal>) with one underscore + (<literal>_</literal>). For example, to patch a file + named <filename>src/freeglut_joystick.c</filename>, name + the corresponding patch + <filename>patch-src_freeglut__joystick.c</filename>. Do + not name patches like <filename>patch-aa</filename> or + <filename>patch-ab</filename>. Always use the path and + file name in patch names. Using <command>make + makepatch</command> automatically generates the correct + names.</para> + </listitem> + + <listitem> + <para xml:lang="en">A patch may modify multiple files if the changes are + related and the patch is named appropriately. For + example, + <filename>patch-add-missing-stdlib.h</filename>.</para> + </listitem> + + <listitem> + <para xml:lang="en">Only use characters <literal>[-+._a-zA-Z0-9]</literal> + for naming patches. In particular, <emphasis>do not use + <literal>::</literal> as a path separator,</emphasis> + use <literal>_</literal> instead.</para> + </listitem> + </itemizedlist> + + + <para xml:lang="en">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.</para> + + <para xml:lang="en">If a file must be deleted, do it in the + <buildtarget xml:lang="en">post-extract</buildtarget> target rather than as + part of the patch.</para> + + </sect2> + + <sect2 xml:id="slow-patch-manual"> + <title xml:lang="en">Manual Patch Generation</title> + + <note> + <para xml:lang="en">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 ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201603290137.u2T1brrn001508>