aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKevin Lo <kevlo@FreeBSD.org>2016-03-29 01:37:53 +0000
committerKevin Lo <kevlo@FreeBSD.org>2016-03-29 01:37:53 +0000
commit1b0aa226832823e8229b37a5ec46f29a00cd14b8 (patch)
treebe7a07eda7000b079f1e26a965af30c0a24de7dc
parent30264ed39e6ca8bd1002517bcfea20c295a129d4 (diff)
downloaddoc-1b0aa22683.tar.gz
doc-1b0aa22683.zip
Push recent translations.
Submitted by: https://reviews.freebsd.org/D5570 Reviewed by: wblock Differential Revision: https://reviews.freebsd.org/D5570
Notes
Notes: svn path=/head/; revision=48496
-rw-r--r--zh_TW.UTF-8/books/porters-handbook/book.xml32689
-rw-r--r--zh_TW.UTF-8/books/porters-handbook/zh_TW.po37193
2 files changed, 58610 insertions, 11272 deletions
diff --git a/zh_TW.UTF-8/books/porters-handbook/book.xml b/zh_TW.UTF-8/books/porters-handbook/book.xml
index 87819b620c..121847268d 100644
--- a/zh_TW.UTF-8/books/porters-handbook/book.xml
+++ b/zh_TW.UTF-8/books/porters-handbook/book.xml
@@ -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>
-
- <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>
+ <pubdate>$FreeBSD$</pubdate>
- &trademarks;
+ <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>
- &legalnotice;
+
+<legalnotice xml:id="legalnotice">
+ <title>版權所有</title>
+
+ <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
+
+ $FreeBSD$
+-->
+<chapter version="5.0" xml:id="why-port">
- <para>幾乎每個 FreeBSD 愛用者都是透過 FreeBSD Ports Collection
- 來裝各式應用程式("ports")。如同 FreeBSD 的其他部分一樣,
- 這些 ports 都主要來自許多志工的努力成果,所以在閱讀這份文件時,
- 請務必感恩在心。</para>
+ <title>楔子</title>
- <para>在 FreeBSD 上面,每個人都可以提交新的 port,
- 或假如該 port 並沒有人維護的話,可以自願維護 &mdash;
- 這點並不需要任何 commit 的權限,就可以來做這件事情。</para>
+ <para>幾乎每個 FreeBSD 愛用者都是透過 FreeBSD Ports Collection 來裝各式應用程式("ports")。如同 FreeBSD 的其他部分一樣, 這些 ports 都主要來自許多志工的努力成果,所以在閱讀這份文件時, 請務必感恩在心。</para>
- </chapter>
+ <para>在 FreeBSD 上面,每個人都可以提交新的 port, 或假如該 port 並沒有人維護的話,可以自願維護 —— 這點並不需要任何 commit 的權限,就可以來做這件事情。</para>
+</chapter>
- <chapter xml:id="own-port">
- <title>自行打造 port</title>
- <para>那麼,開始對自行製作 port 或更新有一些興趣了嗎?太好囉!</para>
+
+<!--
+ The FreeBSD Documentation Project
- <para>下面將介紹一些建立 port 時該注意的事項。如果是想升級現有的 port
- ,那麼也請參閱 <xref linkend="port-upgrading"/> 說明。</para>
+ $FreeBSD$
+-->
- <para>因為這份文件可能講得不是十分詳細,可能需要參考
- <filename>/usr/ports/Mk/bsd.port.mk</filename> 這檔是所有 port 的
- Makefile 檔都會用到的。 就算你不是每天不斷 hacking Makefiles
- ,也都可以藉由它來對整個 port 機制、Makefile 更瞭解,
- 裡面的註釋相當詳細。 此外,若有其他特定 port 的問題,也可以到
- &a.ports; 來獲得答案。</para>
+<chapter version="5.0" xml:id="own-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>製作新的 Port</title>
- <chapter xml:id="quick-porting">
- <title>打造 Port 快速上手篇</title>
+ <para>開始對製作新的 port 或更新現有 port 有一些興趣了嗎?太好囉!</para>
- <para>本節主要介紹如何來快速打造 port,然而,
- 很多時候這些內容並不是很夠用,建議閱讀本文件中更深奧的地方。</para>
+ <para>下面將介紹一些建立 port 時該注意的事項。如果是想升級現有的 port ,那麼也請參閱 <xref linkend="port-upgrading"/> 說明。</para>
- <para>首先取得該應用程式的原始程式碼壓縮檔(tarball),並把它放到
- <varname>DISTDIR</varname>,預設路徑應該是
- <filename>/usr/ports/distfiles</filename>。</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>下面的例子,是假設並不需要再修改該應用程式的原始碼,就可以在
- FreeBSD 上編譯成功的;假如還需要另外修改才能成功編譯的話,
- 那麼請參考下一章的說明。</para>
- </note>
+ <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>
- <sect1 xml:id="porting-makefile">
- <title>編寫 <filename>Makefile</filename></title>
+ <para>想要找簡單的開始上手嗎? 到 <link xlink:href="http://wiki.freebsd.org/WantedPorts">請求協助的 ports 清單</link> 瞧瞧,看看是否有你可以幫上忙的。</para>
+</chapter>
- <para>最簡單的 <filename>Makefile</filename> 大概是像這樣:</para>
- <programlisting># New ports collection makefile for: oneko
-# Date created: 5 December 1994
-# Whom: asami
-#
-# &dollar;FreeBSD&dollar;
-#
+
+<!--
+ The FreeBSD Documentation Project
-PORTNAME= oneko
-PORTVERSION= 1.1b
-CATEGORIES= games
-MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
+ $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>
-MAINTAINER= asami@FreeBSD.org
-COMMENT= A cat chasing a mouse all over the screen
+ <screen xml:lang="en"><prompt>#</prompt> <userinput>echo DEVELOPER=yes &gt;&gt; /etc/make.conf</userinput></screen>
-MAN1= oneko.1
-MANCOMPRESSED= yes
-USE_IMAKE= yes
+ <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 &lt;bsd.port.mk&gt;</programlisting>
- <para>嗯,大致就是這樣,看看你已經領略多少了呢?
- 看到 <literal>&dollar;FreeBSD&dollar;</literal> 這一行的話,別想太多
- ,它是 RCS ID 用途,當該 port 正式進入 port tree 時,
- CVS 就會自動轉換為相關字串囉。 有關這點的細節部份,可以參閱 <link linkend="porting-samplem">sample Makefile</link> 章節。</para>
- </sect1>
+ <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>
- <sect1 xml:id="porting-desc">
- <title>撰寫該軟體的說明檔</title>
+ <para>嗯,大致就是這樣,看看你已經領略多少了呢? 看到 <literal>$FreeBSD$</literal> 這一行的話,別想太多 ,當該 port 正式進入 port tree 時, <application>Subversion</application> 就會自動轉換為相關字串囉。 有關這點的細節部份,可以參閱 <link linkend="porting-samplem">sample Makefile</link> 章節。</para>
+ </sect1>
- <para>無論是否打算再加工做成 package,有 2 個檔案是任何實體 port (Slave
- port則不一定)都必須要具備的。 這 2 個檔分別是
- <filename>pkg-descr</filename> 檔及 <filename>pkg-plist</filename>
- 檔。 這兩個檔案檔名前面都有 <filename>pkg-</filename>
- 以跟其他檔案做區別。</para>
+ <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>
+
+ <note>
+ <para>請注意,這檔<emphasis>絕非</emphasis>「該軟體的說明手冊」或是「如何編譯、使用該 port 的說明」! <emphasis>若是從該軟體的 <filename>README</filename> 或 manpage 直接複製過來的話,請注意</emphasis>。他們常常不是正確的 port 描述或是格式並不適合。例如,manpage會對齊空白,這用monospace字型來看會特別糟糕。</para>
+ </note>
- <para>該 port 的 <filename>pkg-descr</filename> 內容,大致如下面例子
- :</para>
+ <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>
- <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 的 <filename>pkg-plist</filename> 內容,
- 大致如下面例子:</para>
-
- <programlisting>bin/oneko
+ </sect2>
+
+ <sect2 xml:id="porting-pkg-plist">
+ <title><filename>pkg-plist</filename></title>
+
+ <para>這是該 port 所會裝的所有檔案清單,另外因為 package 會由這清單所產生,因此也被稱為『<quote>packing list (打包清單)</quote>』。路徑是相對於安裝的 prefix (通常是 <filename>/usr/local</filename> )。</para>
+
+ <para>這是一個簡單的例子:</para>
+
+ <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> 及
- <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>
-
- <sect1 xml:id="porting-testing">
- <title>檢驗 port 是否完整、可行</title>
-
- <para>接下來,必須檢驗是否有符合 port 的遊戲規則,包括打包該 port
- 為 package。 以下有幾個需要確認的重要地方:</para>
+ <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>
- <itemizedlist>
- <listitem>
- <para>若該 port 沒裝的東西,不要列在 <filename>pkg-plist</filename>
- 內。</para>
- </listitem>
+ <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>
- <listitem>
- <para>若該 port 有裝的東西,請務必列在
- <filename>pkg-plist</filename> 內。</para>
- </listitem>
+ <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>
+ <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>
+
+ <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>後面會介紹到如何運用 <filename>pkg-plist</filename>、 <varname>PLIST_FILES</varname> 這些技巧以因應<link linkend="plist">更複雜的狀況</link>。</para>
+ </sect2>
+ </sect1>
+
+ <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` &gt; 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 可以用 <command>reinstall</command> 來重新安裝
- 。</para>
+ <para xml:lang="en">If it exists, <filename>scripts/configure</filename>
+ is run.</para>
</listitem>
<listitem>
- <para>該 port 在移除之後,確定都可 <link linkend="plist-cleaning">cleans up</link>。</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>
- </itemizedlist>
+ </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>
- <procedure>
- <title>建議的測試步驟順序:</title>
-
- <step>
- <para><command>make install</command></para>
- </step>
-
- <step>
- <para><command>make package</command></para>
- </step>
-
- <step>
- <para><command>make deinstall</command></para>
- </step>
-
- <step>
- <para><command>pkg_add package-name
- </command></para>
- </step>
-
- <step>
- <para><command>make deinstall</command></para>
- </step>
-
- <step>
- <para><command>make reinstall</command></para>
- </step>
-
- <step>
- <para><command>make package</command></para>
- </step>
- </procedure>
-
- <para>確認在 <buildtarget>package</buildtarget> 和
- <buildtarget>deinstall</buildtarget> 這兩個階段都沒有任何錯誤訊息出現。
- 完成第三步驟之後,檢查一下是否所裝的檔案、目錄都有移除完畢。 此外,
- 第四步驟完成後,也檢查一下以 package 裝的該軟體,是否都能正常運作
- 。</para>
-
- <para>最周密的自動方式就是透過裝
- <application>ports tinderbox</application>。 它會建立
- <literal>jails</literal> 並管理之,以便您可以測試上述所有步驟,
- 而不會真正影響您本身的作業系統。 詳情請參考
- <filename>ports/ports-mgmt/tinderbox</filename>。</para>
- </sect1>
-
- <sect1 xml:id="porting-portlint">
- <title>以 <command>portlint</command> 來作檢驗</title>
-
- <para>請用 <command>portlint</command> 來檢查該 port
- 是否有遵循上述遊戲規則。 說到這
- <package>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>提交(Submit) port</title>
-
- <para>首先,請確認是否有瞭解 <link linkend="porting-dads">DOs and DON'Ts</link> 該章部分。</para>
-
- <para>現在你很高興終於打造出 port 來囉,唯一剩下要做的就是把它正式放到
- FreeBSD ports tree 內,才能讓每個人都能分享使用這個 port。 請先拿掉
- <filename>work</filename> 目錄或檔名像是
- <filename>pkgname.tgz</filename> 的 package 可以砍掉。 接著,
- 只要用 <command>shar `find port_dir`</command> 來產生 shar 格式,
- 並配合 &man.send-pr.1; 程式以提交出去。(&man.send-pr.1;
- 的部分可以參閱 <link xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">
- 錯誤報告和意見發表</link>)</para>
-
- <para>記得在填寫 PR 時『分類(Category)』選 <literal>ports</literal>,
- 還有『種類(Class)』填 <literal>change-request</literal>
- (千萬別傻傻地把該 PR 的『Confidential(機密)』設為 yes!),
- 此外在『描述(<quote>Description</quote>)』
- 那邊寫上該程式的簡潔說明,而 shar 檔則附在『修正(<quote>Fix</quote>)
- 』欄位內。</para>
+ <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>
- <note>
- <para>若 Synopsis 欄清楚描述該 PR 重點的話,那麼會讓整個流程更為順暢。
- new ports 的話,我們習慣用:
- <quote>New port: &lt;category&gt;/&lt;portname&gt;
- &lt;該 port 的簡介&gt;</quote> ,而更新 port 的話,則是
- <quote>Update port: &lt;category&gt;/&lt;portname&gt;
- &lt;本次 update 的簡介&gt;</quote>。
- 若你也採用這樣的格式的話,那麼會被受理的機會就會越高囉。</para>
- </note>
+ <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>
- <para>再次強調一點:<emphasis>不必附上原始 source 的 distfile
- ,也就是 <filename>work</filename> 目錄。 同時,也不必附上
- <command>make package</command> 時產生的 package</emphasis>。</para>
-
- <para>送出 port 之後,請耐心等候佳音。
- 有時候可能需要等個幾天或幾個月時間,才會在 FreeBSD ports tree
- 上正式出現。 此外,隨時可以查閱 <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports">
- 等待 committed to FreeBSD 的 port</link> 列表。</para>
-
- <para>一旦我們開始處理你送來的 port 之後,如果有一些意見需要溝通的話,
- 那麼會先 feedback 給你,
- 之後確定都沒問題,就會放到 port tree 內囉!
- 你的大名會被記在 <link xlink:href="&url.articles.contributors;/contrib-additional.html">Additional FreeBSD Contributors</link>
- 列表上,以及其他檔案。聽起來,挺不賴的不是嗎!? <!-- smiley
- -->:-)</para>
- </sect1>
- </chapter>
-
- <chapter xml:id="slow">
- <title>Slow Porting</title>
-
- <para>Ok...事實上並不太可能這麼簡單,port
- 方面可能需要作些修改才能正常使用。 因此,
- 本節將一步一步來介紹如何修改上一章的樣本以正常使用。</para>
-
- <sect1 xml:id="slow-work">
- <title>How things work</title>
-
- <para>首先,先介紹一下在你所作的 port 目錄內打 <command>make</command>
- 時,所會作哪些事情的順序吧。
- 你可以另開一窗來看 <filename>bsd.port.mk</filename>
- 內容,以便瞭解我們下面在講什麼。</para>
-
- <para>但別太擔心是否完全看懂
- <filename>bsd.port.mk</filename> 在做啥,很多人都還沒完全看完...
- <!-- smiley --><emphasis>:-&gt;</emphasis></para>
-
- <procedure>
-
- <step>
- <para>首先,進行 <buildtarget>fetch</buildtarget> 階段。
- <buildtarget>fetch</buildtarget> 是確認 tarball 檔有沒有已在
- <varname>DISTDIR</varname> 內了?若 <buildtarget>fetch</buildtarget>
- 在 <varname>DISTDIR</varname> 找不到的話,它會搜尋 Makefile
- 內的 <varname>MASTER_SITES</varname> URL
- ,或者是主 FTP 站專門放備份 distfiles 的目錄 <uri xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/">ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/</uri>
- 。 假設都找不到的話,但是網路有接上 Internet 的話,它會試著用
- <varname>FETCH</varname> 來抓所指定的檔案。
- 抓到之後,它會把檔案存到 <varname>DISTDIR</varname>
- 以便開始使用或日後運用。</para>
- </step>
-
- <step>
- <para>其次,進行 <buildtarget>extract</buildtarget> 階段,它會從
- <varname>DISTDIR</varname> 內找出該 port 所需的檔案(通常是 gzip
- 格式的 tarball),然後解壓縮到 <varname>WRKDIR</varname>
- 所設定的臨時目錄名稱(預設是 <filename>work</filename> 目錄)內
- 。</para>
- </step>
-
- <step>
- <para>之後,進行 <buildtarget>patch</buildtarget> 階段,
- 一開始會先套用 <varname>PATCHFILES</varname> 所指定的任何 patch
- 檔。 接著是 <varname>PATCHDIR</varname>(預設是
- <filename>files</filename> 子目錄) 內的檔名為
- <filename>patch-*</filename>
- 之類的檔案,會以字母順序而逐一套用 patch。</para>
- </step>
-
- <step>
- <para>接著是 <buildtarget>configure</buildtarget> 階段,可以照 port
- 的類型來作各種不同設定以調整,比如:</para>
+ <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>
- <orderedlist>
- <listitem>
- <para>若有放 <filename>scripts/configure</filename> 的話,
- 那麼就會跑裡面的設定。</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>若有設 <varname>HAS_CONFIGURE</varname> 或是
- <varname>GNU_CONFIGURE</varname> 的話,那麼就會跑
- <filename>WRKSRC/configure</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>
- <listitem>
- <para>若有設 <varname>USE_IMAKE</varname> 的話,那麼就會跑
- <varname>XMKMF</varname> (預設是 <command>xmkmf
- -a</command>) 。</para>
- </listitem>
- </orderedlist>
- </step>
-
- <step>
- <para>最後是 <buildtarget>build</buildtarget> 階段,它會在該
- port 的 working directory(由 <varname>WRKSRC</varname> 所設定)
- 內開始編譯。 若有設 <varname>USE_GMAKE</varname> 的話,
- 那麼就會改用 GNU <command>make</command> 來編譯,
- 否則就用系統本身的 <command>make</command> 來編譯。</para>
- </step>
- </procedure>
-
- <para>上面講的都是打 <command>make</command> 時的預設階段。
- 此外,還可以設定各階段之前、之後要作的事情:透過定義
- <buildtarget>pre-<replaceable>something</replaceable></buildtarget> 或
- <buildtarget>post-<replaceable>something</replaceable></buildtarget>,
- 或者把這些檔名的 script 丟到 <filename>scripts</filename> 子目錄去,
- 這樣子它們就會在各預設階段的之前、之後進行囉。</para>
-
- <para>舉例來說,若在 <filename>Makefile</filename> 內設定
- <buildtarget>post-extract</buildtarget>,而且在
- <filename>scripts</filename> 子目錄內又有
- <filename>pre-build</filename> 檔的話,那麼在作解壓縮之後,就會開始
- <buildtarget>post-extract</buildtarget> 階段以進行解壓縮後的後續動作,
- 而在跑 build 階段之前,就會先執行 <filename>pre-build</filename>
- 這隻 script 作先期準備。 通常較簡單的修改動作,建議直接放在
- <filename>Makefile</filename> 內就好了,
- 因為這樣會比較方便加上這些原本沒有的階段,同時也方便他人協助除錯
- 。</para>
-
- <para>預設的各階段動作都是照 <filename>bsd.port.mk</filename> 內的
- <buildtarget>do-<replaceable>something</replaceable></buildtarget>
- 之類所定義的。 舉例:<buildtarget>do-extract</buildtarget>
- 就是定義怎麼把檔案解壓縮的。
- 若對預設方式覺得不妥的話,都可以在該 port 的
- <filename>Makefile</filename> 重新定義。</para>
- <note>
- <para>The <quote>main</quote> targets (e.g.,
- <buildtarget>extract</buildtarget>,
- <buildtarget>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. If you want to fix the extraction, fix
- <buildtarget>do-extract</buildtarget>, but never ever change
- the way <buildtarget>extract</buildtarget> operates!</para>
- </note>
+ <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>現在,你已經知道打 <command>make</command> 到底會作些什麼事囉,
- 接下來會教你如何作更完美的 port。</para>
- </sect1>
-
- <sect1 xml:id="slow-sources">
- <title>取得原始的 source 檔</title>
-
- <para>取得原始的 source 檔(通常檔名是
- <filename>foo.tar.gz</filename>
- 或 <filename>foo.tar.Z</filename>
- 之類的壓縮檔),然後會把抓下來的檔案放在 <varname>DISTDIR</varname>
- 內。 記得:抓的時候,儘量使用『該軟體主要的正式網站』上面的來源檔
- ,以確保檔案有效、可信。</para>
-
- <para>需要設 <varname>MASTER_SITES</varname> 以指定原始檔案是放在何處。
- 相關網址在 <filename>bsd.sites.mk</filename>
- 內有一些方便的速記表可以使用。 請盡可能多用對應這些網址的變數,
- 以避免同樣的一堆網址有重複很多次出現在 port tree 內。
- 否則,這些網址只要一有改變的話,那麼就會成為維護 port 的夢魘。</para>
-
- <para>如果該檔並沒有放在公開的 FTP 站或網站(HTTP)上,
- 或者該檔並非一般標準格式的話,
- 那麼可以考慮複製該檔,然後放到你可掌握、可信任的 FTP 站或網站(HTTP)
- 上,比如:你自己的網頁空間。</para>
-
- <para>若找不到地方(方便、可信任)來放檔案的話,
- 那麼可以 <quote>house(暫放)</quote> 在
- <systemitem>ftp.FreeBSD.org</systemitem> 上的 committer 自屬空間內;
- 然而,這是最不理想的解法。
- 檔案要放到該 committer 的 <systemitem>freefall</systemitem> 上的
- <filename>~/public_distfiles/</filename> 目錄內才可以。
- 請與協助 commit 你的 port 的那位 committer 聯繫,
- 以便把檔案放到他的目錄內。
- 那位 committer 同時也會把 <varname>MASTER_SITES</varname> 設為
- <varname>MASTER_SITE_LOCAL</varname>,並且把
- <varname>MASTER_SITE_SUBDIR</varname> 設為他自己的
- <systemitem>freefall</systemitem> 帳號名稱。</para>
-
- <para>若該 port 的原始檔打包會經常重包,但原作者卻沒更新版號的話,
- 請考慮把該檔改放到自己的網頁空間,並且把自己網頁空間列為
- <varname>MASTER_SITES</varname> 的第一順位。
- 或者請與原作者聯繫:請他不要這樣做(不斷重包同樣的檔案);如此一來,
- 才有助於建立一定程度的 source code 版本控制。
- 把檔案另外複製一份放到自屬網頁空間的話,不但可有效防止使用者會發生
- <errorname>checksum mismatch(檔案經檢查有問題)</errorname>
- 的錯誤訊息,也可降低我們 FTP 站維護者的工作量。此外,若該 port
- 的檔案僅有一個主要網址,
- 那麼建議:請在自屬網站上放上備份檔,並修改
- <varname>MASTER_SITES</varname> 把你的網址列為第二順位。</para>
-
- <para>若該 port 需要一些額外 `patches'(可透過 Internet 下載),並放在
- <varname>DISTDIR</varname> 內,不必擔心這些 patch
- 檔是否得都跟原始檔一樣來自同一網站,
- 這些情況有另外的解法(請看下面的 <link linkend="porting-patchfiles">PATCHFILES</link> 介紹部分)。</para>
- </sect1>
-
- <sect1 xml:id="slow-modifying">
- <title>量身打造 port</title>
-
- <para>解開壓縮檔,然後開始逐一修改,使該 port 在目前所用的 FreeBSD
- 版本上得以順利編譯。
- 所做的每個動作請都 <emphasis>仔細記錄</emphasis>,
- 如此一來才能迅速自動套用這些修改。
- 在完成 port 之後,每項動作包括:對於檔案的刪除、增加、修改,
- 要記得存為自動化的 script 或者 patch 檔形式,以利他人直接套用。</para>
-
- <para>若該 port 需要使用者的互動、自訂功能來編譯、安裝的話,
- 那麼建議揣摩看看 Larry Wall 的經典之作
- <application>Configure</application> scripts 來完成類似效果。
- Ports collection 的目的之一,就是讓每個 port 儘量用最小空間,
- 來做出軟體的 <quote>plug-and-play(即插即用)</quote>。</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>
- <note>
- <para>除非有明確聲明,否則你所提交給 FreeBSD ports collection 的
- patch 檔、相關 script 檔及其他檔案,都會假設是以標準的 BSD
- 版權形式來發佈。</para>
- </note>
- </sect1>
-
- <sect1 xml:id="slow-patch">
- <title>Patching</title>
-
- <para>在 port 的準備過程中,新增或變更過的檔案,
- 可以利用 &man.diff.1; 將這些變動列出,
- 以便後續讓 &man.patch.1; 使用。
- 所有你想套用的 patch 都應該命名為
- <filename>patch-*</filename>,其中
- <replaceable>*</replaceable> 表示要 patch 檔案的路徑及檔名名稱,
- 例如 <filename>patch-Imakefile</filename> 或
- <filename>patch-src-config.h</filename>。
- 這些檔案都應該儲存在 <varname>PATCHDIR</varname>
- (通常是 <filename>files/</filename>,放在其內的檔案都會自動被套用。
- 所有 patch 檔路徑都是相對於
- <varname>WRKSRC</varname> (通常會將 port 的 tarball 解壓到裡面,
- port 的建置也會在這裡完成)。
- 為了能讓修正和更新更順利,你應該避免多個 patch 修正同一個檔案
- (舉例來說,<filename>patch-file</filename> 和
- <filename>patch-file2</filename> 同時更動
- <filename>WRKSRC/foobar.c</filename>)。</para>
-
- <para>請只使用 <literal>[-+._a-zA-Z0-9]</literal> 這些字元來命名
- patch 檔,不要使用這些字元以外的字元。
- 千萬不要將你的 patch 檔命名成 <filename>patch-aa</filename> 或是
- <filename>patch-ab</filename> 等名稱,
- 請使用路徑和名稱相關的命名。</para>
-
- <para>不要將 RCS 字串放進你的 patch 檔。CVS 會在這些檔案送入
- ports tree 的時候弄亂檔案內容,而且在將它們重新 check out
- 出來後,會因檔案內容的差異造成 patch 失敗。
- RCS 字串是以錢字號 (<literal>&dollar;</literal>) 括起來的,
- 通常以 <literal>&dollar;Id</literal> 或
- <literal>&dollar;RCS</literal> 為開頭。</para>
-
- <para>你可以使用 &man.diff.1; 搭配 recurse (<option>-r</option>) 選項
- 來產生 patch 檔,但請再次檢視產生出的 patch 檔,確保你沒有產生
- 任何不必要的垃圾資訊在裡面。特別是對那些經由
- <command>Imake</command> 或 GNU <command>configure</command>
- 所產生的 <filename>Makefile</filename> 檔產生 patch,
- 都是不必要的,這類的 patch 檔都應該被刪除。假如你必須透過修改
- <command>configure.in</command> 再執行
- <command>autoconf</command> 來重新產生
- <command>configure</command>,不要對
- <command>configure</command> 產生 patch 檔 (這往往會長成數千行!);
- 請定義 <literal>USE_AUTOTOOLS=autoconf:261</literal> 並對
- <filename>configure.in</filename> 產生 patch 檔。</para>
-
- <para>請儘量不要對無用的 whitespace 作修改,因為在 Open Source 界各個
- project 都會使用很多相同的 code base,這些可能卻是採用不同的編排方式
- 、coding style。 若要試圖改變這些編排風格的話,請小心:
- 這些只會是徒勞無功的更改。 此外不僅會造成 CVS repository 空間浪費,
- 也會讓人難以找出真正問題癥結所在,以及分辨不出這段 patch 到底在作什麼
- 。</para>
-
- <para>假如你必須刪除一個檔案,那麼你可以在
- <buildtarget>post-extract</buildtarget> 階段做這件事,
- 而不是在 patch 階段。</para>
-
- <para>你可以直接在 port 的
- <filename>Makefile</filename> 中完成簡單的置換工作,只需使用
- &man.sed.1; 的 in-place mode 即可。這在只需 patch 一個變數的值時相當有用。
- 例如:</para>
-
- <programlisting>post-patch:
- @${REINPLACE_CMD} -e 's|for Linux|for FreeBSD|g' ${WRKSRC}/README
- @${REINPLACE_CMD} -e 's|-pthread|${PTHREAD_LIBS}|' ${WRKSRC}/configure</programlisting>
-
- <para>在移植軟體時,特別是那些在 &windows; 平台開發的軟體,
- 時常會遇到一種情況,就是在大部份的 source file 中,
- 使用 CR/LF 做為斷行。這會影響往後的 patching、compiler warnings、以及
- scripts execution (找不到 <command>/bin/sh^M</command> 的情況) 等。
- 為了快速轉換 CR/LF 為 LF,可以把
- <literal>USE_DOS2UNIX=yes</literal> 加到 port 的
- <filename>Makefile</filename> 檔中。
- 你也可以設定成只針對指定的檔案做轉換:</para>
-
- <programlisting>USE_DOS2UNIX= util.c util.h</programlisting>
-
- <para>若想要轉換所有子目錄內的某類別檔案,可以使用
- <varname>DOS2UNIX_REGEX</varname>。 它的參數是
- <command>find</command> 相容的正規表達式。 相關格式可參閱
- &man.re.format.7;。 對於所指定副檔名的檔案之轉換而言,這相當好用,
- 舉例來說,只動所有原始碼部分而不改 binary 檔案:</para>
-
- <programlisting>USE_DOS2UNIX= yes
-DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting>
- </sect1>
-
- <sect1 xml:id="slow-configure">
- <title>設定</title>
-
- <para>將任何額外的自訂指令包含進你的
- <filename>configure</filename> script 中,且將它儲存在
- <filename>scripts</filename> 的子資料夾裡。 如同上面提到的,
- 你也可以在 <filename>Makefile</filename> 或者是在
- 名稱為 <filename>pre-configure</filename> 或
- <filename>post-configure</filename> 的 script 檔中做同樣的事。</para>
- </sect1>
-
- <sect1 xml:id="slow-user-input">
- <title>處理使用者輸入</title>
-
- <para>如果該 port 需要使用者作出選擇才能安裝的話,
- 則必須在 <filename>Makefile</filename> 加上
- <varname>IS_INTERACTIVE</varname> 變數。 如此一來若使用者有設定
- <envar>BATCH</envar> 環境變數的話,就會略過該 port 而繼續
- <quote>overnight builds</quote>(若使用者把該環境變數值設為
- <envar>BATCH</envar> 的話,那麼 <emphasis>只有</emphasis>
- 那些需要與使用者互動的 port 才會編譯。)。
- 這使得那些需要不停編譯 port 的機器會省下許多時間(後面會說明這點)
- 。</para>
-
- <para>此外建議,若是這些互動問題有合適的預設選項的話,
- 那應確認一下 <varname>PACKAGE_BUILDING</varname> 變數該如何設,
- 才能配合該變數而決定是否停止互動。 如此一來才可以自動編譯出
- CDROM 與 FTP 上的套件。</para>
- </sect1>
- </chapter>
-
- <chapter xml:id="makefile">
- <title>設定 Makefile</title>
-
- <para>設定 <filename>Makefile</filename> 是件非常簡單的事,
- 建議您在開始前,先看看範例。Also, there is a
- <link linkend="porting-samplem">sample Makefile</link> in this
- handbook, so take a look and please follow the ordering of variables
- and sections in that template to make your port easier for others to
- read.</para>
-
- <para>Now, consider the following problems in sequence as you design
- your new <filename>Makefile</filename>:</para>
-
- <sect1 xml:id="makefile-source">
- <title>The original source</title>
-
- <para>Does it live in <varname>DISTDIR</varname> as a standard
- gzip'd tarball named something like
- <filename>foozolix-1.2.tar.gz</filename>? If so, you can go on
- to the next step. If not, you should look at overriding any of
- the <varname>DISTVERSION</varname>, <varname>DISTNAME</varname>,
- <varname>EXTRACT_CMD</varname>,
- <varname>EXTRACT_BEFORE_ARGS</varname>,
- <varname>EXTRACT_AFTER_ARGS</varname>,
- <varname>EXTRACT_SUFX</varname>, or <varname>DISTFILES</varname>
- variables, depending on how alien a format your port's
- distribution file is. (The most common case is
- <literal>EXTRACT_SUFX=.tar.Z</literal>, when the tarball is
- condensed by regular <command>compress</command>, not
- <command>gzip</command>.)</para>
-
- <para>In the worst case, you can simply create your own
- <buildtarget>do-extract</buildtarget> target to override the
- default, though this should be rarely, if ever,
- necessary.</para>
- </sect1>
-
- <sect1 xml:id="makefile-naming">
- <title>Naming</title>
-
- <para>The first part of the port's <filename>Makefile</filename> names
- the port, describes its version number, and lists it in the correct
- category.</para>
-
- <sect2>
- <title><varname>PORTNAME</varname> and <varname>PORTVERSION</varname></title>
-
- <para>You should set <varname>PORTNAME</varname> to the
- base name of your port, and <varname>PORTVERSION</varname>
- to the version number of the port.</para>
- </sect2>
-
- <sect2 xml:id="makefile-naming-revepoch">
- <title><varname>PORTREVISION</varname> and
- <varname>PORTEPOCH</varname></title>
-
- <sect3>
- <title><varname>PORTREVISION</varname></title>
-
- <para>The <varname>PORTREVISION</varname> variable is a
- monotonically increasing value which is reset to 0 with
- every increase of <varname>PORTVERSION</varname> (i.e.
- every time a new official vendor release is made), and
- appended to the package name if non-zero.
- Changes to <varname>PORTREVISION</varname> are
- used by automated tools (e.g. &man.pkg.version.1;)
- to highlight the fact that a new package is
- available.</para>
-
- <para><varname>PORTREVISION</varname> should be increased
- each time a change is made to the port which significantly
- affects the content or structure of the derived
- package.</para>
-
- <para>Examples of when <varname>PORTREVISION</varname>
- should be bumped:</para>
+ </sect2>
- <itemizedlist>
- <listitem>
- <para>Addition of patches to correct security
- vulnerabilities, bugs, or to add new functionality to
- the port.</para>
- </listitem>
+ <sect2 xml:id="slow-patch-manual">
+ <title xml:lang="en">Manual Patch Generation</title>
- <listitem>
- <para>Changes to the port <filename>Makefile</filename> to enable or disable
- compile-time options in the package.</para>
- </listitem>
+ <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
+ may be required occasionally.</para>
+ </note>
- <listitem>
- <para>Changes in the packing list or the install-time
- behavior of the package (e.g. change to a script
- which generates initial data for the package, like ssh
- host keys).</para>
- </listitem>
+ <para xml:lang="en">Patches are saved into files named
+ <filename>patch-*</filename> where
+ <replaceable>*</replaceable> indicates the pathname of the
+ file that is patched, such as
+ <filename>patch-Imakefile</filename> or
+ <filename>patch-src-config.h</filename>.</para>
+
+ <para xml:lang="en">After the file has been modified, <citerefentry><refentrytitle>diff</refentrytitle><manvolnum>1</manvolnum></citerefentry> is used to
+ record the differences between the original and the modified
+ version. <option>-u</option> causes <citerefentry><refentrytitle>diff</refentrytitle><manvolnum>1</manvolnum></citerefentry> to produce
+ <quote>unified</quote> diffs, the preferred form.</para>
+
+ <screen><prompt>%</prompt> <userinput>diff -u <replaceable>file</replaceable>.orig <replaceable>file</replaceable> &gt; patch-<replaceable>pathname-file</replaceable></userinput></screen>
+
+ <para xml:lang="en">When generating patches for new, added files,
+ <option>-N</option> is used to tell <citerefentry><refentrytitle>diff</refentrytitle><manvolnum>1</manvolnum></citerefentry> to treat the
+ non-existent original file as if it existed but was
+ empty:</para>
+
+ <screen><prompt>%</prompt> <userinput>diff -u -N <replaceable>newfile</replaceable>.orig <replaceable>newfile</replaceable> &gt; patch-<replaceable>pathname-newfile</replaceable></userinput></screen>
+
+ <para xml:lang="en">Do not add <literal>$FreeBSD$</literal> RCS
+ strings in patches. When patches are added to the
+ <application>Subversion</application> repository with
+ <command>svn add</command>, the
+ <literal>fbsd:nokeywords</literal> property is set to
+ <literal>yes</literal> automatically so keywords in the patch
+ are not modified when committed. The property can be added
+ manually with <command>svn propset fbsd:nokeywords yes
+ <replaceable>files...</replaceable></command>.</para>
+
+ <para xml:lang="en">Using the recurse (<option>-r</option>) option to
+ <citerefentry><refentrytitle>diff</refentrytitle><manvolnum>1</manvolnum></citerefentry> to generate patches is fine, but please look at
+ the resulting patches to make sure there is no unnecessary
+ junk in there. In particular, diffs between two backup files,
+ <filename>Makefile</filename>s when the port uses
+ <command>Imake</command> or GNU <command>configure</command>,
+ etc., are unnecessary and have to be deleted. If it was
+ necessary to edit <filename>configure.in</filename> and run
+ <command>autoconf</command> to regenerate
+ <command>configure</command>, do not take the diffs of
+ <command>configure</command> (it often grows to a few thousand
+ lines!). Instead, define
+ <literal>USE_AUTOTOOLS=autoconf:261</literal> and take the
+ diffs of <filename>configure.in</filename>.</para>
- <listitem>
- <para>Version bump of a port's shared library dependency
- (in this case, someone trying to install the old
- package after installing a newer version of the
- dependency will fail since it will look for the old
- libfoo.x instead of libfoo.(x+1)).</para>
- </listitem>
+ </sect2>
- <listitem>
- <para>Silent changes to the port distfile which have
- significant functional differences, i.e. changes to
- the distfile requiring a correction to
- <filename>distinfo</filename> with no corresponding change to
- <varname>PORTVERSION</varname>, where a <command>diff
- -ru</command> of the old and new versions shows
- non-trivial changes to the code.</para>
- </listitem>
- </itemizedlist>
+ <sect2 xml:id="slow-patch-automatic-replacements">
+ <title xml:lang="en">Simple Automatic Replacements</title>
- <para>Examples of changes which do not require a
- <varname>PORTREVISION</varname> bump:</para>
+ <para xml:lang="en">Simple replacements can be performed directly from the
+ port <filename>Makefile</filename> using the in-place mode of
+ <citerefentry><refentrytitle>sed</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This is useful when changes use the value of a
+ variable:</para>
- <itemizedlist>
- <listitem>
- <para>Style changes to the port skeleton with no
- functional change to what appears in the resulting
- package.</para>
- </listitem>
+ <programlisting>post-patch:
+ @${REINPLACE_CMD} -e 's|for Linux|for FreeBSD|g' ${WRKSRC}/README</programlisting>
- <listitem>
- <para>Changes to <varname>MASTER_SITES</varname> or
- other functional changes to the port which do not
- affect the resulting package.</para>
- </listitem>
+ <para xml:lang="en">Quite often, software being ported uses the CR/LF
+ convention in source files. This may cause problems with
+ further patching, compiler warnings, or script execution (like
+ <literal>/bin/sh^M not found</literal>.) To quickly convert
+ all files from CR/LF to just LF, add this entry to the port
+ <filename>Makefile</filename>:</para>
- <listitem>
- <para>Trivial patches to the distfile such as correction
- of typos, which are not important enough that users of
- the package should go to the trouble of
- upgrading.</para>
- </listitem>
+ <programlisting>USES= dos2unix</programlisting>
- <listitem>
- <para>Build fixes which cause a package to become
- compilable where it was previously failing (as long as
- the changes do not introduce any functional change on
- any other platforms on which the port did previously
- build). Since <varname>PORTREVISION</varname> reflects
- the content of the package, if the package was not
- previously buildable then there is no need to increase
- <varname>PORTREVISION</varname> to mark a
- change.</para>
- </listitem>
- </itemizedlist>
+ <para xml:lang="en">A list of specific files to convert can be given:</para>
- <para>A rule of thumb is to ask yourself whether a change
- committed to a port is something which everyone
- would benefit from having (either because of an
- enhancement, fix, or by virtue that the new package will
- actually work at all), and weigh that against that fact
- that it will cause everyone who regularly updates their
- ports tree to be compelled to update. If yes, the
- <varname>PORTREVISION</varname> should be bumped.</para>
- </sect3>
-
- <sect3>
- <title><varname>PORTEPOCH</varname></title>
-
- <para>From time to time a software vendor or FreeBSD porter
- will do something silly and release a version of their
- software which is actually numerically less than the
- previous version. An example of this is a port which goes
- from foo-20000801 to foo-1.0 (the former will be
- incorrectly treated as a newer version since 20000801 is a
- numerically greater value than 1).</para>
-
- <para>In situations such as this, the
- <varname>PORTEPOCH</varname> version should be increased.
- If <varname>PORTEPOCH</varname> is nonzero it is appended
- to the package name as described in section 0 above.
- <varname>PORTEPOCH</varname> must never be decreased or reset
- to zero, because that would cause comparison to a package
- from an earlier epoch to fail (i.e. the package would not
- be detected as out of date): the new version number (e.g.
- <literal>1.0,1</literal> in the above example) is still
- numerically less than the previous version (20000801), but
- the <literal>,1</literal> suffix is treated specially by
- automated tools and found to be greater than the implied
- suffix <literal>,0</literal> on the earlier package.</para>
-
- <para>Dropping or resetting <varname>PORTEPOCH</varname>
- incorrectly leads
- to no end of grief; if you do not understand the above discussion,
- please keep after it until you do, or ask questions on
- the mailing lists.</para>
-
- <para>It is expected that <varname>PORTEPOCH</varname> will
- not be used for the majority of ports, and that sensible
- use of <varname>PORTVERSION</varname> can often pre-empt
- it becoming necessary if a future release of the software
- should change the version structure. However, care is
- needed by FreeBSD porters when a vendor release is made
- without an official version number &mdash; such as a code
- <quote>snapshot</quote> release. The temptation is to label the
- release with the release date, which will cause problems
- as in the example above when a new <quote>official</quote> release is
- made.</para>
-
- <para>For example, if a snapshot release is made on the date
- 20000917, and the previous version of the software was
- version 1.2, the snapshot release should be given a
- <varname>PORTVERSION</varname> of 1.2.20000917 or similar,
- not 20000917, so that the succeeding release, say 1.3, is
- still a numerically greater value.</para>
- </sect3>
-
- <sect3>
- <title>Example of <varname>PORTREVISION</varname> and
- <varname>PORTEPOCH</varname> usage</title>
-
- <para>The <literal>gtkmumble</literal> port, version
- <literal>0.10</literal>, is committed to the ports
- collection:</para>
-
- <programlisting>PORTNAME= gtkmumble
-PORTVERSION= 0.10</programlisting>
-
- <para><varname>PKGNAME</varname> becomes
- <literal>gtkmumble-0.10</literal>.</para>
-
- <para>A security hole is discovered which requires a local
- FreeBSD patch. <varname>PORTREVISION</varname> is bumped
- accordingly.</para>
-
- <programlisting>PORTNAME= gtkmumble
-PORTVERSION= 0.10
-PORTREVISION= 1</programlisting>
-
- <para><varname>PKGNAME</varname> becomes
- <literal>gtkmumble-0.10_1</literal></para>
-
- <para>A new version is released by the vendor, numbered <literal>0.2</literal>
- (it turns out the author actually intended
- <literal>0.10</literal> to actually mean
- <literal>0.1.0</literal>, not <quote>what comes after
- 0.9</quote> - oops, too late now). Since the new minor
- version <literal>2</literal> is numerically less than the
- previous version <literal>10</literal>, the
- <varname>PORTEPOCH</varname> must be bumped to manually
- force the new package to be detected as <quote>newer</quote>. Since it
- is a new vendor release of the code,
- <varname>PORTREVISION</varname> is reset to 0 (or removed
- from the <filename>Makefile</filename>).</para>
-
- <programlisting>PORTNAME= gtkmumble
-PORTVERSION= 0.2
-PORTEPOCH= 1</programlisting>
-
- <para><varname>PKGNAME</varname> becomes
- <literal>gtkmumble-0.2,1</literal></para>
-
- <para>The next release is 0.3. Since
- <varname>PORTEPOCH</varname> never decreases, the version
- variables are now:</para>
-
- <programlisting>PORTNAME= gtkmumble
-PORTVERSION= 0.3
-PORTEPOCH= 1</programlisting>
-
- <para><varname>PKGNAME</varname> becomes
- <literal>gtkmumble-0.3,1</literal></para>
+ <programlisting>USES= dos2unix
+DOS2UNIX_FILES= util.c util.h</programlisting>
- <note>
- <para>If <varname>PORTEPOCH</varname> were reset
- to <literal>0</literal> with this upgrade, someone who had
- installed the <literal>gtkmumble-0.10_1</literal> package would not detect
- the <literal>gtkmumble-0.3</literal> package as newer, since
- <literal>3</literal> is still numerically less than
- <literal>10</literal>. Remember, this is the whole point of
- <varname>PORTEPOCH</varname> in the first place.</para>
- </note>
- </sect3>
- </sect2>
+ <para xml:lang="en">Use <varname>DOS2UNIX_REGEX</varname> to convert a group
+ of files across subdirectories. Its argument is a
+ <citerefentry><refentrytitle>find</refentrytitle><manvolnum>1</manvolnum></citerefentry>-compatible regular expression. More on the
+ format is in <citerefentry><refentrytitle>re_format</refentrytitle><manvolnum>7</manvolnum></citerefentry>. This option is useful for
+ converting all files of a given extension. For example,
+ convert all source code files, leaving binary files
+ intact:</para>
- <sect2>
- <title><varname>PKGNAMEPREFIX</varname> and <varname>PKGNAMESUFFIX</varname></title>
+ <programlisting>USES= dos2unix
+DOS2UNIX_REGEX= .*\.([ch]|cpp)</programlisting>
- <para>Two optional variables, <varname>PKGNAMEPREFIX</varname> and
- <varname>PKGNAMESUFFIX</varname>, are combined with
- <varname>PORTNAME</varname> and
- <varname>PORTVERSION</varname> to
- form <varname>PKGNAME</varname> as
- <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>.
- Make sure this conforms to our <link linkend="porting-pkgname">guidelines for a good package
- name</link>. In particular, you are <emphasis>not</emphasis> allowed to use a
- hyphen (<literal>-</literal>) in
- <varname>PORTVERSION</varname>. Also, if the package name
- has the <replaceable>language-</replaceable> or the
- <replaceable>-compiled.specifics</replaceable> part (see below), use
- <varname>PKGNAMEPREFIX</varname> and
- <varname>PKGNAMESUFFIX</varname>, respectively. Do not make
- them part of <varname>PORTNAME</varname>.</para>
- </sect2>
-
- <sect2>
- <title><varname>LATEST_LINK</varname></title>
-
- <para>在某些情況,可能會同時存在有不同版本的同一程式。
- 由於它們可能會有同樣的 <varname>PORTNAME</varname>、
- <varname>PKGNAMEPREFIX</varname>,甚至
- <varname>PKGNAMESUFFIX</varname> 也相同,所以得讓這些程式有所不同,
- 才能讓 port 的 index 以及 package 能順利產生。 遇到這類情況,
- the optional <varname>LATEST_LINK</varname> variable should be set to
- a different value for all ports except the <quote>main</quote>
- one &mdash; see the <filename>editors/vim5</filename> and
- <filename>editors/vim</filename> ports, and the
- <filename>www/apache*</filename> family for examples of its use.
- Note that how to choose a <quote>main</quote> version &mdash;
- <quote>most popular</quote>, <quote>best supported</quote>,
- <quote>least patched</quote>, and so on &mdash; is outside the
- scope of this handbook's recommendations; we only tell you how to
- specify the other ports' versions after you have picked a
- <quote>main</quote> one.</para>
- </sect2>
+ <para xml:lang="en">A similar option is <varname>DOS2UNIX_GLOB</varname>,
+ which runs <command>find</command> for each element listed
+ in it.</para>
+
+ <programlisting>USES= dos2unix
+DOS2UNIX_GLOB= *.c *.cpp *.h</programlisting>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="slow-configure">
+ <title>設定</title>
+
+ <para xml:lang="en">Include any additional customization commands in the
+ <filename>configure</filename> script and save it in the
+ <filename>scripts</filename> subdirectory. As mentioned above,
+ it is also possible do this with <filename>Makefile</filename> targets
+ and/or scripts with the name <filename>pre-configure</filename>
+ or <filename>post-configure</filename>.</para>
+ </sect1>
+
+ <sect1 xml:id="slow-user-input">
+ <title>處理使用者輸入</title>
+
+ <para xml:lang="en">If the port requires user input to build, configure, or
+ install, set <varname>IS_INTERACTIVE</varname> in the
+ <filename>Makefile</filename>. This will allow
+ <quote>overnight builds</quote> to skip it. If the user
+ sets the variable <envar>BATCH</envar> in his environment (and
+ if the user sets the variable <envar>INTERACTIVE</envar>, then
+ <emphasis>only</emphasis> those ports requiring interaction are
+ built). This will save a lot of wasted time on the set of
+ machines that continually build ports (see below).</para>
+
+ <para xml:lang="en">It is also recommended that if there are reasonable default
+ answers to the questions,
+ <varname>PACKAGE_BUILDING</varname> be used to turn off the
+ interactive script when it is set. This will allow us to build
+ the packages for CDROMs and FTP.</para>
+ </sect1>
+</chapter>
+
+
+<!--
+ The FreeBSD Documentation Project
+
+ $FreeBSD$
+-->
+<chapter version="5.0" xml:id="makefiles">
+
+ <title>設定 Makefile</title>
+
+ <para xml:lang="en">Configuring the <filename>Makefile</filename> is pretty
+ simple, and again we suggest looking at existing examples
+ before starting. Also, there is a
+ <link linkend="porting-samplem">sample Makefile</link> in this
+ handbook, so take a look and please follow the ordering of
+ variables and sections in that template to make the port easier
+ for others to read.</para>
+
+ <para xml:lang="en">Consider these problems in sequence during the
+ design of the new <filename>Makefile</filename>:</para>
+
+ <sect1 xml:id="makefile-source">
+ <title xml:lang="en">The Original Source</title>
+
+ <para xml:lang="en">Does it live in <varname>DISTDIR</varname> as a standard
+ <command>gzip</command>ped tarball named something like
+ <filename>foozolix-1.2.tar.gz</filename>? If so, go on
+ to the next step. If not, the distribution file format might
+ require overriding one or more of
+ <varname>DISTVERSION</varname>, <varname>DISTNAME</varname>,
+ <varname>EXTRACT_CMD</varname>,
+ <varname>EXTRACT_BEFORE_ARGS</varname>,
+ <varname>EXTRACT_AFTER_ARGS</varname>,
+ <varname>EXTRACT_SUFX</varname>, or
+ <varname>DISTFILES</varname>.</para>
+
+ <para xml:lang="en">In the worst case, create a custom
+ <buildtarget xml:lang="en">do-extract</buildtarget> target to override the
+ default. This is rarely, if ever, necessary.</para>
+ </sect1>
+
+ <sect1 xml:id="makefile-naming">
+ <title>命名</title>
+
+ <para xml:lang="en">The first part of the port's <filename>Makefile</filename>
+ names the port, describes its version number, and lists it in
+ the correct category.</para>
+
+ <sect2 xml:id="makefile-portname">
+ <title xml:lang="en"><varname>PORTNAME</varname> and
+ <varname>PORTVERSION</varname></title>
+
+ <para xml:lang="en">Set <varname>PORTNAME</varname> to the base
+ name of the port. Set <varname>PORTVERSION</varname> to the
+ version number of the port unless
+ <varname>DISTVERSION</varname> is used (see
+ <xref linkend="makefile-distversion"/>).</para>
+
+ <important>
+ <para xml:lang="en">The package name must be unique across the entire ports
+ tree. Make sure that the <varname>PORTNAME</varname> is not
+ already in use by an existing port. If the name has already
+ been used, add either
+ <link linkend="porting-pkgnameprefix-suffix"><varname>PKGNAMEPREFIX</varname>
+ or <varname>PKGNAMESUFFIX</varname></link>.</para>
+ </important>
+ </sect2>
+
+ <sect2 xml:id="makefile-naming-revepoch">
+ <title xml:lang="en"><varname>PORTREVISION</varname> and
+ <varname>PORTEPOCH</varname></title>
+
+ <sect3 xml:id="makefile-portrevision">
+ <title xml:lang="en"><varname>PORTREVISION</varname></title>
+
+ <para xml:lang="en"><varname>PORTREVISION</varname> is a
+ monotonically increasing value which is reset to 0 with
+ every increase of <varname>PORTVERSION</varname>, typically
+ every time there is a new official vendor release. If
+ <varname>PORTREVISION</varname> is non-zero, the value is
+ appended to the package name. Changes to
+ <varname>PORTREVISION</varname> are used by automated tools
+ like <citerefentry><refentrytitle>pkg-version</refentrytitle><manvolnum>8</manvolnum></citerefentry> to determine that a new package is
+ available.</para>
+
+ <para xml:lang="en"><varname>PORTREVISION</varname> must be increased each
+ time a change is made to the port that changes the generated
+ package in any way. That includes changes that only affect
+ a package built with non-default
+ <link linkend="makefile-options">options</link>.</para>
+
+ <para xml:lang="en">Examples of when <varname>PORTREVISION</varname>
+ must be bumped:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para xml:lang="en">Addition of patches to correct security
+ vulnerabilities, bugs, or to add new functionality to
+ the port.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">Changes to the port <filename>Makefile</filename> to
+ enable or disable compile-time options in the
+ package.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">Changes in the packing list or the install-time
+ behavior of the package. For example, a change to a
+ script which generates initial data for the package,
+ like <citerefentry><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry> host keys.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">Version bump of a port's shared library dependency
+ (in this case, someone trying to install the old package
+ after installing a newer version of the dependency will
+ fail since it will look for the old libfoo.x instead of
+ libfoo.(x+1)).</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">Silent changes to the port distfile which have
+ significant functional differences. For example,
+ changes to the distfile requiring a correction to
+ <filename>distinfo</filename> with no corresponding
+ change to <varname>PORTVERSION</varname>, where a
+ <command>diff -ru</command> of the old and new versions
+ shows non-trivial changes to the code.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para xml:lang="en">Examples of changes which do not require a
+ <varname>PORTREVISION</varname> bump:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para xml:lang="en">Style changes to the port skeleton with no
+ functional change to what appears in the resulting
+ package.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">Changes to <varname>MASTER_SITES</varname> or other
+ functional changes to the port which do not affect the
+ resulting package.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">Trivial patches to the distfile such as correction
+ of typos, which are not important enough that users of
+ the package have to go to the trouble of
+ upgrading.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">Build fixes which cause a package to become
+ compilable where it was previously failing. As long as
+ the changes do not introduce any functional change on
+ any other platforms on which the port did previously
+ build. Since <varname>PORTREVISION</varname> reflects
+ the content of the package, if the package was not
+ previously buildable then there is no need to increase
+ <varname>PORTREVISION</varname> to mark a change.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para xml:lang="en">A rule of thumb is to decide whether a change
+ committed to a port is something which
+ <emphasis>some</emphasis> people would benefit from having.
+ Either because of an enhancement, fix,
+ or by virtue that the new package will actually work at
+ all. Then weigh that against that fact that it will cause
+ everyone who regularly updates their ports tree to be
+ compelled to update. If yes,
+ <varname>PORTREVISION</varname> must be bumped.</para>
+
+ <note>
+ <para xml:lang="en">People using binary packages will
+ <emphasis>never</emphasis> see the update if
+ <varname>PORTREVISION</varname> is not bumped. Without
+ increasing <varname>PORTREVISION</varname>, the
+ package builders have no way to detect the change and
+ thus, will not rebuild the package.</para>
+ </note>
+ </sect3>
+
+ <sect3 xml:id="makefile-portepoch">
+ <title xml:lang="en"><varname>PORTEPOCH</varname></title>
+
+ <para xml:lang="en">From time to time a software vendor or FreeBSD porter will
+ do something silly and release a version of their software
+ which is actually numerically less than the previous
+ version. An example of this is a port which goes from
+ foo-20000801 to foo-1.0 (the former will be incorrectly
+ treated as a newer version since 20000801 is a numerically
+ greater value than 1).</para>
+
+ <tip>
+ <para xml:lang="en">The results of version number comparisons are not
+ always obvious. <command>pkg version</command> (see
+ <citerefentry><refentrytitle>pkg-version</refentrytitle><manvolnum>8</manvolnum></citerefentry>) can be used to test the comparison of
+ two version number strings. For example:</para>
+
+ <screen><prompt>%</prompt> <userinput>pkg version -t 0.031 0.29</userinput>
+&gt;</screen>
+
+ <para xml:lang="en">The <literal>&gt;</literal> output indicates that
+ version 0.031 is considered greater than version 0.29,
+ which may not have been obvious to the porter.</para>
+ </tip>
+
+ <para xml:lang="en">In situations such as this,
+ <varname>PORTEPOCH</varname> must be increased.
+ If <varname>PORTEPOCH</varname> is nonzero it is appended to
+ the package name as described in section 0 above.
+ <varname>PORTEPOCH</varname> must never be decreased or
+ reset to zero, because that would cause comparison to a
+ package from an earlier epoch to fail. For example, the
+ package would not be detected as out of date. The new
+ version number, <literal>1.0,1</literal> in the above
+ example, is still numerically less than the previous
+ version, 20000801, but the <literal>,1</literal> suffix is
+ treated specially by automated tools and found to be greater
+ than the implied suffix <literal>,0</literal> on the earlier
+ package.</para>
+
+ <para xml:lang="en">Dropping or resetting <varname>PORTEPOCH</varname>
+ incorrectly leads to no end of grief. If the discussion
+ above was not clear enough, please consult the
+ <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports">FreeBSD ports mailing list</link>.</para>
+
+ <para xml:lang="en">It is expected that <varname>PORTEPOCH</varname> will
+ not be used for the majority of ports, and that sensible use
+ of <varname>PORTVERSION</varname> can often preempt it
+ becoming necessary if a future release of the software
+ changes the version structure. However, care is
+ needed by FreeBSD porters when a vendor release is made without
+ an official version number — such as a code
+ <quote>snapshot</quote> release. The temptation is to label
+ the release with the release date, which will cause problems
+ as in the example above when a new <quote>official</quote>
+ release is made.</para>
+
+ <para xml:lang="en">For example, if a snapshot release is made on the date
+ <literal>20000917</literal>, and the previous version of the
+ software was version <literal>1.2</literal>, do not use
+ <literal>20000917</literal> for
+ <varname>PORTVERSION</varname>. The correct way is a
+ <varname>PORTVERSION</varname> of
+ <literal>1.2.20000917</literal>, or similar, so that the
+ succeeding release, say <literal>1.3</literal>, is still a
+ numerically greater value.</para>
+ </sect3>
+
+ <sect3 xml:id="makefile-portrevision-example">
+ <title><varname>PORTREVISION</varname> 和 <varname>PORTEPOCH</varname> 的使用範例</title>
+
+ <para xml:lang="en">The <literal>gtkmumble</literal> port, version
+ <literal>0.10</literal>, is committed to the ports
+ collection:</para>
+
+ <programlisting>PORTNAME= gtkmumble
+PORTVERSION= 0.10</programlisting>
+
+ <para><varname>PKGNAME</varname> 變成 <literal>gtkmumble-0.10</literal>.</para>
+
+ <para xml:lang="en">A security hole is discovered which requires a local
+ FreeBSD patch. <varname>PORTREVISION</varname> is bumped
+ accordingly.</para>
+
+ <programlisting>PORTNAME= gtkmumble
+PORTVERSION= 0.10
+PORTREVISION= 1</programlisting>
+
+ <para><varname>PKGNAME</varname> 變成 <literal>gtkmumble-0.10_1</literal></para>
+
+ <para xml:lang="en">A new version is released by the vendor, numbered
+ <literal>0.2</literal> (it turns out the author actually
+ intended <literal>0.10</literal> to actually mean
+ <literal>0.1.0</literal>, not <quote>what comes after
+ 0.9</quote> - oops, too late now). Since the new minor
+ version <literal>2</literal> is numerically less than the
+ previous version <literal>10</literal>,
+ <varname>PORTEPOCH</varname> must be bumped to manually
+ force the new package to be detected as
+ <quote>newer</quote>. Since it is a new vendor release of
+ the code, <varname>PORTREVISION</varname> is reset to 0 (or
+ removed from the <filename>Makefile</filename>).</para>
+
+ <programlisting>PORTNAME= gtkmumble
+PORTVERSION= 0.2
+PORTEPOCH= 1</programlisting>
+
+ <para><varname>PKGNAME</varname> 變成 <literal>gtkmumble-0.2,1</literal></para>
+
+ <para xml:lang="en">The next release is 0.3. Since
+ <varname>PORTEPOCH</varname> never decreases, the version
+ variables are now:</para>
+
+ <programlisting>PORTNAME= gtkmumble
+PORTVERSION= 0.3
+PORTEPOCH= 1</programlisting>
+
+ <para><varname>PKGNAME</varname> 變成 <literal>gtkmumble-0.3,1</literal></para>
+
+ <note>
+ <para xml:lang="en">If <varname>PORTEPOCH</varname> were reset to
+ <literal>0</literal> with this upgrade, someone who had
+ installed the <literal>gtkmumble-0.10_1</literal> package
+ would not detect the <literal>gtkmumble-0.3</literal>
+ package as newer, since <literal>3</literal> is still
+ numerically less than <literal>10</literal>. Remember,
+ this is the whole point of <varname>PORTEPOCH</varname> in
+ the first place.</para>
+ </note>
+ </sect3>
+ </sect2>
+
+ <sect2 xml:id="porting-pkgnameprefix-suffix">
+ <title><varname>PKGNAMEPREFIX</varname> 和 <varname>PKGNAMESUFFIX</varname></title>
+
+ <para xml:lang="en">Two optional variables, <varname>PKGNAMEPREFIX</varname>
+ and <varname>PKGNAMESUFFIX</varname>, are combined with
+ <varname>PORTNAME</varname> and <varname>PORTVERSION</varname>
+ to form <varname>PKGNAME</varname> as
+ <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>.
+ Make sure this conforms to our
+ <link linkend="porting-pkgname">guidelines for a good
+ package name</link>. In particular, the use of a
+ hyphen (<literal>-</literal>) in
+ <varname>PORTVERSION</varname> is <emphasis>not</emphasis>
+ allowed.
+ Also, if the package name has the
+ <replaceable>language-</replaceable> or the
+ <replaceable>-compiled.specifics</replaceable> part (see
+ below), use <varname>PKGNAMEPREFIX</varname> and
+ <varname>PKGNAMESUFFIX</varname>, respectively. Do not make
+ them part of <varname>PORTNAME</varname>.</para>
+ </sect2>
<sect2 xml:id="porting-pkgname">
- <title>Package Naming Conventions</title>
+ <title>套件命名慣例</title>
- <para>The following are the conventions you should follow in naming your
- packages. This is to have our package directory easy to scan, as
- there are already thousands of packages and users are going to
- turn away if they hurt their eyes!</para>
+ <para xml:lang="en">These are the conventions to follow when
+ naming packages. This is to make the package directory
+ easy to scan, as there are already thousands of packages and
+ users are going to turn away if they hurt their eyes!</para>
- <para>The package name should look like
- <filename>language_region-name-compiled.specifics-version.numbers</filename>.</para>
+ <para xml:lang="en">Package names take the form of
+ <filename><replaceable>language_region-name-compiled.specifics-version.numbers</replaceable></filename>.</para>
- <para>The package name is defined as
+ <para xml:lang="en">The package name is defined as
<literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>.
- Make sure to set the variables to conform to that format.</para>
+ Make sure to set the variables to conform to that
+ format.</para>
- <orderedlist>
- <listitem>
- <para>FreeBSD strives to support the native language of its users.
- The <replaceable>language-</replaceable> part should be a two
- letter abbreviation of the natural language defined by ISO-639 if
- the port is specific to a certain language. Examples are
- <literal>ja</literal> for Japanese, <literal>ru</literal> for
- Russian, <literal>vi</literal> for Vietnamese,
- <literal>zh</literal> for Chinese, <literal>ko</literal> for
- Korean and <literal>de</literal> for German.</para>
-
- <para>If the port is specific to a certain region within the
- language area, add the two letter country code as well.
- Examples are <literal>en_US</literal> for US English and
- <literal>fr_CH</literal> for Swiss French.</para>
-
- <para>The <replaceable>language-</replaceable> part should
- be set in the <varname>PKGNAMEPREFIX</varname> variable.</para>
- </listitem>
+ <variablelist xml:id="porting-pkgname-format">
+ <varlistentry xml:id="porting-pkgname-language">
+ <term xml:lang="en"><filename><replaceable>language_region-</replaceable></filename></term>
- <listitem>
- <para>The first letter of the <filename>name</filename> part
- should be lowercase. (The rest of the name may contain
- capital letters, so use your own discretion when you are
- converting a software name that has some capital letters in it.)
- There is a tradition of naming <literal>Perl 5</literal> modules by
- prepending <literal>p5-</literal> and converting the double-colon
- separator to a hyphen; for example, the
- <literal>Data::Dumper</literal> module becomes
- <literal>p5-Data-Dumper</literal>.</para>
- </listitem>
+ <listitem>
+ <para xml:lang="en">FreeBSD strives to support the native language of its
+ users. The <replaceable>language-</replaceable> part is
+ a two letter abbreviation of the natural language
+ defined by ISO-639 when the port is specific to a
+ certain language. Examples are <literal>ja</literal>
+ for Japanese, <literal>ru</literal> for Russian,
+ <literal>vi</literal> for Vietnamese,
+ <literal>zh</literal> for Chinese, <literal>ko</literal>
+ for Korean and <literal>de</literal> for German.</para>
+
+ <para xml:lang="en">If the port is specific to a certain region within
+ the language area, add the two letter country code as
+ well. Examples are <literal>en_US</literal> for US
+ English and <literal>fr_CH</literal> for Swiss
+ French.</para>
+
+ <para xml:lang="en">The <replaceable>language-</replaceable> part is
+ set in <varname>PKGNAMEPREFIX</varname>.</para>
+ </listitem>
+ </varlistentry>
- <listitem>
- <para>Make sure that the port's name and version are clearly
- separated and placed into the <varname>PORTNAME</varname> and
- <varname>PORTVERSION</varname> variables. The only reason for
- <varname>PORTNAME</varname> to contain a version part is if
- the upstream distribution is really named that way, as in
- the <filename>textproc/libxml2</filename> or
- <filename>japanese/kinput2-freewnn</filename> ports. Otherwise,
- the <varname>PORTNAME</varname> should not contain any
- version-specific information. It is quite normal for several
- ports to have the same <varname>PORTNAME</varname>, as the
- <filename>www/apache*</filename> ports do; in that case,
- different versions (and different index entries) are
- distinguished by the <varname>PKGNAMEPREFIX</varname>,
- <varname>PKGNAMESUFFIX</varname>, and
- <varname>LATEST_LINK</varname> values.</para>
- </listitem>
+ <varlistentry xml:id="porting-pkgname-name">
+ <term xml:lang="en"><filename><replaceable>name</replaceable></filename></term>
- <listitem>
- <para>If the port can be built with different <link linkend="makefile-masterdir">hardcoded defaults</link> (usually
- part of the directory name in a family of ports), the
- <replaceable>-compiled.specifics</replaceable> part should state
- the compiled-in defaults (the hyphen is optional). Examples are
- papersize and font units.</para>
-
- <para>The <replaceable>-compiled.specifics</replaceable> part
- should be set in the <varname>PKGNAMESUFFIX</varname>
- variable.</para>
- </listitem>
+ <listitem>
+ <para xml:lang="en">Make sure that the port's name and version are
+ clearly separated and placed into
+ <varname>PORTNAME</varname> and
+ <varname>PORTVERSION</varname>. The only
+ reason for <varname>PORTNAME</varname> to contain a
+ version part is if the upstream distribution is really
+ named that way, as in the
+ <package role="port">textproc/libxml2</package> or
+ <package role="port">japanese/kinput2-freewnn</package>
+ ports. Otherwise, <varname>PORTNAME</varname> cannot
+ contain any version-specific information. It is quite
+ normal for several ports to have the same
+ <varname>PORTNAME</varname>, as the
+ <package role="port">www/apache*</package> ports do; in
+ that case, different versions (and different index
+ entries) are distinguished by
+ <varname>PKGNAMEPREFIX</varname>
+ and <varname>PKGNAMESUFFIX</varname> values.</para>
+
+ <para xml:lang="en">There is a tradition of naming
+ <literal>Perl 5</literal> modules by prepending
+ <literal>p5-</literal> and converting the double-colon
+ separator to a hyphen. For example, the
+ <literal>Data::Dumper</literal> module becomes
+ <literal>p5-Data-Dumper</literal>.</para>
+ </listitem>
+ </varlistentry>
- <listitem>
- <para>The version string should follow a dash
- (<literal>-</literal>) and be a period-separated list of
- integers and single lowercase alphabetics. In particular,
- it is not permissible to have another dash inside the
- version string. The only exception is the string
- <literal>pl</literal> (meaning <quote>patchlevel</quote>), which can be
- used <emphasis>only</emphasis> when there are no major and
- minor version numbers in the software. If the software
- version has strings like <quote>alpha</quote>, <quote>beta</quote>, <quote>rc</quote>, or <quote>pre</quote>, take
- the first letter and put it immediately after a period.
- If the version string continues after those names, the
- numbers should follow the single alphabet without an extra
- period between them.</para>
-
- <para>The idea is to make it easier to sort ports by looking
- at the version string. In particular, make sure version
- number components are always delimited by a period, and
- if the date is part of the string, use the
- <literal>yyyy.mm.dd</literal>
- format, not
- <literal>dd.mm.yyyy</literal>
- or the non-Y2K compliant
- <literal>yy.mm.dd</literal>
- format.</para>
- </listitem>
- </orderedlist>
+ <varlistentry xml:id="porting-pkgname-compiled-specifics">
+ <term xml:lang="en"><filename><replaceable>-compiled.specifics</replaceable></filename></term>
- <para>Here are some (real) examples on how to convert the name
+ <listitem>
+ <para xml:lang="en">If the port can be built with different <link linkend="makefile-masterdir">hardcoded defaults</link>
+ (usually part of the directory name in a family of
+ ports), the
+ <replaceable>-compiled.specifics</replaceable> part
+ states the compiled-in defaults. The hyphen is
+ optional. Examples are paper size and font
+ units.</para>
+
+ <para xml:lang="en">The <replaceable>-compiled.specifics</replaceable>
+ part is set in <varname>PKGNAMESUFFIX</varname>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="porting-pkgname-version-numbers">
+ <term xml:lang="en"><filename><replaceable>-version.numbers</replaceable></filename></term>
+
+ <listitem>
+ <para xml:lang="en">The version string follows a dash
+ (<literal>-</literal>) and is a period-separated list of
+ integers and single lowercase alphabetics. In
+ particular, it is not permissible to have another dash
+ inside the version string. The only exception is the
+ string <literal>pl</literal> (meaning
+ <quote>patchlevel</quote>), which can be used
+ <emphasis>only</emphasis> when there are no major and
+ minor version numbers in the software. If the software
+ version has strings like <quote>alpha</quote>,
+ <quote>beta</quote>, <quote>rc</quote>, or
+ <quote>pre</quote>, take the first letter and put it
+ immediately after a period. If the version string
+ continues after those names, the numbers follow
+ the single alphabet without an extra period between
+ them (for example, <literal>1.0b2</literal>).</para>
+
+ <para xml:lang="en">The idea is to make it easier to sort ports by
+ looking at the version string. In particular, make sure
+ version number components are always delimited by a
+ period, and if the date is part of the string, use the
+ <literal>0.0.<replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>
+ format, not
+ <literal><replaceable>dd</replaceable>.<replaceable>mm</replaceable>.<replaceable>yyyy</replaceable></literal>
+ or the non-Y2K compliant
+ <literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>
+ format. It is important to prefix the version with
+ <literal>0.0.</literal> in case a release with an actual
+ version number is made, which would be
+ numerically less than
+ <literal><replaceable>yyyy</replaceable></literal>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <important>
+ <para xml:lang="en">Package name must be unique among all of the ports
+ tree, check that there is not already a port with the same
+ <varname>PORTNAME</varname> and if there is add one of <link linkend="porting-pkgnameprefix-suffix"><varname>PKGNAMEPREFIX</varname>
+ or <varname>PKGNAMESUFFIX</varname></link>.</para>
+ </important>
+
+ <para xml:lang="en">Here are some (real) examples on how to convert the name
as called by the software authors to a suitable package
name:</para>
- <informaltable frame="none" pgwide="1">
+ <table frame="none" pgwide="1">
+ <title>套件命名範例</title>
+
<tgroup cols="6">
<thead>
<row>
- <entry>Distribution Name</entry>
+ <entry xml:lang="en">Distribution Name</entry>
<entry><varname>PKGNAMEPREFIX</varname></entry>
<entry><varname>PORTNAME</varname></entry>
<entry><varname>PKGNAMESUFFIX</varname></entry>
<entry><varname>PORTVERSION</varname></entry>
- <entry>Reason</entry>
+ <entry>原因</entry>
</row>
</thead>
<tbody>
<row>
<entry>mule-2.2.2</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>mule</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>2.2.2</entry>
- <entry>No changes required</entry>
+ <entry xml:lang="en">No changes required</entry>
+ </row>
+
+ <row>
+ <entry>mule-1.0.1</entry>
+ <entry>(空)</entry>
+ <entry>mule</entry>
+ <entry>1</entry>
+ <entry>1.0.1</entry>
+ <entry><literal>mule</literal> 已存在</entry>
</row>
<row>
<entry>EmiClock-1.0.2</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>emiclock</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>1.0.2</entry>
- <entry>No uppercase names for single programs</entry>
+ <entry xml:lang="en">No uppercase names for single programs</entry>
</row>
<row>
<entry>rdist-1.3alpha</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>rdist</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>1.3.a</entry>
- <entry>No strings like <literal>alpha</literal>
+ <entry xml:lang="en">No strings like <literal>alpha</literal>
allowed</entry>
</row>
<row>
<entry>es-0.9-beta1</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>es</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>0.9.b1</entry>
- <entry>No strings like <literal>beta</literal>
+ <entry xml:lang="en">No strings like <literal>beta</literal>
allowed</entry>
</row>
<row>
<entry>mailman-2.0rc3</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>mailman</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>2.0.r3</entry>
- <entry>No strings like <literal>rc</literal>
+ <entry xml:lang="en">No strings like <literal>rc</literal>
allowed</entry>
</row>
<row>
<entry>v3.3beta021.src</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>tiff</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>3.3</entry>
- <entry>What the heck was that anyway?</entry>
+ <entry xml:lang="en">What the heck was that anyway?</entry>
</row>
<row>
<entry>tvtwm</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>tvtwm</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>pl11</entry>
- <entry>Version string always required</entry>
+ <entry xml:lang="en">Version string always required</entry>
</row>
<row>
<entry>piewm</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>piewm</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>1.0</entry>
- <entry>Version string always required</entry>
+ <entry xml:lang="en">Version string always required</entry>
</row>
<row>
<entry>xvgr-2.10pl1</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>xvgr</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>2.10.1</entry>
- <entry><literal>pl</literal> allowed only when no
+ <entry xml:lang="en"><literal>pl</literal> allowed only when no
major/minor version numbers</entry>
</row>
@@ -1227,7829 +1515,12819 @@ PORTEPOCH= 1</programlisting>
<entry>gawk-2.15.6</entry>
<entry>ja-</entry>
<entry>gawk</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>2.15.6</entry>
- <entry>Japanese language version</entry>
+ <entry>日文版</entry>
</row>
<row>
<entry>psutils-1.13</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>psutils</entry>
<entry>-letter</entry>
<entry>1.13</entry>
- <entry>Papersize hardcoded at package build time</entry>
+ <entry xml:lang="en">Paper size hardcoded at package build
+ time</entry>
</row>
<row>
<entry>pkfonts</entry>
- <entry>(empty)</entry>
+ <entry>(空)</entry>
<entry>pkfonts</entry>
<entry>300</entry>
<entry>1.0</entry>
- <entry>Package for 300dpi fonts</entry>
+ <entry xml:lang="en">Package for 300dpi fonts</entry>
</row>
</tbody>
</tgroup>
- </informaltable>
+ </table>
- <para>If there is absolutely no trace of version information in the
- original source and it is unlikely that the original author will ever
- release another version, just set the version string to
- <literal>1.0</literal> (like the <literal>piewm</literal> example above). Otherwise, ask
- the original author or use the date string
- (<literal>yyyy.mm.dd</literal>)
+ <para xml:lang="en">If there is absolutely no trace of version information in
+ the original source and it is unlikely that the original
+ author will ever release another version, just set the version
+ string to <literal>1.0</literal> (like the
+ <literal>piewm</literal> example above). Otherwise, ask the
+ original author or use the date string the source file was
+ released on
+ (<literal>0.0.<replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>)
as the version.</para>
</sect2>
- </sect1>
+ </sect1>
+
+ <sect1 xml:id="makefile-categories">
+ <title>分類</title>
+
+ <sect2 xml:id="makefile-categories-definition">
+ <title><varname>CATEGORIES</varname></title>
+
+ <para xml:lang="en">When a package is created, it is put under
+ <filename>/usr/ports/packages/All</filename> and links are
+ made from one or more subdirectories of
+ <filename>/usr/ports/packages</filename>. The names of these
+ subdirectories are specified by the variable
+ <varname>CATEGORIES</varname>. It is intended to make life
+ easier for the user when he is wading through the pile of
+ packages on the FTP site or the CDROM. Please take a look at
+ the <link linkend="porting-categories">current list of
+ categories</link> and pick the ones that are suitable for
+ the port.</para>
+
+ <para xml:lang="en">This list also determines where in the ports tree the port
+ is imported. If there is more than one category here,
+ the port files must be put in the subdirectory
+ with the name of the first category. See
+ <link linkend="choosing-categories">below</link> for more
+ discussion about how to pick the right categories.</para>
+ </sect2>
- <sect1 xml:id="makefile-categories">
- <title>Categorization</title>
+ <sect2 xml:id="porting-categories">
+ <title>目前分類清單</title>
- <sect2>
- <title><varname>CATEGORIES</varname></title>
+ <para xml:lang="en">Here is the current list of port categories. Those marked
+ with an asterisk (<literal>*</literal>) are
+ <emphasis>virtual</emphasis> categories—those that do
+ not have a corresponding subdirectory in the ports tree. They
+ are only used as secondary categories, and only for search
+ purposes.</para>
- <para>When a package is created, it is put under
- <filename>/usr/ports/packages/All</filename> and links are made from
- one or more subdirectories of
- <filename>/usr/ports/packages</filename>. The names of these
- subdirectories are specified by the variable
- <varname>CATEGORIES</varname>. It is intended to make life easier
- for the user when he is wading through the pile of packages on the
- FTP site or the CDROM. Please take a look at the <link linkend="porting-categories">current list of categories</link> and pick the ones
- that are suitable for your port.</para>
+ <note>
+ <para xml:lang="en">For non-virtual categories, there is a one-line
+ description in <varname>COMMENT</varname> in that
+ subdirectory's <filename>Makefile</filename>.</para>
+ </note>
- <para>This list also determines where in the ports tree the port is
- imported. If you put more than one category here, it is assumed
- that the port files will be put in the subdirectory with the name in
- the first category. See <link linkend="choosing-categories">below</link> for more
- discussion about how to pick the right categories.</para>
- </sect2>
+ <informaltable frame="none" pgwide="1">
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>分類</entry>
+ <entry>描述</entry>
+ <entry>註</entry>
+ </row>
+ </thead>
- <sect2 xml:id="porting-categories">
- <title>Current list of categories</title>
+ <tbody>
+ <row>
+ <entry><filename>accessibility</filename></entry>
+ <entry xml:lang="en">Ports to help disabled users.</entry>
+ <entry/>
+ </row>
- <para>Here is the current list of port categories. Those
- marked with an asterisk (<literal>*</literal>) are
- <emphasis>virtual</emphasis> categories&mdash;those that do not have
- a corresponding subdirectory in the ports tree. They are only
- used as secondary categories, and only for search purposes.</para>
+ <row>
+ <entry><filename>afterstep*</filename></entry>
- <note>
- <para>For non-virtual categories, you will find a one-line
- description in the <varname>COMMENT</varname> in that
- subdirectory's <filename>Makefile</filename>.</para>
- </note>
+ <entry xml:lang="en">Ports to support the <link xlink:href="http://www.afterstep.org">AfterStep</link>
+ window manager.</entry>
+ <entry/>
+ </row>
- <informaltable frame="none" pgwide="1">
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Category</entry>
- <entry>Description</entry>
- <entry>Notes</entry>
- </row>
- </thead>
+ <row>
+ <entry><filename>arabic</filename></entry>
+ <entry>阿拉伯文支援。</entry>
+ <entry/>
+ </row>
- <tbody>
- <row>
- <entry><filename>accessibility</filename></entry>
- <entry>Ports to help disabled users.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>archivers</filename></entry>
+ <entry xml:lang="en">Archiving tools.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>afterstep*</filename></entry>
- <entry>Ports to support the
- <link xlink:href="http://www.afterstep.org">AfterStep</link>
- window manager.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>astro</filename></entry>
+ <entry xml:lang="en">Astronomical ports.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>arabic</filename></entry>
- <entry>Arabic language support.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>audio</filename></entry>
+ <entry xml:lang="en">Sound support.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>archivers</filename></entry>
- <entry>Archiving tools.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>benchmarks</filename></entry>
+ <entry xml:lang="en">Benchmarking utilities.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>astro</filename></entry>
- <entry>Astronomical ports.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>biology</filename></entry>
+ <entry xml:lang="en">Biology-related software.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>audio</filename></entry>
- <entry>Sound support.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>cad</filename></entry>
+ <entry xml:lang="en">Computer aided design tools.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>benchmarks</filename></entry>
- <entry>Benchmarking utilities.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>chinese</filename></entry>
+ <entry>中文支援。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>biology</filename></entry>
- <entry>Biology-related software.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>comms</filename></entry>
+ <entry xml:lang="en">Communication software.</entry>
+ <entry xml:lang="en">Mostly software to talk to the serial
+ port.</entry>
+ </row>
- <row>
- <entry><filename>cad</filename></entry>
- <entry>Computer aided design tools.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>converters</filename></entry>
+ <entry xml:lang="en">Character code converters.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>chinese</filename></entry>
- <entry>Chinese language support.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>databases</filename></entry>
+ <entry>資料庫。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>comms</filename></entry>
- <entry>Communication software.</entry>
- <entry>Mostly software to talk to your serial port.</entry>
- </row>
+ <row>
+ <entry><filename>deskutils</filename></entry>
+ <entry xml:lang="en">Things that used to be on the desktop before
+ computers were invented.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>converters</filename></entry>
- <entry>Character code converters.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>devel</filename></entry>
+ <entry>開發公用程式。</entry>
+ <entry xml:lang="en">Do not put libraries here just because they are
+ libraries. They should <emphasis>not</emphasis> be
+ in this category unless they truly do not belong
+ anywhere else.</entry>
+ </row>
- <row>
- <entry><filename>databases</filename></entry>
- <entry>Databases.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>dns</filename></entry>
+ <entry>DNS 相關軟體。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>deskutils</filename></entry>
- <entry>Things that used to be on the desktop before
- computers were invented.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>docs*</filename></entry>
+ <entry xml:lang="en">Meta-ports for FreeBSD documentation.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>devel</filename></entry>
- <entry>Development utilities.</entry>
- <entry>Do not put libraries here just because they are
- libraries&mdash;unless they truly do not belong anywhere
- else, they should not be in this category.</entry>
- </row>
+ <row>
+ <entry><filename>editors</filename></entry>
+ <entry xml:lang="en">General editors.</entry>
+ <entry xml:lang="en">Specialized editors go in the section for those
+ tools. For example, a mathematical-formula editor
+ will go in <filename>math</filename>, and have
+ <filename>editors</filename> as a second
+ category.</entry>
+ </row>
- <row>
- <entry><filename>dns</filename></entry>
- <entry>DNS-related software.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>elisp*</filename></entry>
+ <entry xml:lang="en">Emacs-lisp ports.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>editors</filename></entry>
- <entry>General editors.</entry>
- <entry>Specialized editors go in the section for those
- tools (e.g., a mathematical-formula editor will go
- in <filename>math</filename>).</entry>
- </row>
+ <row>
+ <entry><filename>emulators</filename></entry>
+ <entry xml:lang="en">Emulators for other operating systems.</entry>
+ <entry xml:lang="en">Terminal emulators do <emphasis>not</emphasis>
+ belong here. X-based ones go to
+ <filename>x11</filename> and text-based ones to
+ either <filename>comms</filename> or
+ <filename>misc</filename>, depending on the exact
+ functionality.</entry>
+ </row>
- <row>
- <entry><filename>elisp*</filename></entry>
- <entry>Emacs-lisp ports.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>finance</filename></entry>
+ <entry xml:lang="en">Monetary, financial and related
+ applications.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>emulators</filename></entry>
- <entry>Emulators for other operating systems.</entry>
- <entry>Terminal emulators do <emphasis>not</emphasis> belong
- here&mdash;X-based ones should go to
- <filename>x11</filename> and text-based ones to either
- <filename>comms</filename> or <filename>misc</filename>,
- depending on the exact functionality.</entry>
- </row>
+ <row>
+ <entry><filename>french</filename></entry>
+ <entry>法文支援。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>finance</filename></entry>
- <entry>Monetary, financial and related applications.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>ftp</filename></entry>
+ <entry xml:lang="en"><acronym>FTP</acronym> client and server
+ utilities.</entry>
+ <entry xml:lang="en">If the port speaks both <acronym>FTP</acronym>
+ and <acronym>HTTP</acronym>, put it
+ in <filename>ftp</filename> with a secondary
+ category of <filename>www</filename>.</entry>
+ </row>
- <row>
- <entry><filename>french</filename></entry>
- <entry>French language support.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>games</filename></entry>
+ <entry>遊戲。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>ftp</filename></entry>
- <entry>FTP client and server utilities.</entry>
- <entry>If your port speaks both FTP and HTTP, put it in
- <filename>ftp</filename> with a secondary
- category of <filename>www</filename>.</entry>
- </row>
+ <row>
+ <entry><filename>geography*</filename></entry>
+ <entry>地理相關軟體。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>games</filename></entry>
- <entry>遊戲。</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>german</filename></entry>
+ <entry>德文支援。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>geography*</filename></entry>
- <entry>地理圖資相關的軟體。</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>gnome*</filename></entry>
+ <entry xml:lang="en">Ports from the
+ <link xlink:href="http://www.gnome.org">GNOME</link>
+ Project.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>german</filename></entry>
- <entry>德文相關支援。</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>gnustep*</filename></entry>
+ <entry xml:lang="en">Software related to the GNUstep desktop
+ environment.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>gnome*</filename></entry>
- <entry>Ports from the <link xlink:href="http://www.gnome.org">GNOME</link>
- Project.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>graphics</filename></entry>
+ <entry>繪圖公用程式。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>gnustep*</filename></entry>
- <entry>GNUstep 桌面環境相關的軟體。</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>hamradio*</filename></entry>
+ <entry xml:lang="en">Software for amateur radio.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>graphics</filename></entry>
- <entry>圖形處理的工具軟體。</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>haskell*</filename></entry>
+ <entry xml:lang="en">Software related to the Haskell
+ language.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>hamradio*</filename></entry>
- <entry>Software for amateur radio.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>hebrew</filename></entry>
+ <entry>希伯來文支援。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>haskell*</filename></entry>
- <entry>Software related to the Haskell language.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>hungarian</filename></entry>
+ <entry>匈牙利文支援。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>hebrew</filename></entry>
- <entry>Hebrew language support.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>ipv6*</filename></entry>
+ <entry>IPv6 相關軟體。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>hungarian</filename></entry>
- <entry>Hungarian language support.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>irc</filename></entry>
+ <entry xml:lang="en">Internet Relay Chat utilities.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>ipv6*</filename></entry>
- <entry>IPv6 related software.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>japanese</filename></entry>
+ <entry>日文支援。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>irc</filename></entry>
- <entry>Internet Relay Chat utilities.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>java</filename></entry>
+ <entry xml:lang="en">Software related to the Java™
+ language.</entry>
+ <entry xml:lang="en">The <filename>java</filename> category must not
+ be the only one for a port. Save for ports directly
+ related to the Java language, porters are also
+ encouraged not to use <filename>java</filename> as the
+ main category of a port.</entry>
+ </row>
- <row>
- <entry><filename>japanese</filename></entry>
- <entry>Japanese language support.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>kde*</filename></entry>
+ <entry xml:lang="en">Ports from the
+ <link xlink:href="http://www.kde.org">KDE</link>
+ Project.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>java</filename></entry>
- <entry>Software related to the Java language.</entry>
- <entry>The <filename>java</filename> category shall not be
- the only one for a port. Save for ports directly related to
- the Java language, porters are also encouraged not to
- use <filename>java</filename> as the main category of a
- port.</entry>
- </row>
+ <row>
+ <entry><filename>kld*</filename></entry>
+ <entry xml:lang="en">Kernel loadable modules.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>kde*</filename></entry>
- <entry>Ports from the <link xlink:href="http://www.kde.org">K Desktop Environment (KDE)</link>
- Project.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>korean</filename></entry>
+ <entry>韓文支援。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>kld*</filename></entry>
- <entry>Kernel loadable modules。</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>lang</filename></entry>
+ <entry>程式語言。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>korean</filename></entry>
- <entry>Korean language support.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>linux*</filename></entry>
+ <entry>Linux 應用程式和支援的公用程式</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>lang</filename></entry>
- <entry>Programming languages.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>lisp*</filename></entry>
+ <entry xml:lang="en">Software related to the Lisp language.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>linux*</filename></entry>
- <entry>Linux applications and support utilities.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>mail</filename></entry>
+ <entry>郵件軟體</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>lisp*</filename></entry>
- <entry>Software related to the Lisp language.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>math</filename></entry>
+ <entry xml:lang="en">Numerical computation software and other
+ utilities for mathematics.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>mail</filename></entry>
- <entry>Mail software.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>mbone*</filename></entry>
+ <entry>MBone 應用程式。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>math</filename></entry>
- <entry>Numerical computation software and other utilities
- for mathematics.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>misc</filename></entry>
+ <entry>其他公用程式</entry>
+ <entry xml:lang="en">Things that do not belong anywhere
+ else. If at all possible, try to find a better
+ category for the port than <literal>misc</literal>,
+ as ports tend to be overlooked in here.</entry>
+ </row>
- <row>
- <entry><filename>mbone</filename></entry>
- <entry>MBone applications.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>multimedia</filename></entry>
+ <entry>多媒體軟體。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>misc</filename></entry>
- <entry>Miscellaneous utilities</entry>
- <entry>Basically things that
- do not belong anywhere else.
- If at all possible, try to
- find a better category for your port than
- <literal>misc</literal>, as ports tend to get overlooked
- in here.</entry>
- </row>
+ <row>
+ <entry><filename>net</filename></entry>
+ <entry xml:lang="en">Miscellaneous networking software.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>multimedia</filename></entry>
- <entry>Multimedia software.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>net-im</filename></entry>
+ <entry>即時通訊軟體。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>net</filename></entry>
- <entry>Miscellaneous networking software.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>net-mgmt</filename></entry>
+ <entry>網路管理軟體。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>net-im</filename></entry>
- <entry>Instant messaging software.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>net-p2p</filename></entry>
+ <entry>點對點 (Peer to peer) 網路應用程式。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>net-mgmt</filename></entry>
- <entry>Networking management software.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>news</filename></entry>
+ <entry>USENET 新聞軟體。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>net-p2p</filename></entry>
- <entry>Peer to peer network applications.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>palm</filename></entry>
- <row>
- <entry><filename>news</filename></entry>
- <entry>USENET news software.</entry>
- <entry/>
- </row>
+ <entry xml:lang="en">Software support for the <link xlink:href="http://www.palm.com/">Palm™</link>
+ series.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>palm</filename></entry>
- <entry>Software support for the <link xlink:href="http://www.palm.com/">Palm&trade;</link> series.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>parallel*</filename></entry>
+ <entry xml:lang="en">Applications dealing with parallelism in
+ computing.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>parallel*</filename></entry>
- <entry>Applications dealing with parallelism in computing.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>pear*</filename></entry>
+ <entry xml:lang="en">Ports related to the Pear PHP
+ framework.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>pear*</filename></entry>
- <entry>Ports related to the Pear PHP framework.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>perl5*</filename></entry>
+ <entry xml:lang="en">Ports that require
+ <application>Perl</application> version 5 to
+ run.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>perl5*</filename></entry>
- <entry>Ports that require <application>Perl</application> version 5 to run.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>plan9*</filename></entry>
- <row>
- <entry><filename>plan9*</filename></entry>
- <entry>Various programs from <link xlink:href="http://www.cs.bell-labs.com/plan9dist/">Plan9</link>.</entry>
- <entry/>
- </row>
+ <entry xml:lang="en">Various programs from <link xlink:href="http://www.cs.bell-labs.com/plan9dist/">Plan9</link>.</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>polish</filename></entry>
- <entry>Polish language support.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>polish</filename></entry>
+ <entry>波蘭文支援。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>ports-mgmt</filename></entry>
- <entry>FreeBSD ports 及 packages 的管理、安裝、開發。</entry>
- </row>
+ <row>
+ <entry><filename>ports-mgmt</filename></entry>
+ <entry xml:lang="en">Ports for managing, installing and developing
+ FreeBSD ports and packages.</entry>
+ </row>
- <row>
- <entry><filename>portuguese</filename></entry>
- <entry>Portuguese language support.</entry>
- <entry/>
- </row>
+ <row>
+ <entry><filename>portuguese</filename></entry>
+ <entry>葡萄牙文支援。</entry>
+ <entry/>
+ </row>
- <row>
- <entry><filename>print</filename></entry>
- <entry>Printing software.</entry>
- <entry>Desktop publishing tools
- (previewers, etc.) belong here too.</entry>
- </row>
+ <row>
+ <entry><filename>print</filename></entry>
+ <entry>列印軟體。</entry>
+ <entry xml:lang="en">Desktop publishing tools
+ (previewers, etc.) belong here too.</entry>
+ </row>
+
+ <row>
+ <entry><filename>python*</filename></entry>
+
+ <entry xml:lang="en">Software related to the <link xlink:href="http://www.python.org/">Python</link>
+ language.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>ruby*</filename></entry>
+ <entry xml:lang="en">Software related to the <link xlink:href="http://www.ruby-lang.org/">Ruby</link>
+ language.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>rubygems*</filename></entry>
+
+ <entry xml:lang="en">Ports of <link xlink:href="http://www.rubygems.org/">RubyGems</link>
+ packages.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>russian</filename></entry>
+ <entry>俄文支援。</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>scheme*</filename></entry>
+ <entry xml:lang="en">Software related to the Scheme
+ language.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>science</filename></entry>
+ <entry xml:lang="en">Scientific ports that do not fit into other
+ categories such as <filename>astro</filename>,
+ <filename>biology</filename> and
+ <filename>math</filename>.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>security</filename></entry>
+ <entry xml:lang="en">Security utilities.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>shells</filename></entry>
+ <entry xml:lang="en">Command line shells.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>spanish*</filename></entry>
+ <entry>西班牙文支援。</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>sysutils</filename></entry>
+ <entry>系統公用程式。</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>tcl*</filename></entry>
+ <entry xml:lang="en">Ports that use Tcl to run.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>textproc</filename></entry>
+ <entry xml:lang="en">Text processing utilities.</entry>
+ <entry xml:lang="en">It does not include desktop publishing tools,
+ which go to <filename>print</filename>.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk*</filename></entry>
+ <entry xml:lang="en">Ports that use Tk to run.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>ukrainian</filename></entry>
+ <entry>烏克蘭文支援</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>vietnamese</filename></entry>
+ <entry>越南文支援。</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>windowmaker*</filename></entry>
+ <entry xml:lang="en">Ports to support the WindowMaker window
+ manager.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>www</filename></entry>
+ <entry xml:lang="en">Software related to the World Wide Web.</entry>
+ <entry xml:lang="en">HTML language
+ support belongs here too.</entry>
+ </row>
+ <row>
+ <entry><filename>x11</filename></entry>
+ <entry>X Window 系統和他的朋友們。</entry>
+ <entry xml:lang="en">This category is only for software that directly
+ supports the window system. Do not put regular X
+ applications here. Most of them go into other
+ <filename>x11-*</filename> categories (see
+ below).</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-clocks</filename></entry>
+ <entry>X11 時鐘。</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>x11-drivers</filename></entry>
+ <entry>X11 驅動程式。</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>x11-fm</filename></entry>
+ <entry xml:lang="en">X11 file managers.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>x11-fonts</filename></entry>
+ <entry xml:lang="en">X11 fonts and font utilities.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>x11-servers</filename></entry>
+ <entry>X11 伺服器。</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>x11-themes</filename></entry>
+ <entry>X11 佈景主題。</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>x11-toolkits</filename></entry>
+ <entry xml:lang="en">X11 toolkits.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>x11-wm</filename></entry>
+ <entry xml:lang="en">X11 window managers.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>xfce*</filename></entry>
+ <entry xml:lang="en">Ports related to the
+ <link xlink:href="http://www.xfce.org/">Xfce</link>
+ desktop environment.</entry>
+ <entry/>
+ </row>
+
+ <row>
+ <entry><filename>zope*</filename></entry>
+ <entry xml:lang="en"><link xlink:href="http://www.zope.org/">Zope</link>
+ support.</entry>
+ <entry/>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+
+ <sect2 xml:id="choosing-categories">
+ <title>選擇正確的目錄</title>
+
+ <para xml:lang="en">As many of the categories overlap, choosing which of the
+ categories will be the primary category of the port can be
+ tedious. There are several rules that govern this issue.
+ Here is the list of priorities, in decreasing order of
+ precedence:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para xml:lang="en">The first category must be a physical category (see
+ <link linkend="porting-categories">above</link>). This is
+ necessary to make the packaging work. Virtual categories
+ and physical categories may be intermixed after
+ that.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">Language specific categories always come first. For
+ example, if the port installs Japanese X11 fonts, then
+ the <varname>CATEGORIES</varname> line would read
+ <filename>japanese x11-fonts</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">Specific categories are listed before less-specific
+ ones. For instance, an HTML editor is listed as
+ <filename>www editors</filename>, not the other way
+ around. Also, do not list
+ <filename>net</filename> when the port belongs to any of
+ <filename>irc</filename>, <filename>mail</filename>,
+ <filename>news</filename>, <filename>security</filename>,
+ or <filename>www</filename>, as <filename>net</filename>
+ is included implicitly.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><filename>x11</filename> is used as a secondary
+ category only when the primary category is a natural
+ language. In particular, do not put
+ <filename>x11</filename> in the category line for X
+ applications.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><application>Emacs</application> modes are
+ placed in the same ports category as the application
+ supported by the mode, not in
+ <filename>editors</filename>. For example, an
+ <application>Emacs</application> mode to edit source files
+ of some programming language goes into
+ <filename>lang</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">Ports installing loadable kernel modules also
+ have the virtual category <filename>kld</filename> in
+ their <varname>CATEGORIES</varname> line. This is one of
+ the things handled automatically by adding
+ <literal>USES=kmod</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><filename>misc</filename> does not appear with any
+ other non-virtual category. If there is
+ <literal>misc</literal> with something else in
+ <varname>CATEGORIES</varname>, that means
+ <literal>misc</literal> can safely be deleted and the port
+ placed only in the other subdirectory.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">If the port truly does not belong anywhere else,
+ put it in <filename>misc</filename>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para xml:lang="en">If the category is not clearly defined, please put a
+ comment to that effect in the <link xlink:href="https://bugs.freebsd.org/submit/">port
+ submission</link> in the bug database so
+ we can discuss it before we import it. As a committer,
+ send a note to the <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports">FreeBSD ports mailing list</link> so we can discuss it
+ first. Too often, new ports are imported to the wrong
+ category only to be moved right away. This causes unnecessary
+ and undesirable bloat in the master source repository.</para>
+ </sect2>
+
+ <sect2 xml:id="proposing-categories">
+ <title>提出新的目錄</title>
+
+ <para xml:lang="en">As the Ports Collection has grown over time, various new
+ categories have been introduced. New categories can either be
+ <emphasis>virtual</emphasis> categories—those that do
+ not have a corresponding subdirectory in the ports tree—
+ or <emphasis>physical</emphasis> categories—those that
+ do. This section discusses the issues involved in creating a
+ new physical category. Read it thouroughly before proposing a
+ new one.</para>
+
+ <para xml:lang="en">Our existing practice has been to avoid creating a new
+ physical category unless either a large number of ports would
+ logically belong to it, or the ports that would belong to it
+ are a logically distinct group that is of limited general
+ interest (for instance, categories related to spoken human
+ languages), or preferably both.</para>
+
+ <para xml:lang="en">The rationale for this is that such a change creates a
+ <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/committers-guide/#ports">fair
+ amount of work</link> for both the committers and also for
+ all users who track changes to the Ports Collection. In
+ addition, proposed category changes just naturally seem to
+ attract controversy. (Perhaps this is because there is no
+ clear consensus on when a category is <quote>too big</quote>,
+ nor whether categories should lend themselves to browsing (and
+ thus what number of categories would be an ideal number), and
+ so forth.)</para>
+
+ <para>步驟如下:</para>
+
+ <procedure>
+ <step>
+ <para xml:lang="en">Propose the new category on <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports">FreeBSD ports mailing list</link>. Include
+ a detailed rationale for the new category,
+ including why the existing categories are not
+ sufficient, and the list of existing ports proposed to
+ move. (If there are new ports pending in
+ <application>Bugzilla</application> that would fit this
+ category, list them too.) If you are the maintainer
+ and/or submitter, respectively, mention that as it may
+ help the case.</para>
+ </step>
+
+ <step>
+ <para xml:lang="en">Participate in the discussion.</para>
+ </step>
+
+ <step>
+ <para xml:lang="en">If it seems that there is support for the idea, file
+ a PR which includes both the rationale and the list of
+ existing ports that need to be moved. Ideally, this PR
+ would also include these patches:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para xml:lang="en"><filename>Makefile</filename>s for the new ports
+ once they are repocopied</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><filename>Makefile</filename> for the new
+ category</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><filename>Makefile</filename> for the old ports'
+ categories</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><filename>Makefile</filename>s for ports that
+ depend on the old ports</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">(for extra credit, include the other files
+ that have to change, as per the procedure in the
+ Committer's Guide.)</para>
+ </listitem>
+ </itemizedlist>
+ </step>
+
+ <step>
+ <para xml:lang="en">Since it affects the ports infrastructure and involves
+ moving and patching many ports but also possibly running
+ regression tests on the build cluster, assign the PR to
+ the Ports Management Team <email>portmgr@FreeBSD.org</email>.</para>
+ </step>
+
+ <step>
+ <para xml:lang="en">If that PR is approved, a committer will need to
+ follow the rest of the procedure that is <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/committers-guide/article.html#PORTS">outlined
+ in the Committer's Guide</link>.</para>
+ </step>
+ </procedure>
+
+ <para xml:lang="en">Proposing a new virtual category is similar to the
+ above but much less involved, since no ports will actually
+ have to move. In this case, the only patches to include in
+ the PR would be those to add the new category to
+ <varname>CATEGORIES</varname> of the affected ports.</para>
+ </sect2>
+
+ <sect2 xml:id="proposing-reorg">
+ <title xml:lang="en">Proposing Reorganizing All the Categories</title>
+
+ <para xml:lang="en">Occasionally someone proposes reorganizing the
+ categories with either a 2-level structure, or some other kind
+ of keyword structure. To date, nothing has come of any of
+ these proposals because, while they are very easy to make, the
+ effort involved to retrofit the entire existing ports
+ collection with any kind of reorganization is daunting to say
+ the very least. Please read the history of these proposals in
+ the mailing list archives before posting this idea.
+ Furthermore, be prepared to be challenged to offer
+ a working prototype.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="makefile-distfiles">
+ <title xml:lang="en">The Distribution Files</title>
+
+ <para xml:lang="en">The second part of the <filename>Makefile</filename>
+ describes the files that must be downloaded to build
+ the port, and where they can be downloaded.</para>
+
+ <sect2 xml:id="makefile-distversion">
+ <title><varname>DISTVERSION/DISTNAME</varname></title>
+
+ <para xml:lang="en"><varname>DISTNAME</varname> is the name of the port as
+ called by the authors of the software.
+ <varname>DISTNAME</varname> defaults to
+ <literal>${PORTNAME}-${DISTVERSIONPREFIX}${DISTVERSION}${DISTVERSIONSUFFIX}</literal>,
+ and <varname>DISTVERSION</varname> defaults to
+ <literal>${PORTVERSION}</literal> so override it
+ only if necessary. <varname>DISTNAME</varname> is only used
+ in two places. First, the distribution file list
+ (<varname>DISTFILES</varname>) defaults to
+ <literal>${DISTNAME}</literal><literal>${EXTRACT_SUFX}</literal>.
+ Second, the distribution file is expected to extract into a
+ subdirectory named <varname>WRKSRC</varname>, which defaults
+ to <filename>work/${DISTNAME}</filename>.</para>
+
+ <para xml:lang="en">Some vendor's distribution names which do not fit into the
+ <literal>${PORTNAME}-${PORTVERSION}</literal>-scheme can be
+ handled automatically by setting
+ <varname>DISTVERSION</varname>.
+ <varname>PORTVERSION</varname> will be derived from it
+ automatically.</para>
+
+ <note>
+ <para xml:lang="en">Only one of <varname>PORTVERSION</varname> and
+ <varname>DISTVERSION</varname> can be set at a time. If
+ <varname>DISTVERSION</varname> does not derive a correct
+ <varname>PORTVERSION</varname>, do not use
+ <varname>DISTVERSION</varname>, set
+ <varname>PORTVERSION</varname> to the right value and set
+ <varname>DISTNAME</varname> with <varname>PORTNAME</varname>
+ with either some computation of
+ <varname>PORTVERSION</varname> or the verbatim upstream
+ version.</para>
+ </note>
+
+
+ <table frame="none" pgwide="0">
+ <title xml:lang="en">Examples of <varname>DISTVERSION</varname> and the
+ Derived <varname>PORTVERSION</varname></title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry><varname>DISTVERSION</varname></entry>
+ <entry><varname>PORTVERSION</varname></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>0.7.1d</entry>
+ <entry>0.7.1.d</entry>
+ </row>
+
+ <row>
+ <entry>10Alpha3</entry>
+ <entry>10.a3</entry>
+ </row>
+
+ <row>
+ <entry>3Beta7-pre2</entry>
+ <entry>3.b7.p2</entry>
+ </row>
+
+ <row>
+ <entry>8:f_17</entry>
+ <entry>8f.17</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <note>
+ <para xml:lang="en"><varname>PKGNAMEPREFIX</varname> and
+ <varname>PKGNAMESUFFIX</varname> do not affect
+ <varname>DISTNAME</varname>. Also note that if
+ <varname>WRKSRC</varname> is equal to
+ <filename>${WRKDIR}/${DISTNAME}</filename> while
+ the original source archive is named something other than
+ <literal>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</literal>,
+ leave <varname>DISTNAME</varname>
+ alone— defining only
+ <varname>DISTFILES</varname> is easier than both
+ <varname>DISTNAME</varname> and <varname>WRKSRC</varname>
+ (and possibly <varname>EXTRACT_SUFX</varname>).</para>
+ </note>
+ </sect2>
+
+ <sect2 xml:id="makefile-master_sites">
+ <title><varname>MASTER_SITES</varname></title>
+
+ <para xml:lang="en">Record the directory part of the FTP/HTTP-URL pointing at
+ the original tarball in <varname>MASTER_SITES</varname>. Do
+ not forget the trailing slash (<filename>/</filename>)!</para>
+
+ <para xml:lang="en">The <command>make</command> macros will try to use this
+ specification for grabbing the distribution file with
+ <varname>FETCH</varname> if they cannot find it already on the
+ system.</para>
+
+ <para xml:lang="en">It is recommended that multiple sites are included on this
+ list, preferably from different continents. This will
+ safeguard against wide-area network problems. We are even
+ planning to add support for automatically determining the
+ closest master site and fetching from there; having multiple
+ sites will go a long way towards helping this effort.</para>
+
+ <important>
+ <para xml:lang="en"><varname>MASTER_SITES</varname> must not be blank. It
+ must point to the actual site hosting the distribution
+ files. It cannot point to web archives, or the FreeBSD
+ distribution files cache sites. The only exception to this
+ rule is ports that do not have any distribution files. For
+ example, meta-ports do not have any distribution files, so
+ <varname>MASTER_SITES</varname> does not need to be
+ set.</para>
+ </important>
+
+ <sect3 xml:id="makefile-master_sites-shorthand">
+ <title>使用 <varname>MASTER_SITE_<replaceable>*</replaceable></varname> 變數</title>
+
+ <para xml:lang="en">Shortcut abbreviations are available for popular
+ archives like SourceForge (<literal>SOURCEFORGE</literal>),
+ GNU (<literal>GNU</literal>), or Perl CPAN
+ (<literal>PERL_CPAN</literal>).
+ <varname>MASTER_SITES</varname> can use them
+ directly:</para>
+
+ <programlisting>MASTER_SITES= GNU/make</programlisting>
+
+ <para xml:lang="en">The older expanded format still works, but all ports
+ have been converted to the compact format. The expanded
+ format looks like this:</para>
+
+ <programlisting>MASTER_SITES= ${MASTER_SITE_GNU}
+MASTER_SITE_SUBDIR= make</programlisting>
+
+ <para xml:lang="en">These values and variables are defined in <link xlink:href="https://svnweb.freebsd.org/ports/head/Mk/bsd.sites.mk?view=markup"><filename>Mk/bsd.sites.mk</filename></link>.
+ New entries are added often, so make sure to check the
+ latest version of this file before submitting a port.</para>
+
+ <tip>
+ <para xml:lang="en">For any
+ <varname>MASTER_SITE_<replaceable>FOO</replaceable></varname>
+ variable, the shorthand
+ <literal><replaceable>FOO</replaceable></literal> can be
+ used. For example, use:</para>
+
+ <programlisting>MASTER_SITES= <replaceable>FOO</replaceable></programlisting>
+
+ <para xml:lang="en">If <varname>MASTER_SITE_SUBDIR</varname> is needed,
+ use this:</para>
+
+ <programlisting>MASTER_SITES= <replaceable>FOO</replaceable>/<replaceable>bar</replaceable></programlisting>
+ </tip>
+
+ <note>
+ <para xml:lang="en">Some
+ <varname>MASTER_SITE_<replaceable>*</replaceable></varname>
+ names are quite long, and for ease of use, shortcuts have
+ been defined:</para>
+
+ <table frame="none" xml:id="makefile-master_sites-shortcut">
+ <title xml:lang="en">Shortcuts for
+ <varname>MASTER_SITE_<replaceable>*</replaceable></varname>
+ Macros</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>巨集</entry>
+ <entry xml:lang="en">Shortcut</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><varname>PERL_CPAN</varname></entry>
+ <entry><varname>CPAN</varname></entry>
+ </row>
+
+ <row>
+ <entry><varname>GITHUB</varname></entry>
+ <entry><varname>GH</varname></entry>
+ </row>
+
+ <row>
+ <entry><varname>GITHUB_CLOUD</varname></entry>
+ <entry><varname>GHC</varname></entry>
+ </row>
+
+ <row>
+ <entry><varname>LIBREOFFICE_DEV</varname></entry>
+ <entry><varname>LODEV</varname></entry>
+ </row>
+
+ <row>
+ <entry><varname>NETLIB</varname></entry>
+ <entry><varname>NL</varname></entry>
+ </row>
+
+ <row>
+ <entry><varname>RUBYGEMS</varname></entry>
+ <entry><varname>RG</varname></entry>
+ </row>
+
+ <row>
+ <entry><varname>SOURCEFORGE</varname></entry>
+ <entry><varname>SF</varname></entry>
+ </row>
+
+ <row>
+ <entry><varname>SOURCEFORGE_JP</varname></entry>
+ <entry><varname>SFJP</varname></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </note>
+ </sect3>
+
+ <sect3 xml:id="makefile-master_sites-magic">
+ <title xml:lang="en">Magic MASTER_SITES Macros</title>
+
+ <para xml:lang="en">Several <quote>magic</quote> macros exist for
+ popular sites with a predictable directory structure. For
+ these, just use the abbreviation and the system will choose
+ a subdirectory automatically. For a port
+ named <literal>Stardict</literal>, of version
+ <literal>1.2.3</literal>, and hosted on SourceForge, adding
+ this line:</para>
+
+ <programlisting>MASTER_SITES= SF</programlisting>
+
+ <para xml:lang="en">infers a subdirectory named
+ <literal>/project/stardict/stardict/1.2.3</literal>. If the
+ inferred directory is incorrect, it can be
+ overridden:</para>
+
+ <programlisting>MASTER_SITES= SF/stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting>
+
+ <para xml:lang="en">This can also be written as</para>
+
+ <programlisting>MASTER_SITES= SF
+MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting>
+
+ <table frame="none" xml:id="makefile-master_sites-popular">
+ <title xml:lang="en">Magic <varname>MASTER_SITES</varname>
+ Macros</title>
+
+ <tgroup cols="2">
+ <thead>
<row>
- <entry><filename>python*</filename></entry>
- <entry>Software related to the <link xlink:href="http://www.python.org/">Python</link> language.</entry>
- <entry/>
+ <entry>巨集</entry>
+ <entry xml:lang="en">Assumed subdirectory</entry>
</row>
+ </thead>
+ <tbody>
<row>
- <entry><filename>ruby*</filename></entry>
- <entry>Software related to the <link xlink:href="http://www.ruby-lang.org/">Ruby</link> language.</entry>
- <entry/>
+ <entry><varname>APACHE_COMMONS_BINARIES</varname></entry>
+ <entry><literal>${PORTNAME:S,commons-,,}</literal></entry>
</row>
<row>
- <entry><filename>rubygems*</filename></entry>
- <entry>Ports of <link xlink:href="http://www.rubygems.org/">RubyGems</link> packages.</entry>
- <entry/>
+ <entry><varname>APACHE_COMMONS_SOURCE</varname></entry>
+ <entry><literal>${PORTNAME:S,commons-,,}</literal></entry>
</row>
<row>
- <entry><filename>russian</filename></entry>
- <entry>Russian language support.</entry>
- <entry/>
+ <entry><varname>APACHE_JAKARTA</varname></entry>
+ <entry><literal>${PORTNAME:S,-,/,}/source</literal></entry>
</row>
<row>
- <entry><filename>scheme*</filename></entry>
- <entry>Software related to the Scheme language.</entry>
- <entry/>
+ <entry><varname>BERLIOS</varname></entry>
+ <entry><literal>${PORTNAME:tl}.berlios</literal></entry>
</row>
<row>
- <entry><filename>science</filename></entry>
- <entry>Scientific ports that do not fit into other
- categories such as <filename>astro</filename>,
- <filename>biology</filename> and
- <filename>math</filename>.</entry>
- <entry/>
+ <entry><varname>CHEESESHOP</varname></entry>
+ <entry><literal>source/${DISTNAME:C/(.).*/\1/}/${DISTNAME:C/(.*)-[0-9].*/\1/}</literal></entry>
</row>
<row>
- <entry><filename>security</filename></entry>
- <entry>Security utilities.</entry>
- <entry/>
+ <entry><varname>CPAN</varname></entry>
+ <entry><literal>${PORTNAME:C/-.*//}</literal></entry>
</row>
<row>
- <entry><filename>shells</filename></entry>
- <entry>Command line shells.</entry>
- <entry/>
+ <entry><varname>DEBIAN</varname></entry>
+ <entry><literal>pool/main/${PORTNAME:C/^((lib)?.).*$/\1/}/${PORTNAME}</literal></entry>
</row>
<row>
- <entry><filename>spanish*</filename></entry>
- <entry>西班牙文的相關支援。</entry>
- <entry/>
+ <entry><varname>FARSIGHT</varname></entry>
+ <entry><literal>${PORTNAME}</literal></entry>
</row>
<row>
- <entry><filename>sysutils</filename></entry>
- <entry>System utilities.</entry>
- <entry/>
+ <entry><varname>FESTIVAL</varname></entry>
+ <entry><literal>${PORTREVISION}</literal></entry>
</row>
<row>
- <entry><filename>tcl*</filename></entry>
- <entry>使用 Tcl 語言的軟體。</entry>
- <entry/>
+ <entry><varname>GCC</varname></entry>
+ <entry><literal>releases/${DISTNAME}</literal></entry>
</row>
<row>
- <entry><filename>textproc</filename></entry>
- <entry>Text processing utilities.</entry>
- <entry>It does not include
- desktop publishing tools, which go to <filename>print</filename>.</entry>
+ <entry><varname>GENTOO</varname></entry>
+ <entry><literal>distfiles</literal></entry>
</row>
<row>
- <entry><filename>tk*</filename></entry>
- <entry>使用 Tk 語言的程式。</entry>
- <entry/>
+ <entry><varname>GIMP</varname></entry>
+ <entry><literal>${PORTNAME}/${PORTVERSION:R}/</literal></entry>
</row>
<row>
- <entry><filename>ukrainian</filename></entry>
- <entry>Ukrainian language support.</entry>
- <entry/>
+ <entry><varname>GH</varname></entry>
+ <entry><literal>${GH_ACCOUNT}/${GH_PROJECT}/tar.gz/${GH_TAGNAME}?dummy=/</literal></entry>
</row>
<row>
- <entry><filename>vietnamese</filename></entry>
- <entry>Vietnamese language support.</entry>
- <entry/>
+ <entry><varname>GHC</varname></entry>
+ <entry><literal>${GH_ACCOUNT}/${GH_PROJECT}/</literal></entry>
</row>
<row>
- <entry><filename>windowmaker*</filename></entry>
- <entry>Ports to support the WindowMaker window
- manager.</entry>
- <entry/>
+ <entry><varname>GNOME</varname></entry>
+ <entry><literal>sources/${PORTNAME}/${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}</literal></entry>
</row>
<row>
- <entry><filename>www</filename></entry>
- <entry>Software related to the World Wide Web.</entry>
- <entry>HTML language
- support belongs here too.</entry>
+ <entry><varname>GNU</varname></entry>
+ <entry><literal>${PORTNAME}</literal></entry>
</row>
<row>
- <entry><filename>x11</filename></entry>
- <entry>The X Window System and friends.</entry>
- <entry>This category is only
- for software that directly supports the window system. Do not
- put regular X applications here; most of them should go
- into other <filename>x11-*</filename> categories (see below).
- If your port <emphasis>is</emphasis> an X
- application, define <varname>USE_XLIB</varname> (implied by
- <varname>USE_IMAKE</varname>) and put it in the appropriate
- category.</entry>
+ <entry><varname>GNUPG</varname></entry>
+ <entry><literal>${PORTNAME}</literal></entry>
</row>
<row>
- <entry><filename>x11-clocks</filename></entry>
- <entry>X11 clocks.</entry>
- <entry/>
+ <entry><varname>GNU_ALPHA</varname></entry>
+ <entry><literal>${PORTNAME}</literal></entry>
</row>
<row>
- <entry><filename>x11-drivers</filename></entry>
- <entry>X11 驅動程式。</entry>
- <entry/>
+ <entry><varname>HORDE</varname></entry>
+ <entry><literal>${PORTNAME}</literal></entry>
</row>
<row>
- <entry><filename>x11-fm</filename></entry>
- <entry>X11 file managers.</entry>
- <entry/>
+ <entry><varname>LODEV</varname></entry>
+ <entry><literal>${PORTNAME}</literal></entry>
</row>
<row>
- <entry><filename>x11-fonts</filename></entry>
- <entry>X11 fonts and font utilities.</entry>
- <entry/>
+ <entry><varname>MATE</varname></entry>
+ <entry><literal>${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}</literal></entry>
</row>
<row>
- <entry><filename>x11-servers</filename></entry>
- <entry>X11 servers.</entry>
- <entry/>
+ <entry><varname>MOZDEV</varname></entry>
+ <entry><literal>${PORTNAME:tl}</literal></entry>
</row>
<row>
- <entry><filename>x11-themes</filename></entry>
- <entry>X11 themes.</entry>
- <entry/>
+ <entry><varname>NL</varname></entry>
+ <entry><literal>${PORTNAME}</literal></entry>
</row>
<row>
- <entry><filename>x11-toolkits</filename></entry>
- <entry>X11 toolkits.</entry>
- <entry/>
+ <entry><varname>QT</varname></entry>
+ <entry><literal>archive/qt/${PORTVERSION:R}</literal></entry>
</row>
<row>
- <entry><filename>x11-wm</filename></entry>
- <entry>X11 window managers.</entry>
- <entry/>
+ <entry><varname>SAMBA</varname></entry>
+ <entry><literal>${PORTNAME}</literal></entry>
</row>
<row>
- <entry><filename>xfce*</filename></entry>
- <entry><link xlink:href="http://www.xfce.org/">Xfce</link>
- 桌面環境的相關軟體。</entry>
- <entry/>
+ <entry><varname>SAVANNAH</varname></entry>
+ <entry><literal>${PORTNAME:tl}</literal></entry>
</row>
<row>
- <entry><filename>zope*</filename></entry>
- <entry><link xlink:href="http://www.zope.org/">Zope</link> support.</entry>
- <entry/>
+ <entry><varname>SF</varname></entry>
+ <entry><literal>${PORTNAME:tl}/${PORTNAME:tl}/${PORTVERSION}</literal></entry>
</row>
</tbody>
</tgroup>
- </informaltable>
- </sect2>
+ </table>
+ </sect3>
+ </sect2>
- <sect2 xml:id="choosing-categories">
- <title>Choosing the right category</title>
+ <sect2 xml:id="makefile-master_sites-github">
+ <title><varname>USE_GITHUB</varname></title>
- <para>As many of the categories overlap, you often have to choose
- which of the categories should be the primary category of your port.
- There are several rules that govern this issue. Here is the list of
- priorities, in decreasing order of precedence:</para>
+ <para xml:lang="en">If the distribution file comes from a specific commit or
+ tag on <link xlink:href="https://github.com">GitHub</link>
+ for which there is no officially released file, there is an
+ easy way to set the right <varname>DISTNAME</varname> and
+ <varname>MASTER_SITES</varname> automatically. These
+ variables are available:</para>
- <itemizedlist>
+ <table xml:id="makefile-master_sites-github-description">
+ <title xml:lang="en"><varname>USE_GITHUB</varname> Description</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry xml:lang="en">Variable</entry>
+ <entry>描述</entry>
+ <entry xml:lang="en">Default</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><varname>GH_ACCOUNT</varname></entry>
+ <entry xml:lang="en">Account name of the GitHub user hosting the
+ project</entry>
+ <entry><literal>${PORTNAME}</literal></entry>
+ </row>
+
+ <row>
+ <entry><varname>GH_PROJECT</varname></entry>
+ <entry xml:lang="en">Name of the project on GitHub</entry>
+ <entry><literal>${PORTNAME}</literal></entry>
+ </row>
+
+
+ <row>
+ <entry><varname>GH_TAGNAME</varname></entry>
+ <entry xml:lang="en">Name of the tag to download (2.0.1, hash, ...)
+ Using the name of a branch here is incorrect. It is
+ also possible to use the hash of a commit id to do a
+ snapshot.</entry>
+ <entry><literal>${DISTVERSIONPREFIX}${DISTVERSION}${DISTVERSIONSUFFIX}</literal></entry>
+ </row>
+
+ <row>
+ <entry><varname>GH_TUPLE</varname></entry>
+ <entry xml:lang="en"><varname>GH_TUPLE</varname> allows putting all
+ the <varname>GH_ACCOUNT</varname>,
+ <varname>GH_PROJECT</varname>, and
+ <varname>GH_TAGNAME</varname> into one variable. The
+ format is
+ <replaceable>account</replaceable><literal>:</literal><replaceable>project</replaceable><literal>:</literal><replaceable>tagname</replaceable><literal>:</literal><replaceable>group</replaceable>.
+ It is helpful when there is more than one GitHub
+ project from which to fetch.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <important>
+ <para xml:lang="en">Do not use <varname>GH_TUPLE</varname> for the default
+ distribution file, as it has no default.</para>
+ </important>
+
+ <example xml:id="makefile-master_sites-github-ex1">
+ <title xml:lang="en">Simple Use of <varname>USE_GITHUB</varname></title>
+
+ <para xml:lang="en">While trying to make a port for version
+ <literal>1.2.7</literal> of <application>pkg</application>
+ from the FreeBSD user on github, at <link xlink:href="https://github.com/freebsd/pkg"/>, The
+ <filename>Makefile</filename> would end up looking like
+ this (slightly stripped for the example):</para>
+
+ <programlisting>PORTNAME= pkg
+PORTVERSION= 1.2.7
+
+USE_GITHUB= yes
+GH_ACCOUNT= freebsd</programlisting>
+
+ <para xml:lang="en">It will automatically have
+ <varname>MASTER_SITES</varname> set to <literal>GH
+ GHC</literal> and <varname>WRKSRC</varname> to
+ <literal>${WRKDIR}/pkg-1.2.7</literal>.</para>
+ </example>
+
+ <example xml:id="makefile-master_sites-github-ex2">
+ <title xml:lang="en">More Complete Use of
+ <varname>USE_GITHUB</varname></title>
+
+ <para xml:lang="en">While trying to make a port for the bleeding edge
+ version of <application>pkg</application> from the FreeBSD
+ user on github, at <link xlink:href="https://github.com/freebsd/pkg"/>, the
+ <filename>Makefile</filename> ends up looking like
+ this (slightly stripped for the example):</para>
+
+ <programlisting>PORTNAME= pkg-devel
+PORTVERSION= 1.3.0.a.20140411
+
+USE_GITHUB= yes
+GH_ACCOUNT= freebsd
+GH_PROJECT= pkg
+GH_TAGNAME= 6dbb17b</programlisting>
+
+ <para xml:lang="en">It will automatically have
+ <varname>MASTER_SITES</varname> set to <literal>GH
+ GHC</literal> and <varname>WRKSRC</varname> to
+ <literal>${WRKDIR}/pkg-6dbb17b</literal>.</para>
+ </example>
+
+ <example xml:id="makefile-master_sites-github-ex3">
+ <title xml:lang="en">Use of <varname>USE_GITHUB</varname> with
+ <varname>DISTVERSIONPREFIX</varname></title>
+
+ <para xml:lang="en">From time to time, <varname>GH_TAGNAME</varname> is a
+ slight variation from <varname>DISTVERSION</varname>.
+ For example, if the version is <literal>1.0.2</literal>,
+ the tag is <literal>v1.0.2</literal>. In those cases, it
+ is possible to use <varname>DISTVERSIONPREFIX</varname> or
+ <varname>DISTVERSIONSUFFIX</varname>:</para>
+
+ <programlisting xml:lang="en">PORTNAME= foo
+PORTVERSION= 1.0.2
+DISTVERSIONPREFIX= v
+
+USE_GITHUB= yes</programlisting>
+
+ <para xml:lang="en">It will automatically set
+ <varname>GH_TAGNAME</varname> to
+ <literal>v1.0.2</literal>, while <varname>WRKSRC</varname>
+ will be kept to
+ <varname>${WRKDIR}/foo-1.0.2</varname>.</para>
+ </example>
+
+ <sect3 xml:id="makefile-master_sites-github-multiple">
+ <title xml:lang="en">Fetching Multiple Files from GitHub</title>
+
+ <para xml:lang="en">The <varname>USE_GITHUB</varname> framework also
+ supports fetching multiple distribution files from
+ different places in GitHub. It works in a way very
+ similar to <xref linkend="porting-master-sites-n"/>.</para>
+
+ <para xml:lang="en">Multiple values are added to
+ <varname>GH_ACCOUNT</varname>,
+ <varname>GH_PROJECT</varname>, and
+ <varname>GH_TAGNAME</varname>. Each different value is
+ assigned a tag. The main value can either have no tag, or
+ the <literal>:DEFAULT</literal> tag. A value can be
+ omitted if it is the same as the default as listed in
+ <xref linkend="makefile-master_sites-github-description"/>.</para>
+
+ <para xml:lang="en"><varname>GH_TUPLE</varname> can also be used when there
+ are a lot of distribution files. It helps keep the account,
+ project, tagname, and group information at the same
+ place.</para>
+
+ <para xml:lang="en">For each tag, a
+ <varname>${WRKSRC_<replaceable>tag</replaceable>}</varname>
+ helper variable is created, containing the directory into
+ which the file has been extracted. The
+ <varname>${WRKSRC_<replaceable>tag</replaceable>}</varname>
+ variables can be used to move directories around during
+ <buildtarget xml:lang="en">post-extract</buildtarget>, or add to
+ <varname>CONFIGURE_ARGS</varname>, or whatever is needed
+ so that the software builds correctly.</para>
+
+ <example xml:id="makefile-master_sites-github-multi">
+ <title xml:lang="en">Use of <varname>USE_GITHUB</varname> with Multiple
+ Distribution Files</title>
+
+ <para xml:lang="en">From time to time, there is a need to fetch more
+ than one distribution file. For example, when the
+ upstream git repository uses submodules. This can be
+ done easily using tags in the
+ <varname>GH_<replaceable>*</replaceable></varname>
+ variables:</para>
+
+ <programlisting>PORTNAME= foo
+PORTVERSION= 1.0.2
+
+USE_GITHUB= yes
+GH_ACCOUNT= bar:icons,contrib
+GH_PROJECT= foo-icons:icons foo-contrib:contrib
+GH_TAGNAME= 1.0:icons fa579bc:contrib
+
+CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib}
+
+post-extract:
+ @${MV} ${WRKSRC_icons} ${WRKSRC}/icons</programlisting>
+
+ <para xml:lang="en">This will fetch three distribution files from
+ github. The default one comes from
+ <filename>foo/foo</filename> and is version
+ <literal>1.0.2</literal>. The second one, tagged
+ <literal>icons</literal>, comes from
+ <filename>bar/foo-icons</filename> and is in version
+ <literal>1.0</literal>. The third one comes from
+ <filename>bar/foo-contrib</filename> and uses the
+ <application>Git</application> commit
+ <literal>fa579bc</literal>. The distribution files are
+ named <filename>foo-foo-1.0.2_GH0.tar.gz</filename>,
+ <filename>bar-foo-icons-1.0_GH0.tar.gz</filename>, and
+ <filename>bar-foo-contrib-fa579bc_GH0.tar.gz</filename>.</para>
+
+ <para xml:lang="en">All the distribution files are extracted in
+ <varname>${WRKDIR}</varname> in their respective
+ subdirectories. The default file is still extracted in
+ <varname>${WRKSRC}</varname>, in this case,
+ <filename>${WRKDIR}/foo-1.0.2</filename>. Each
+ additional distribution file is extracted in
+ <varname>${WRKSRC_<replaceable>tag</replaceable>}</varname>.
+ Here, for the <literal>icons</literal> tag, it is called
+ <varname>${WRKSRC_icons}</varname> and it contains
+ <filename>${WRKDIR}/foo-icons-1.0</filename>. The file
+ with the <literal>contrib</literal> tag is called
+ <varname>${WRKSRC_contrib}</varname> and contains
+ <literal>${WRKDIR}/foo-contrib-fa579bc</literal>.</para>
+ </example>
+
+ <example xml:id="makefile-master_sites-github-multi2">
+ <title xml:lang="en">Use of <varname>USE_GITHUB</varname> with Multiple
+ Distribution Files Using
+ <varname>GH_TUPLE</varname></title>
+
+ <para xml:lang="en">This is functionally equivalent to <xref linkend="makefile-master_sites-github-multi"/>, but
+ using <varname>GH_TUPLE</varname>:</para>
+
+ <programlisting>PORTNAME= foo
+PORTVERSION= 1.0.2
+
+USE_GITHUB= yes
+GH_TUPLE= bar:foo-icons:1.0:icons \
+ bar:foo-contrib:fa579bc:contrib
+
+CONFIGURE_ARGS= --with-contrib=${WRKSRC_contrib}
+
+post-extract:
+ @${MV} ${WRKSRC_icons} ${WRKSRC}/icons</programlisting>
+
+ <para xml:lang="en">Grouping was used in the previous example with
+ <literal>bar:icons,contrib</literal>. Some redundant
+ information is present with <varname>GH_TUPLE</varname>
+ because grouping is not possible.</para>
+ </example>
+ </sect3>
+ </sect2>
+
+ <sect2 xml:id="makefile-extract_sufx">
+ <title><varname>EXTRACT_SUFX</varname></title>
+
+ <para xml:lang="en">If there is one distribution file, and it uses an odd
+ suffix to indicate the compression mechanism, set
+ <varname>EXTRACT_SUFX</varname>.</para>
+
+ <para xml:lang="en">For example, if the distribution file was named
+ <filename>foo.tar.gzip</filename> instead of the more normal
+ <filename>foo.tar.gz</filename>, write:</para>
+
+ <programlisting>DISTNAME= foo
+EXTRACT_SUFX= .tar.gzip</programlisting>
+
+ <para xml:lang="en">The
+ <literal>USES=tar[:<replaceable>xxx</replaceable>]</literal>,
+ <literal>USES=lha</literal> or <literal>USES=zip</literal>
+ automatically set <varname>EXTRACT_SUFX</varname> to the most
+ common archives extensions as necessary, see <xref linkend="uses-values"/> for more details. If neither of
+ these are set then <varname>EXTRACT_SUFX</varname> defaults to
+ <literal>.tar.gz</literal>.</para>
+
+ <note>
+ <para xml:lang="en">As <varname>EXTRACT_SUFX</varname> is only used in
+ <varname>DISTFILES</varname>, only set one of them..</para>
+ </note>
+ </sect2>
+
+ <sect2 xml:id="makefile-distfiles-definition">
+ <title><varname>DISTFILES</varname></title>
+
+ <para xml:lang="en">Sometimes the names of the files to be downloaded have no
+ resemblance to the name of the port. For example, it might be
+ called <filename>source.tar.gz</filename> or similar. In
+ other cases the application's source code might be in several
+ different archives, all of which must be downloaded.</para>
+
+ <para xml:lang="en">If this is the case, set <varname>DISTFILES</varname> to
+ be a space separated list of all the files that must be
+ downloaded.</para>
+
+ <programlisting>DISTFILES= source1.tar.gz source2.tar.gz</programlisting>
+
+ <para xml:lang="en">If not explicitly set, <varname>DISTFILES</varname>
+ defaults to
+ <literal>${DISTNAME}${EXTRACT_SUFX}</literal>.</para>
+ </sect2>
+
+ <sect2 xml:id="makefile-extract_only">
+ <title><varname>EXTRACT_ONLY</varname></title>
+
+ <para xml:lang="en">If only some of the <varname>DISTFILES</varname> must be
+ extracted—for example, one of them is the source code,
+ while another is an uncompressed document—list the
+ filenames that must be extracted in
+ <varname>EXTRACT_ONLY</varname>.</para>
+
+ <programlisting>DISTFILES= source.tar.gz manual.html
+EXTRACT_ONLY= source.tar.gz</programlisting>
+
+ <para xml:lang="en">When none of the <varname>DISTFILES</varname> need to be
+ uncompressed, set <varname>EXTRACT_ONLY</varname> to the empty
+ string.</para>
+
+ <programlisting>EXTRACT_ONLY=</programlisting>
+ </sect2>
+
+ <sect2 xml:id="porting-patchfiles">
+ <title xml:lang="en"><varname>PATCHFILES</varname></title>
+
+ <para xml:lang="en">If the port requires some additional patches that are
+ available by <acronym>FTP</acronym> or
+ <acronym>HTTP</acronym>, set <varname>PATCHFILES</varname> to
+ the names of the files and <varname>PATCH_SITES</varname> to
+ the URL of the directory that contains them (the format is the
+ same as <varname>MASTER_SITES</varname>).</para>
+
+ <para xml:lang="en">If the patch is not relative to the top of the source tree
+ (that is, <varname>WRKSRC</varname>) because it contains some
+ extra pathnames, set <varname>PATCH_DIST_STRIP</varname>
+ accordingly. For instance, if all the pathnames in the patch
+ have an extra <literal>foozolix-1.0/</literal> in front of the
+ filenames, then set
+ <literal>PATCH_DIST_STRIP=-p1</literal>.</para>
+
+ <para xml:lang="en">Do not worry if the patches are compressed; they will be
+ decompressed automatically if the filenames end with
+ <filename>.Z</filename>, <filename>.gz</filename>,
+ <filename>.bz2</filename> or <filename>.xz</filename>.</para>
+
+ <para xml:lang="en">If the patch is distributed with some other files, such as
+ documentation, in a <command>gzip</command>ped tarball, using
+ <varname>PATCHFILES</varname> is not possible. If that is the
+ case, add the name and the location of the patch tarball to
+ <varname>DISTFILES</varname> and
+ <varname>MASTER_SITES</varname>. Then, use
+ <varname>EXTRA_PATCHES</varname> to point to those
+ files and <filename>bsd.port.mk</filename> will automatically
+ apply them. In particular, do
+ <emphasis>not</emphasis> copy patch files into
+ <filename>${PATCHDIR}</filename>. That directory may
+ not be writable.</para>
+
+ <tip>
+ <para xml:lang="en">If there are multiple patches and they need mixed values
+ for the strip parameter, it can be added alongside the patch
+ name in <varname>PATCHFILES</varname>, e.g:</para>
+
+ <programlisting xml:lang="en">PATCHFILES= patch1 patch2:-p1</programlisting>
+
+ <para xml:lang="en">This does not conflict with <link linkend="porting-master-sites-n">the master site grouping
+ feature</link>, adding a group also works:</para>
+
+ <programlisting xml:lang="en">PATCHFILES= patch2:-p1:source2</programlisting>
+ </tip>
+
+ <note>
+ <para xml:lang="en">The tarball will have been extracted alongside the
+ regular source by then, so there is no need to explicitly
+ extract it if it is a regular <command>gzip</command>ped or
+ <command>compress</command>ed tarball. Take extra care not
+ to overwrite something that already exists in that
+ directory if extracting it manually. Also, do not forget to
+ add a command to remove the copied patch in the
+ <buildtarget xml:lang="en">pre-clean</buildtarget> target.</para>
+ </note>
+ </sect2>
+
+ <sect2 xml:id="porting-master-sites-n">
+ <title xml:lang="en">Multiple Distribution or Patches Files from Multiple
+ Locations</title>
+
+ <para xml:lang="en">(Consider this to be a somewhat
+ <quote>advanced topic</quote>; those new to this document
+ may wish to skip this section at first).</para>
+
+ <para xml:lang="en">This section has information on the fetching mechanism
+ known as both <literal>MASTER_SITES:n</literal> and
+ <literal>MASTER_SITES_NN</literal>. We will refer to this
+ mechanism as <literal>MASTER_SITES:n</literal>.</para>
+
+ <para xml:lang="en">A little background first. OpenBSD has a neat feature
+ inside <varname>DISTFILES</varname> and
+ <varname>PATCHFILES</varname> which allows files and
+ patches to be postfixed with <literal>:n</literal>
+ identifiers. Here, <literal>n</literal> can be both
+ <literal>[0-9]</literal> and denote a group designation. For
+ example:</para>
+
+ <programlisting xml:lang="en">DISTFILES= alpha:0 beta:1</programlisting>
+
+ <para xml:lang="en">In OpenBSD, distribution file <filename>alpha</filename>
+ will be associated with variable
+ <varname>MASTER_SITES0</varname> instead of our common
+ <varname>MASTER_SITES</varname> and
+ <filename>beta</filename> with
+ <varname>MASTER_SITES1</varname>.</para>
+
+ <para xml:lang="en">This is a very interesting feature which can decrease
+ that endless search for the correct download site.</para>
+
+ <para xml:lang="en">Just picture 2 files in <varname>DISTFILES</varname> and
+ 20 sites in <varname>MASTER_SITES</varname>, the sites slow as
+ hell where <filename>beta</filename> is carried by all sites
+ in <varname>MASTER_SITES</varname>, and
+ <filename>alpha</filename> can only be found in the 20th site.
+ It would be such a waste to check all of them if the
+ maintainer knew this beforehand, would it not? Not a good
+ start for that lovely weekend!</para>
+
+ <para xml:lang="en">Now that you have the idea, just imagine more
+ <varname>DISTFILES</varname> and more
+ <varname>MASTER_SITES</varname>. Surely our
+ <quote>distfiles survey meister</quote> would appreciate the
+ relief to network strain that this would bring.</para>
+
+ <para xml:lang="en">In the next sections, information will follow on the
+ FreeBSD implementation of this idea. We improved a bit on
+ OpenBSD's concept.</para>
+
+ <sect3 xml:id="porting-master-sites-n-simplified">
+ <title xml:lang="en">Simplified Information</title>
+
+ <para xml:lang="en">This section explains how to quickly prepare fine
+ grained fetching of multiple distribution files and patches
+ from different sites and subdirectories. We describe here a
+ case of simplified <literal>MASTER_SITES:n</literal> usage.
+ This will be sufficient for most scenarios. More detailed
+ information are available in <xref linkend="ports-master-sites-n-detailed"/>.</para>
+
+ <para xml:lang="en">Some applications consist of multiple distribution files
+ that must be downloaded from a number of different sites.
+ For example, <application>Ghostscript</application> consists
+ of the core of the program, and then a large number of
+ driver files that are used depending on the user's printer.
+ Some of these driver files are supplied with the core, but
+ many others must be downloaded from a variety of different
+ sites.</para>
+
+ <para xml:lang="en">To support this, each entry in
+ <varname>DISTFILES</varname> may be followed by a colon and
+ a <quote>tag name</quote>. Each site listed in
+ <varname>MASTER_SITES</varname> is then followed by a colon,
+ and the tag that indicates which distribution files are
+ downloaded from this site.</para>
+
+ <para xml:lang="en">For example, consider an application with the source
+ split in two parts, <filename>source1.tar.gz</filename> and
+ <filename>source2.tar.gz</filename>, which must be
+ downloaded from two different sites. The port's
+ <filename>Makefile</filename> would include lines like <xref linkend="ports-master-sites-n-example-simple-use-one-file-per-site"/>.</para>
+
+ <example xml:id="ports-master-sites-n-example-simple-use-one-file-per-site">
+
+ <title xml:lang="en">Simplified Use of <literal>MASTER_SITES:n</literal>
+ with One File Per Site</title>
+
+ <programlisting>MASTER_SITES= ftp://ftp1.example.com/:source1 \
+ http://www.example.com/:source2
+DISTFILES= source1.tar.gz:source1 \
+ source2.tar.gz:source2</programlisting>
+ </example>
+
+ <para xml:lang="en">Multiple distribution files can have the same tag.
+ Continuing the previous example, suppose that there was a
+ third distfile, <filename>source3.tar.gz</filename>, that
+ is downloaded from
+ <systemitem>ftp.example2.com</systemitem>. The
+ <filename>Makefile</filename> would then be written like
+ <xref linkend="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"/>.</para>
+
+ <example xml:id="ports-master-sites-n-example-simple-use-more-than-one-file-per-site">
+
+ <title xml:lang="en">Simplified Use of <literal>MASTER_SITES:n</literal>
+ with More Than One File Per Site</title>
+
+ <programlisting>MASTER_SITES= ftp://ftp.example.com/:source1 \
+ http://www.example.com/:source2
+DISTFILES= source1.tar.gz:source1 \
+ source2.tar.gz:source2 \
+ source3.tar.gz:source2</programlisting>
+ </example>
+ </sect3>
+
+ <sect3 xml:id="ports-master-sites-n-detailed">
+ <title xml:lang="en">Detailed Information</title>
+
+ <para xml:lang="en">Okay, so the previous example did not reflect the new
+ port's needs? In this section we will explain in detail how
+ the fine grained fetching mechanism
+ <literal>MASTER_SITES:n</literal> works and how it can
+ be used.</para>
+
+ <orderedlist>
<listitem>
- <para>The first category must be a physical category (see
- <link linkend="porting-categories">above</link>). This is
- necessary to make the packaging work. Virtual categories and
- physical categories may be intermixed after that.</para>
+ <para xml:lang="en">Elements can be postfixed with
+ <literal>:<replaceable>n</replaceable></literal> where
+ <replaceable>n</replaceable> is
+ <literal>[^:,]+</literal>, that is,
+ <replaceable>n</replaceable> could conceptually be any
+ alphanumeric string but we will limit it to
+ <literal>[a-zA-Z_][0-9a-zA-Z_]+</literal> for
+ now.</para>
+
+ <para xml:lang="en">Moreover, string matching is case sensitive; that
+ is, <literal>n</literal> is different from
+ <literal>N</literal>.</para>
+
+ <para xml:lang="en">However, these words cannot be used for
+ postfixing purposes since they yield special meaning:
+ <literal>default</literal>, <literal>all</literal> and
+ <literal>ALL</literal> (they are used internally in
+ item <xref linkend="porting-master-sites-n-what-changes-in-port-targets"/>).
+ Furthermore, <literal>DEFAULT</literal> is a special
+ purpose word (check item <xref linkend="porting-master-sites-n-DEFAULT-group"/>).</para>
</listitem>
<listitem>
- <para>Language specific categories always come first. For
- example, if your port installs Japanese X11 fonts, then your
- <varname>CATEGORIES</varname> line would read <filename>japanese
- x11-fonts</filename>.</para>
+ <para xml:lang="en">Elements postfixed with <literal>:n</literal>
+ belong to the group <literal>n</literal>,
+ <literal>:m</literal> belong to group
+ <literal>m</literal> and so forth.</para>
</listitem>
- <listitem>
- <para>Specific categories are listed before less-specific ones. For
- instance, an HTML editor should be listed as <filename>www
- editors</filename>, not the other way around. Also, you should not
- list <filename>net</filename> when the port belongs to
- any of <filename>irc</filename>, <filename>mail</filename>,
- <filename>mbone</filename>, <filename>news</filename>,
- <filename>security</filename>, or <filename>www</filename>, as
- <filename>net</filename> is included implicitly.</para>
+ <listitem xml:id="porting-master-sites-n-DEFAULT-group">
+ <para xml:lang="en">Elements without a postfix are groupless, they
+ all belong to the special group
+ <literal>DEFAULT</literal>. Any elements postfixed
+ with <literal>DEFAULT</literal>, is just being
+ redundant unless an element belongs
+ to both <literal>DEFAULT</literal> and other groups at
+ the same time (check item <xref linkend="porting-master-sites-n-comma-operator"/>).</para>
+
+ <para xml:lang="en">These examples are equivalent but the first
+ one is preferred:</para>
+
+ <programlisting>MASTER_SITES= alpha</programlisting>
+
+ <programlisting>MASTER_SITES= alpha:DEFAULT</programlisting>
</listitem>
<listitem>
- <para><filename>x11</filename> is used as a secondary category only
- when the primary category is a natural language. In particular,
- you should not put <filename>x11</filename> in the category line
- for X applications.</para>
+ <para xml:lang="en">Groups are not exclusive, an element may belong to
+ several different groups at the same time and a group
+ can either have either several different elements or
+ none at all.</para>
+ </listitem>
+
+ <listitem xml:id="porting-master-sites-n-comma-operator">
+ <para xml:lang="en">When an element belongs to several groups
+ at the same time, use the comma operator
+ (<literal>,</literal>).</para>
+
+ <para xml:lang="en">Instead of repeating it several times, each time
+ with a different postfix, we can list several groups at
+ once in a single postfix. For instance,
+ <literal>:m,n,o</literal> marks an element that belongs
+ to group <literal>m</literal>, <literal>n</literal> and
+ <literal>o</literal>.</para>
+
+ <para xml:lang="en">All these examples are equivalent but the
+ last one is preferred:</para>
+
+ <programlisting>MASTER_SITES= alpha alpha:SOME_SITE</programlisting>
+
+ <programlisting>MASTER_SITES= alpha:DEFAULT alpha:SOME_SITE</programlisting>
+
+ <programlisting>MASTER_SITES= alpha:SOME_SITE,DEFAULT</programlisting>
+
+ <programlisting>MASTER_SITES= alpha:DEFAULT,SOME_SITE</programlisting>
</listitem>
<listitem>
- <para><application>Emacs</application> modes should be
- placed in the same ports category as the application
- supported by the mode, not in
- <filename>editors</filename>. For example, an
- <application>Emacs</application> mode to edit source
- files of some programming language should go into
- <filename>lang</filename>.
- </para>
+ <para xml:lang="en">All sites within a given group are sorted according
+ to <varname>MASTER_SORT_AWK</varname>. All groups
+ within <varname>MASTER_SITES</varname> and
+ <varname>PATCH_SITES</varname> are sorted as
+ well.</para>
+ </listitem>
+
+ <listitem xml:id="porting-master-sites-n-group-semantics">
+ <para xml:lang="en">Group semantics can be used in any of the
+ variables <varname>MASTER_SITES</varname>,
+ <varname>PATCH_SITES</varname>,
+ <varname>MASTER_SITE_SUBDIR</varname>,
+ <varname>PATCH_SITE_SUBDIR</varname>,
+ <varname>DISTFILES</varname>, and
+ <varname>PATCHFILES</varname> according to this
+ syntax:</para>
+
+ <orderedlist>
+ <listitem>
+ <para xml:lang="en">All <varname>MASTER_SITES</varname>,
+ <varname>PATCH_SITES</varname>,
+ <varname>MASTER_SITE_SUBDIR</varname> and
+ <varname>PATCH_SITE_SUBDIR</varname> elements must
+ be terminated with the forward slash
+ <literal>/</literal> character. If any elements
+ belong to any groups, the group postfix
+ <literal>:<replaceable>n</replaceable></literal>
+ must come right after the terminator
+ <literal>/</literal>. The
+ <literal>MASTER_SITES:n</literal> mechanism relies
+ on the existence of the terminator
+ <literal>/</literal> to avoid confusing elements
+ where a <literal>:n</literal> is a valid part of the
+ element with occurrences where <literal>:n</literal>
+ denotes group <literal>n</literal>. For
+ compatibility purposes, since the
+ <literal>/</literal> terminator was not required
+ before in both <varname>MASTER_SITE_SUBDIR</varname>
+ and <varname>PATCH_SITE_SUBDIR</varname> elements,
+ if the postfix immediate preceding character is not
+ a <literal>/</literal> then <literal>:n</literal>
+ will be considered a valid part of the element
+ instead of a group postfix even if an element is
+ postfixed with <literal>:n</literal>. See both
+ <xref linkend="ports-master-sites-n-example-detailed-use-master-site-subdir"/>
+ and <xref linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para>
+
+ <example xml:id="ports-master-sites-n-example-detailed-use-master-site-subdir">
+
+ <title xml:lang="en">Detailed Use of
+ <literal>MASTER_SITES:n</literal> in
+ <varname>MASTER_SITE_SUBDIR</varname></title>
+
+ <programlisting>MASTER_SITE_SUBDIR= old:n new/:NEW</programlisting>
+
+ <itemizedlist>
+ <listitem>
+ <para xml:lang="en">Directories within group
+ <literal>DEFAULT</literal> -&gt;
+ old:n</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">Directories within group
+ <literal>NEW</literal> -&gt; new</para>
+ </listitem>
+ </itemizedlist>
+ </example>
+
+ <example xml:id="ports-master-sites-n-example-detailed-use-complete-example-master-sites">
+
+ <title xml:lang="en">Detailed Use of
+ <literal>MASTER_SITES:n</literal> with Comma
+ Operator, Multiple Files, Multiple Sites and
+ Multiple Subdirectories</title>
+
+ <programlisting>MASTER_SITES= http://site1/%SUBDIR%/ http://site2/:DEFAULT \
+ http://site3/:group3 http://site4/:group4 \
+ http://site5/:group5 http://site6/:group6 \
+ http://site7/:DEFAULT,group6 \
+ http://site8/%SUBDIR%/:group6,group7 \
+ http://site9/:group8
+DISTFILES= file1 file2:DEFAULT file3:group3 \
+ file4:group4,group5,group6 file5:grouping \
+ file6:group7
+MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \
+ directory-one/:group6,DEFAULT \
+ directory</programlisting>
+
+ <para xml:lang="en">The previous example results in this
+ fine grained fetching. Sites are listed in the
+ exact order they will be used.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para xml:lang="en"><filename>file1</filename> will be
+ fetched from</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><varname>MASTER_SITE_OVERRIDE</varname></para>
+ </listitem>
+
+ <listitem>
+ <para>http://site1/directory-trial:1/</para>
+ </listitem>
+
+ <listitem>
+ <para>http://site1/directory-one/</para>
+ </listitem>
+
+ <listitem>
+ <para>http://site1/directory/</para>
+ </listitem>
+
+ <listitem>
+ <para>http://site2/</para>
+ </listitem>
+
+ <listitem>
+ <para>http://site7/</para>
+ </listitem>
+
+ <listitem>
+ <para><varname>MASTER_SITE_BACKUP</varname></para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><filename>file2</filename> will be fetched
+ exactly as <filename>file1</filename> since
+ they both belong to the same group</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><varname>MASTER_SITE_OVERRIDE</varname></para>
+ </listitem>
+
+ <listitem>
+ <para>http://site1/directory-trial:1/</para>
+ </listitem>
+
+ <listitem>
+ <para>http://site1/directory-one/</para>
+ </listitem>
+
+ <listitem>
+ <para>http://site1/directory/</para>
+ </listitem>
+
+ <listitem>
+ <para>http://site2/</para>
+ </listitem>
+
+ <listitem>
+ <para>http://site7/</para>
+ </listitem>
+
+ <listitem>
+ <para><varname>MASTER_SITE_BACKUP</varname></para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><filename>file3</filename> will be fetched
+ from</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><varname>MASTER_SITE_OVERRIDE</varname></para>
+ </listitem>
+
+ <listitem>
+ <para>http://site3/</para>
+ </listitem>
+
+ <listitem>
+ <para><varname>MASTER_SITE_BACKUP</varname></para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><filename>file4</filename> will be
+ fetched from</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><varname>MASTER_SITE_OVERRIDE</varname></para>
+ </listitem>
+
+ <listitem>
+ <para>http://site4/</para>
+ </listitem>
+
+ <listitem>
+ <para>http://site5/</para>
+ </listitem>
+
+ <listitem>
+ <para>http://site6/</para>
+ </listitem>
+
+ <listitem>
+ <para>http://site7/</para>
+ </listitem>
+
+ <listitem>
+ <para>http://site8/directory-one/</para>
+ </listitem>
+
+ <listitem>
+ <para><varname>MASTER_SITE_BACKUP</varname></para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><filename>file5</filename> will be fetched
+ from</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><varname>MASTER_SITE_OVERRIDE</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>MASTER_SITE_BACKUP</varname></para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><filename>file6</filename> will be fetched
+ from</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><varname>MASTER_SITE_OVERRIDE</varname></para>
+ </listitem>
+
+ <listitem>
+ <para>http://site8/</para>
+ </listitem>
+
+ <listitem>
+ <para><varname>MASTER_SITE_BACKUP</varname></para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </example>
+ </listitem>
+ </orderedlist>
</listitem>
<listitem>
- <para>會安裝 kernel loadable modules 的 port 請在
- <varname>CATEGORIES</varname> 內加上 <filename>kld</filename>
- 這個虛擬目錄。</para>
+ <para xml:lang="en">How do I group one of the special macros from
+ <filename>bsd.sites.mk</filename>, for example,
+ SourceForge (<literal>SF</literal>)?</para>
+
+ <para xml:lang="en">This has been simplified as much as possible. See
+ <xref linkend="ports-master-sites-n-example-detailed-use-master-site-sourceforge"/>.</para>
+
+ <example xml:id="ports-master-sites-n-example-detailed-use-master-site-sourceforge">
+
+ <title xml:lang="en">Detailed Use of <literal>MASTER_SITES:n</literal>
+ with SourceForge (<literal>SF</literal>)</title>
+
+ <programlisting>MASTER_SITES= http://site1/ SF/something/1.0:sourceforge,TEST
+DISTFILES= something.tar.gz:sourceforge</programlisting>
+
+ <para xml:lang="en"><filename>something.tar.gz</filename> will be
+ fetched from all sites within SourceForge.</para>
+ </example>
</listitem>
<listitem>
- <para><filename>misc</filename>
- should not appear with any other non-virtual category.
- If you have <literal>misc</literal> with something else in
- your <varname>CATEGORIES</varname> line, that means you can
- safely delete <literal>misc</literal> and just put the port
- in that other subdirectory!</para>
+ <para xml:lang="en">How do I use this with
+ <varname>PATCH<replaceable>*</replaceable></varname>?</para>
+
+ <para xml:lang="en">All examples were done with
+ <varname>MASTER<replaceable>*</replaceable></varname>
+ but they work exactly the same for
+ <varname>PATCH<replaceable>*</replaceable></varname>
+ ones as can be seen in <xref linkend="ports-master-sites-n-example-detailed-use-patch-sites"/>.</para>
+
+ <example xml:id="ports-master-sites-n-example-detailed-use-patch-sites">
+
+ <title xml:lang="en">Simplified Use of
+ <literal>MASTER_SITES:n</literal> with
+ <varname>PATCH_SITES</varname></title>
+
+ <programlisting>PATCH_SITES= http://site1/ http://site2/:test
+PATCHFILES= patch1:test</programlisting>
+ </example>
</listitem>
+ </orderedlist>
+ </sect3>
+
+ <sect3 xml:id="port-master-sites-n-what-changed">
+ <title xml:lang="en">What Does Change for Ports? What Does Not?</title>
+ <orderedlist numeration="lowerroman">
<listitem>
- <para>If your port truly does not belong anywhere else, put it in
- <filename>misc</filename>.</para>
+ <para xml:lang="en">All current ports remain the same. The
+ <literal>MASTER_SITES:n</literal> feature code is only
+ activated if there are elements postfixed with
+ <literal>:<replaceable>n</replaceable></literal> like
+ elements according to the aforementioned syntax rules,
+ especially as shown in item <xref linkend="porting-master-sites-n-group-semantics"/>.</para>
</listitem>
- </itemizedlist>
- <para>If you are not sure about the category, please put a comment to
- that effect in your &man.send-pr.1; submission so we can
- discuss it before we import it. If you are a committer, send a note
- to the &a.ports; so we can discuss it first. Too often, new ports are
- imported to the wrong category only to be moved right away.
- This causes unnecessary and undesirable bloat in the master
- source repository.</para>
- </sect2>
-
- <sect2 xml:id="proposing-categories">
- <title>Proposing a new category</title>
-
- <para>As the Ports Collection has grown over time, various new
- categories have been introduced. New categories can either
- be <emphasis>virtual</emphasis> categories&mdash;those that do
- not have a corresponding subdirectory in the ports tree&mdash;
- or <emphasis>physical</emphasis> categories&mdash;those that
- do. The following text discusses the issues involved in creating
- a new physical category so that you can understand them before
- you propose one.</para>
-
- <para>Our existing practice has been to avoid creating a new
- physical category unless either a large number of ports would
- logically belong to it, or the ports that would belong to it
- are a logically distinct group that is of limited general
- interest (for instance, categories related to spoken human
- languages), or preferably both.</para>
-
- <para>The rationale for this is that such a change creates a
- <link xlink:href="&url.articles.committers-guide;/#ports">
- fair amount of work</link> for both the committers and also
- for all users who track changes to the Ports Collection. In
- addition, proposed category changes just naturally seem to
- attract controversy. (Perhaps this is because there is no
- clear consensus on when a category is <quote>too big</quote>,
- nor whether categories should lend themselves to browsing (and
- thus what number of categories would be an ideal number), and
- so forth.)</para>
-
- <para>Here is the procedure:</para>
-
- <procedure>
- <step>
- <para>Propose the new category on &a.ports;. You should
- include a detailed rationale for the new category,
- including why you feel the existing categories are not
- sufficient, and the list of existing ports proposed to move.
- (If there are new ports pending in
- <application>GNATS</application> that would fit this
- category, list them too.) If you are the maintainer and/or
- submitter, respectively, mention that as it may help you
- to make your case.</para>
- </step>
-
- <step>
- <para>Participate in the discussion.</para>
- </step>
-
- <step>
- <para>If it seems that there is support for your idea,
- file a PR which includes both the rationale and the list
- of existing ports that need to be moved. Ideally, this
- PR should also include patches for the following:</para>
+ <listitem xml:id="porting-master-sites-n-what-changes-in-port-targets">
+ <para xml:lang="en">The port targets remain the same:
+ <buildtarget xml:lang="en">checksum</buildtarget>,
+ <buildtarget xml:lang="en">makesum</buildtarget>,
+ <buildtarget xml:lang="en">patch</buildtarget>,
+ <buildtarget xml:lang="en">configure</buildtarget>,
+ <buildtarget xml:lang="en">build</buildtarget>, etc. With the obvious
+ exceptions of <buildtarget xml:lang="en">do-fetch</buildtarget>,
+ <buildtarget xml:lang="en">fetch-list</buildtarget>,
+ <buildtarget xml:lang="en">master-sites</buildtarget> and
+ <buildtarget xml:lang="en">patch-sites</buildtarget>.</para>
<itemizedlist>
<listitem>
- <para><filename>Makefile</filename>s for the
- new ports once they are repocopied</para>
+ <para xml:lang="en"><buildtarget xml:lang="en">do-fetch</buildtarget>: deploys
+ the new grouping postfixed
+ <varname>DISTFILES</varname> and
+ <varname>PATCHFILES</varname> with their matching
+ group elements within both
+ <varname>MASTER_SITES</varname> and
+ <varname>PATCH_SITES</varname> which use matching
+ group elements within both
+ <varname>MASTER_SITE_SUBDIR</varname> and
+ <varname>PATCH_SITE_SUBDIR</varname>. Check <xref linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para>
</listitem>
<listitem>
- <para><filename>Makefile</filename> for the
- new category</para>
+ <para xml:lang="en"><buildtarget xml:lang="en">fetch-list</buildtarget>: works
+ like old <buildtarget xml:lang="en">fetch-list</buildtarget> with
+ the exception that it groups just like
+ <buildtarget xml:lang="en">do-fetch</buildtarget>.</para>
</listitem>
<listitem>
- <para><filename>Makefile</filename> for the
- old ports' categories</para>
+ <para xml:lang="en"><buildtarget xml:lang="en">master-sites</buildtarget> and
+ <buildtarget xml:lang="en">patch-sites</buildtarget>:
+ (incompatible with older versions) only return the
+ elements of group <literal>DEFAULT</literal>; in
+ fact, they execute targets
+ <buildtarget xml:lang="en">master-sites-default</buildtarget> and
+ <buildtarget xml:lang="en">patch-sites-default</buildtarget>
+ respectively.</para>
+
+ <para xml:lang="en">Furthermore, using target either
+ <buildtarget xml:lang="en">master-sites-all</buildtarget> or
+ <buildtarget xml:lang="en">patch-sites-all</buildtarget> is
+ preferred to directly checking either
+ <buildtarget xml:lang="en">MASTER_SITES</buildtarget> or
+ <buildtarget xml:lang="en">PATCH_SITES</buildtarget>. Also,
+ directly checking is not guaranteed to work in any
+ future versions. Check item <xref linkend="porting-master-sites-n-new-port-targets-master-sites-all"/>
+ for more information on these new port
+ targets.</para>
</listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para xml:lang="en">New port targets</para>
+
+ <orderedlist>
<listitem>
- <para><filename>Makefile</filename>s for ports
- that depend on the old ports</para>
+ <para xml:lang="en">There are
+ <buildtarget xml:lang="en">master-sites-<replaceable>n</replaceable></buildtarget>
+ and
+ <buildtarget xml:lang="en">patch-sites-<replaceable>n</replaceable></buildtarget>
+ targets which will list the elements of the
+ respective group <replaceable>n</replaceable>
+ within <varname>MASTER_SITES</varname> and
+ <varname>PATCH_SITES</varname> respectively. For
+ instance, both
+ <buildtarget xml:lang="en">master-sites-DEFAULT</buildtarget>
+ and <buildtarget xml:lang="en">patch-sites-DEFAULT</buildtarget>
+ will return the elements of group
+ <literal>DEFAULT</literal>,
+ <buildtarget xml:lang="en">master-sites-test</buildtarget> and
+ <buildtarget xml:lang="en">patch-sites-test</buildtarget> of
+ group <literal>test</literal>, and thereon.</para>
</listitem>
- <listitem>
- <para>(for extra credit, you can include the other
- files that have to change, as per the procedure
- in the Committer's Guide.)</para>
+ <listitem xml:id="porting-master-sites-n-new-port-targets-master-sites-all">
+ <para xml:lang="en">There are new targets
+ <buildtarget xml:lang="en">master-sites-all</buildtarget> and
+ <buildtarget xml:lang="en">patch-sites-all</buildtarget> which do
+ the work of the old
+ <buildtarget xml:lang="en">master-sites</buildtarget> and
+ <buildtarget xml:lang="en">patch-sites</buildtarget> ones. They
+ return the elements of all groups as if they all
+ belonged to the same group with the caveat that it
+ lists as many <varname>MASTER_SITE_BACKUP</varname>
+ and <varname>MASTER_SITE_OVERRIDE</varname> as there
+ are groups defined within either
+ <varname>DISTFILES</varname> or
+ <varname>PATCHFILES</varname>; respectively for
+ <buildtarget xml:lang="en">master-sites-all</buildtarget> and
+ <buildtarget xml:lang="en">patch-sites-all</buildtarget>.</para>
</listitem>
- </itemizedlist>
- </step>
-
- <step>
- <para>Since it affects the ports infrastructure and involves
- not only performing repo-copies but also possibly running
- regression tests on the build cluster, the PR should be
- assigned to the &a.portmgr;.</para>
- </step>
-
- <step>
- <para>If that PR is approved, a committer will need to follow
- the rest of the procedure that is
- <link xlink:href="&url.articles.committers-guide;/#ports">
- outlined in the Committer's Guide</link>.</para>
- </step>
- </procedure>
-
- <para>Proposing a new virtual category should be similar to
- the above but much less involved, since no ports will
- actually have to move. In this case, the only patches to
- include in the PR would be those to add the new category to the
- <varname>CATEGORIES</varname> of the affected ports.</para>
- </sect2>
-
- <sect2 xml:id="proposing-reorg">
- <title>Proposing reorganizing all the categories</title>
-
- <para>Occasionally someone proposes reorganizing the categories
- with either a 2-level structure, or some other kind of keyword
- structure. To date, nothing has come of any of these proposals
- because, while they are very easy to make, the effort involved to
- retrofit the entire existing ports collection with any kind of
- reorganization is daunting to say the very least. Please read
- the history of these proposals in the mailing list archives before
- you post this idea; furthermore, you should be prepared to be
- challenged to offer a working prototype.</para>
- </sect2>
- </sect1>
-
- <sect1 xml:id="makefile-distfiles">
- <title>The distribution files</title>
-
- <para>The second part of the <filename>Makefile</filename> describes the
- files that must be downloaded in order to build the port, and where
- they can be downloaded from.</para>
-
- <sect2>
- <title><varname>DISTVERSION/DISTNAME</varname></title>
-
- <para><varname>DISTNAME</varname> is the name of the port as
- called by the authors of the software.
- <varname>DISTNAME</varname> defaults to
- <literal>${PORTNAME}-${PORTVERSION}</literal>, so override it only if necessary.
- <varname>DISTNAME</varname> is only used in two places.
- First, the distribution file list
- (<varname>DISTFILES</varname>) defaults to
- <varname>${DISTNAME}</varname><varname>${EXTRACT_SUFX}</varname>.
- Second, the distribution file is expected to extract into a
- subdirectory named <varname>WRKSRC</varname>, which defaults
- to <filename>work/${DISTNAME}</filename>.</para>
-
- <para>Some vendor's distribution names which do not fit into the
- <literal>${PORTNAME}-${PORTVERSION}</literal>-scheme can be handled
- automatically by setting <varname>DISTVERSION</varname>.
- <varname>PORTVERSION</varname> and <varname>DISTNAME</varname> will be
- derived automatically, but can of course be overridden. The following
- table lists some examples:</para>
-
- <informaltable frame="none" pgwide="1">
- <tgroup cols="2">
- <thead>
- <row>
- <entry><varname>DISTVERSION</varname></entry>
- <entry><varname>PORTVERSION</varname></entry>
- </row>
- </thead>
+ </orderedlist>
+ </listitem>
+ </orderedlist>
+ </sect3>
+ </sect2>
- <tbody>
- <row>
- <entry>0.7.1d</entry>
- <entry>0.7.1.d</entry>
- </row>
+ <sect2 xml:id="makefile-dist_subdir">
+ <title><varname>DIST_SUBDIR</varname></title>
+
+ <para xml:lang="en">Do not let the port clutter
+ <filename>/usr/ports/distfiles</filename>. If the port
+ requires a lot of files to be fetched, or contains a file that
+ has a name that might conflict with other ports (for example,
+ <filename>Makefile</filename>), set
+ <varname>DIST_SUBDIR</varname> to the name of the port
+ (<literal>${PORTNAME}</literal> or
+ <literal>${PKGNAMEPREFIX}${PORTNAME}</literal> are
+ fine). This will change <varname>DISTDIR</varname> from the
+ default <filename>/usr/ports/distfiles</filename> to
+ <filename>/usr/ports/distfiles/${DIST_SUBDIR}</filename>, and
+ in effect puts everything that is required for the port into
+ that subdirectory.</para>
+
+ <para xml:lang="en">It will also look at the subdirectory with the same name
+ on the backup master site at
+ <filename>ftp.FreeBSD.org</filename>. (Setting
+ <varname>DISTDIR</varname> explicitly in
+ <filename>Makefile</filename> will not accomplish this, so
+ please use <varname>DIST_SUBDIR</varname>.)</para>
- <row>
- <entry>10Alpha3</entry>
- <entry>10.a3</entry>
- </row>
+ <note>
+ <para xml:lang="en">This does not affect
+ <varname>MASTER_SITES</varname> defined in the
+ <filename>Makefile</filename>.</para>
+ </note>
+ </sect2>
- <row>
- <entry>3Beta7-pre2</entry>
- <entry>3.b7.p2</entry>
- </row>
+ <sect2 xml:id="makefile-always_keep_distfiles">
+ <title><varname>ALWAYS_KEEP_DISTFILES</varname></title>
- <row>
- <entry>8:f_17</entry>
- <entry>8f.17</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
+ <para xml:lang="en">If the port uses binary distfiles and has a license that
+ requires that the source code is provided with packages
+ distributed in binary form, like <acronym>GPL</acronym>,
+ <varname>ALWAYS_KEEP_DISTFILES</varname> will instruct the
+ FreeBSD build cluster to keep a copy of the files specified in
+ <varname>DISTFILES</varname>. Users of these ports will
+ generally not need these files, so it is a good idea to only
+ add the source distfiles to <varname>DISTFILES</varname> when
+ <varname>PACKAGE_BUILDING</varname> is defined.</para>
- <note>
- <para><varname>PKGNAMEPREFIX</varname> and
- <varname>PKGNAMESUFFIX</varname> do not affect
- <varname>DISTNAME</varname>. Also note that if
- <varname>WRKSRC</varname> is equal to
- <filename>work/${PORTNAME}-${PORTVERSION}</filename>
- while the original source archive is named something other than
- <varname>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</varname>,
- you should probably leave <varname>DISTNAME</varname>
- alone&mdash; you are better off defining
- <varname>DISTFILES</varname> than having to set both
- <varname>DISTNAME</varname> and <varname>WRKSRC</varname>
- (and possibly <varname>EXTRACT_SUFX</varname>).</para>
- </note>
- </sect2>
+ <example xml:id="ports-master-sites-n-example-always-keep-distfiles">
- <sect2>
- <title><varname>MASTER_SITES</varname></title>
+ <title xml:lang="en">Use of
+ <varname>ALWAYS_KEEP_DISTFILES</varname></title>
- <para>Record the directory part of the FTP/HTTP-URL pointing at the
- original tarball in <varname>MASTER_SITES</varname>. Do not forget
- the trailing slash (<filename>/</filename>)!</para>
+ <programlisting xml:lang="en">.if defined(PACKAGE_BUILDING)
+DISTFILES+= <replaceable>foo.tar.gz</replaceable>
+ALWAYS_KEEP_DISTFILES= yes
+.endif</programlisting>
+ </example>
- <para>The <command>make</command> macros will try to use this
- specification for grabbing the distribution file with
- <varname>FETCH</varname> if they cannot find it already on the
- system.</para>
+ <para xml:lang="en">When adding extra files to <varname>DISTFILES</varname>,
+ make sure to also add them to <filename>distinfo</filename>.
+ Also, the additional files will normally be extracted into
+ <varname>WRKDIR</varname> as well, which for some ports may
+ lead to undesirable side effects and require special
+ handling.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="makefile-maintainer">
+ <title><varname>MAINTAINER</varname></title>
+
+ <para> 請在這裡設定你的 email 地址<emphasis>:-)</emphasis></para>
+
+ <para xml:lang="en">Only a single address without the comment part is
+ allowed as a <varname>MAINTAINER</varname> value. The format
+ used is <literal>user@hostname.domain</literal>. Please
+ do not include any descriptive text such as a real name in
+ this entry. That merely confuses the Ports infrastructure
+ and most tools using it.</para>
+
+ <para xml:lang="en">The maintainer is responsible for keeping the port up to
+ date and making sure that it works correctly. For a detailed
+ description of the responsibilities of a port maintainer, refer
+ to <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/contributing/ports-contributing.html#maintain-port">The
+ challenge for port maintainers</link>.</para>
+
+ <note>
+ <para xml:lang="en">A maintainer volunteers to keep a port in good working
+ order. Maintainers have the primary responsibility for their
+ ports, but not exclusive ownership. Ports exist for the
+ benefit of the community and, in reality, belong to the
+ community. What this means is that people other than the
+ maintainer can make changes to a port. Large changes to the
+ Ports Collection might require changes to many ports. The
+ FreeBSD Ports Management Team or members of other teams might
+ modify ports to fix dependency issues or other problems, like
+ a version bump for a shared library update.</para>
+
+ <para xml:lang="en">Some types of fixes have <quote>blanket approval</quote>
+ from the Ports Management Team <email>portmgr@FreeBSD.org</email>, allowing any committer to fix those
+ categories of problems on any port. These fixes do not need
+ approval from the maintainer. Blanket approval does not apply
+ to ports that are maintained by teams like <email role="nolink">autotools@FreeBSD.org</email>, <email role="nolink">x11@FreeBSD.org</email>, <email role="nolink">gnome@FreeBSD.org</email>, or <email role="nolink">kde@FreeBSD.org</email>. These teams use
+ external repositories and can have work that would conflict
+ with changes that would normally fall under blanket
+ approval.</para>
+
+ <para xml:lang="en">Blanket approval for most ports applies to these types of
+ fixes:</para>
- <para>It is recommended that you put multiple sites on this list,
- preferably from different continents. This will safeguard against
- wide-area network problems. We are even planning to add support
- for automatically determining the closest master site and fetching
- from there; having multiple sites will go a long way towards
- helping this effort.</para>
-
- <para>If the original tarball is part of one of the popular
- archives such as X-contrib, GNU, or Perl CPAN, you may be able
- refer to those sites in an easy compact form using
- <varname>MASTER_SITE_<replaceable>*</replaceable></varname>
- (比如:<varname>MASTER_SITE_XCONTRIB</varname>、
- <varname>MASTER_SITE_GNU</varname>、
- <varname>MASTER_SITE_PERL_CPAN</varname>)。 Simply set
- <varname>MASTER_SITES</varname> to one of these variables and
- <varname>MASTER_SITE_SUBDIR</varname> to the path within the
- archive. Here is an example:</para>
-
- <programlisting>MASTER_SITES= ${MASTER_SITE_XCONTRIB}
-MASTER_SITE_SUBDIR= applications</programlisting>
-
- <para>These variables are defined in
- <filename>/usr/ports/Mk/bsd.sites.mk</filename>. There are
- new entries added all the time, so make sure to check the
- latest version of this file before submitting a port.</para>
+ <itemizedlist>
+ <listitem>
+ <para xml:lang="en">Most infrastructure changes to a port (that is,
+ modernizing, but not changing the functionality). For
+ example, converting to staging,
+ <varname>USE_GMAKE</varname> to
+ <literal>USES=gmake</literal>, the new
+ <varname>LIB_DEPENDS</varname> format...</para>
+ </listitem>
- <para>The user can also set the <varname>MASTER_SITE_*</varname>
- variables in <filename>/etc/make.conf</filename> to override our
- choices, and use their favorite mirrors of these popular archives
- instead.</para>
- </sect2>
+ <listitem>
+ <para xml:lang="en">Trivial and <emphasis>tested</emphasis> build and
+ runtime fixes.</para>
+ </listitem>
+ </itemizedlist>
+ </note>
+
+ <para xml:lang="en">Other changes to the port will be sent to the maintainer
+ for review and approval before being committed. If the
+ maintainer does not respond to an update request after two weeks
+ (excluding major public holidays), then that is considered a
+ maintainer timeout, and the update may be made without explicit
+ maintainer approval. If the maintainer does not respond within
+ three months, or if there have been three consecutive timeouts,
+ then that maintainer is considered absent without
+ leave, and can be replaced as the maintainer of the particular
+ port in question. Exceptions to this are anything maintained by
+ the Ports Management Team <email>portmgr@FreeBSD.org</email>, or the Security Officer Team <email>security-officer@FreeBSD.org</email>. No unauthorized
+ commits may ever be made to ports maintained by those
+ groups.</para>
+
+ <para xml:lang="en">We reserve the right to modify the maintainer's submission
+ to better match existing policies and style of the Ports
+ Collection without explicit blessing from the submitter or the
+ maintainer. Also,
+ large infrastructural changes can result in a port being
+ modified without the maintainer's consent. These kinds of
+ changes will never affect the port's functionality.</para>
+
+ <para xml:lang="en">The Ports Management Team <email>portmgr@FreeBSD.org</email> reserves the right to revoke or override
+ anyone's maintainership for any reason, and the
+ Security Officer Team <email>security-officer@FreeBSD.org</email> reserves the right to revoke or override
+ maintainership for security reasons.</para>
+ </sect1>
+
+ <sect1 xml:id="makefile-comment">
+ <title><varname>COMMENT</varname></title>
+
+ <para>這是關於這個 port的一行描述。請遵守這些原則:</para>
+
+ <orderedlist>
+ <listitem>
+ <para xml:lang="en">Try to keep the COMMENT value at no longer than 70
+ characters, as this line will be used by
+ <command>pkg info</command> (see <citerefentry><refentrytitle>pkg-info</refentrytitle><manvolnum>8</manvolnum></citerefentry>) to
+ display a one-line summary of the port;</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">Do <emphasis>not</emphasis> include the package name (or
+ version number of the software);</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">The comment must begin with a capital and end without
+ a period;</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">Do not start with an indefinite article (that is, A or
+ An);</para>
+ </listitem>
+
+ <listitem>
+ <para>名字首字大寫 (例如, Apache, JavaScript, Perl);</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">For lists of words, use the Oxford comma (for example,
+ green, red<emphasis>,</emphasis> and blue);</para>
+ </listitem>
+
+ <listitem>
+ <para>請檢查拼字。</para>
+ </listitem>
+ </orderedlist>
+
+ <para>以下是範例:</para>
+
+ <programlisting xml:lang="en">COMMENT= Cat chasing a mouse all over the screen</programlisting>
+
+ <para xml:lang="en">The COMMENT variable immediately follows the
+ MAINTAINER variable in the <filename>Makefile</filename>.</para>
+ </sect1>
+
+ <sect1 xml:id="makefile-portscout">
+ <title><varname>PORTSCOUT</varname></title>
+
+ <para xml:lang="en"><application>Portscout</application> is an automated
+ distfile check utility for the FreeBSD Ports Collection,
+ described in detail in <xref linkend="distfile-survey"/>.</para>
+
+ <para xml:lang="en"><varname>PORTSCOUT</varname> defines special
+ conditions within which the <application>Portscout</application>
+ distfile scanner is restricted.</para>
+
+ <para xml:lang="en">Situations where <varname>PORTSCOUT</varname>
+ is set include:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para xml:lang="en">When distfiles have to be ignored, whether for specific
+ versions, or specific minor revisions. For example, to
+ exclude version <replaceable>8.2</replaceable> from distfile
+ version checks because it is known to be broken, add:</para>
+
+ <programlisting>PORTSCOUT= ignore:8.2</programlisting>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">When specific versions or specific major and minor
+ revisions of a distfile must be checked. For example, if
+ only version <replaceable>0.6.4</replaceable> must be
+ monitored because newer versions have compatibility issues
+ with FreeBSD, add:</para>
+
+ <programlisting>PORTSCOUT= limit:^0\.6\.4</programlisting>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">When URLs listing the available versions differ from the
+ download URLs. For example, to limit distfile version
+ checks to the download page for the
+ <package role="port">databases/pgtune</package> port,
+ add:</para>
+
+ <programlisting>PORTSCOUT= site:http://pgfoundry.org/frs/?group_id=1000416</programlisting>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 xml:id="makefile-depend">
+ <title>相依性</title>
+
+ <para xml:lang="en">Many ports depend on other ports. This is a very convenient
+ feature of most Unix-like operating systems, including FreeBSD.
+ Multiple ports can share a common dependency, rather than
+ bundling that dependency with every port or package that needs
+ it. There are seven variables that can be used to ensure that
+ all the required bits will be on the user's machine. There are
+ also some pre-supported dependency variables for common cases,
+ plus a few more to control the behavior of dependencies.</para>
+
+ <sect2 xml:id="makefile-lib_depends">
+ <title xml:lang="en"><varname>LIB_DEPENDS</varname></title>
+
+ <para xml:lang="en">This variable specifies the shared libraries this port
+ depends on. It is a list of
+ <replaceable>lib</replaceable>:<replaceable>dir</replaceable>
+ tuples where <replaceable>lib</replaceable> is the name of
+ the shared library, <replaceable>dir</replaceable> is the
+ directory in which to find it in case it is not available.
+ For example,</para>
+
+ <programlisting xml:lang="en">LIB_DEPENDS= libjpeg.so:${PORTSDIR}/graphics/jpeg</programlisting>
+
+ <para xml:lang="en">will check for a shared jpeg library with any version, and
+ descend into the <filename>graphics/jpeg</filename>
+ subdirectory of the ports tree to build and install it if it
+ is not found.</para>
+
+ <para xml:lang="en">The dependency is checked twice, once from within the
+ <buildtarget xml:lang="en">build</buildtarget> target and then from within
+ the <buildtarget xml:lang="en">install</buildtarget> target. Also, the name
+ of the dependency is put into the package so that
+ <command>pkg install</command> (see <citerefentry><refentrytitle>pkg-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>) will
+ automatically install it if it is not on the user's
+ system.</para>
+ </sect2>
- <sect2>
- <title><varname>EXTRACT_SUFX</varname></title>
+ <sect2 xml:id="makefile-run_depends">
+ <title><varname>RUN_DEPENDS</varname></title>
+
+ <para xml:lang="en">This variable specifies executables or files this port
+ depends on during run-time. It is a list of
+ <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional>
+ tuples where <replaceable>path</replaceable> is the name of
+ the executable or file, <replaceable>dir</replaceable> is the
+ directory in which to find it in case it is not available, and
+ <replaceable>target</replaceable> is the target to call in
+ that directory. If <replaceable>path</replaceable> starts
+ with a slash (<literal>/</literal>), it is treated as a file
+ and its existence is tested with <command>test -e</command>;
+ otherwise, it is assumed to be an executable, and
+ <command>which -s</command> is used to determine if the
+ program exists in the search path.</para>
+
+ <para>例如,</para>
+
+ <programlisting>RUN_DEPENDS= ${LOCALBASE}/news/bin/innd:${PORTSDIR}/news/inn \
+ xmlcatmgr:${PORTSDIR}/textproc/xmlcatmgr</programlisting>
+
+ <para xml:lang="en">will check if the file or directory
+ <filename>/usr/local/news/bin/innd</filename> exists, and
+ build and install it from the <filename>news/inn</filename>
+ subdirectory of the ports tree if it is not found. It will
+ also see if an executable called <command>xmlcatmgr</command>
+ is in the search path, and descend into
+ <filename>textproc/xmlcatmgr</filename>
+ to build and install it if it is not found.</para>
- <para>If you have one distribution file, and it uses an odd suffix to
- indicate the compression mechanism, set
- <varname>EXTRACT_SUFX</varname>.</para>
+ <note>
+ <para xml:lang="en">In this case, <command>innd</command> is actually an
+ executable; if an executable is in a place that is not
+ expected to be in the search path, use the full
+ pathname.</para>
+ </note>
- <para>For example, if the distribution file was named
- <filename>foo.tgz</filename> instead of the more normal
- <filename>foo.tar.gz</filename>, you would write:</para>
+ <note>
+ <para xml:lang="en">The official search <envar>PATH</envar> used on the
+ ports build cluster is</para>
- <programlisting>DISTNAME= foo
-EXTRACT_SUFX= .tgz</programlisting>
+ <programlisting>/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin</programlisting>
+ </note>
- <para>The <varname>USE_BZIP2</varname> and <varname>USE_ZIP</varname>
- variables automatically set <varname>EXTRACT_SUFX</varname> to
- <literal>.tar.bz2</literal> or <literal>.zip</literal> as necessary. If
- neither of these are set then <varname>EXTRACT_SUFX</varname>
- defaults to <literal>.tar.gz</literal>.</para>
+ <para xml:lang="en">The dependency is checked from within the
+ <buildtarget xml:lang="en">install</buildtarget> target. Also, the name of
+ the dependency is put into the package so that
+ <command>pkg install</command> (see <citerefentry><refentrytitle>pkg-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>) will
+ automatically install it if it is not on the user's system.
+ The <replaceable>target</replaceable> part can be omitted if
+ it is the same as <varname>DEPENDS_TARGET</varname>.</para>
+
+ <para xml:lang="en">A quite common situation is when
+ <varname>RUN_DEPENDS</varname> is literally the same as
+ <varname>BUILD_DEPENDS</varname>, especially if ported
+ software is written in a scripted language or if it requires
+ the same build and run-time environment. In this case, it is
+ both tempting and intuitive to directly assign one to the
+ other:</para>
+
+ <programlisting>RUN_DEPENDS= ${BUILD_DEPENDS}</programlisting>
+
+ <para xml:lang="en">However, such assignment can pollute run-time
+ dependencies with entries not defined in the port's original
+ <varname>BUILD_DEPENDS</varname>. This happens because of
+ <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s lazy evaluation of variable assignment.
+ Consider a <filename>Makefile</filename> with
+ <varname>USE_<replaceable>*</replaceable></varname>,
+ which are processed by <filename>ports/Mk/bsd.*.mk</filename>
+ to augment initial build dependencies. For example,
+ <literal>USES= gmake</literal> adds
+ <package role="port">devel/gmake</package> to
+ <varname>BUILD_DEPENDS</varname>. To prevent such additional
+ dependencies from polluting <varname>RUN_DEPENDS</varname>,
+ create another variable with the current content of
+ <varname>BUILD_DEPENDS</varname> and assign it to both
+ <varname>BUILD_DEPENDS</varname> and
+ <varname>RUN_DEPENDS</varname>:</para>
+
+ <programlisting>MY_DEPENDS= some:${PORTSDIR}/devel/some \
+ other:${PORTSDIR}/lang/other
+BUILD_DEPENDS= ${MY_DEPENDS}
+RUN_DEPENDS= ${MY_DEPENDS}</programlisting>
- <note>
- <para>You never need to set both <varname>EXTRACT_SUFX</varname> and
- <varname>DISTFILES</varname>.</para>
- </note>
- </sect2>
-
- <sect2>
- <title><varname>DISTFILES</varname></title>
-
- <para>Sometimes the names of the files to be downloaded have no
- resemblance to the name of the port. For example, it might be
- called <filename>source.tar.gz</filename> or similar. In other
- cases the application's source code might be in several different
- archives, all of which must be downloaded.</para>
-
- <para>If this is the case, set <varname>DISTFILES</varname> to be a
- space separated list of all the files that must be
- downloaded.</para>
-
- <programlisting>DISTFILES= source1.tar.gz source2.tar.gz</programlisting>
-
- <para>If not explicitly set, <varname>DISTFILES</varname> defaults to
- <literal>${DISTNAME}${EXTRACT_SUFX}</literal>.</para>
- </sect2>
-
- <sect2>
- <title><varname>EXTRACT_ONLY</varname></title>
-
- <para>If only some of the <varname>DISTFILES</varname> must be
- extracted&mdash;for example, one of them is the source code, while
- another is an uncompressed document&mdash;list the filenames that
- must be extracted in <varname>EXTRACT_ONLY</varname>.</para>
-
- <programlisting>DISTFILES= source.tar.gz manual.html
-EXTRACT_ONLY= source.tar.gz</programlisting>
-
- <para>If <emphasis>none</emphasis> of the <varname>DISTFILES</varname>
- should be uncompressed then set <varname>EXTRACT_ONLY</varname> to
- the empty string.</para>
-
- <programlisting>EXTRACT_ONLY=</programlisting>
- </sect2>
-
- <sect2 xml:id="porting-patchfiles">
- <title><varname>PATCHFILES</varname></title>
-
- <para>If your port requires some additional patches that are available
- by FTP or HTTP, set <varname>PATCHFILES</varname> to the names of
- the files and <varname>PATCH_SITES</varname> to the URL of the
- directory that contains them (the format is the same as
- <varname>MASTER_SITES</varname>).</para>
-
- <para>If the patch is not relative to the top of the source tree
- (i.e., <varname>WRKSRC</varname>) because it contains some extra
- pathnames, set <varname>PATCH_DIST_STRIP</varname> accordingly. For
- instance, if all the pathnames in the patch have an extra
- <literal>foozolix-1.0/</literal> in front of the filenames, then set
- <literal>PATCH_DIST_STRIP=-p1</literal>.</para>
-
- <para>Do not worry if the patches are compressed; they will be
- decompressed automatically if the filenames end with
- <filename>.gz</filename> or <filename>.Z</filename>.</para>
-
- <para>If the patch is distributed with some other files, such as
- documentation, in a gzip'd tarball, you cannot just use
- <varname>PATCHFILES</varname>. If that is the case, add the name
- and the location of the patch tarball to
- <varname>DISTFILES</varname> and <varname>MASTER_SITES</varname>.
- Then, use the <varname>EXTRA_PATCHES</varname> variable to
- point to those files and <filename>bsd.port.mk</filename>
- will automatically apply them for you. In particular, do
- <emphasis>not</emphasis> copy patch files into the
- <varname>PATCHDIR</varname> directory&mdash;that directory may
- not be writable.</para>
+ <important>
+ <para xml:lang="en"><emphasis>Do not</emphasis> use <literal>:=</literal>
+ to assign <varname>BUILD_DEPENDS</varname> to
+ <varname>RUN_DEPENDS</varname> or vice-versa. All
+ variables are expanded immediately, which is exactly the
+ wrong thing to do and almost always a failure.</para>
+ </important>
+ </sect2>
- <note>
- <para>The tarball will have been extracted alongside the
- regular source by then, so there is no need to explicitly extract
- it if it is a regular gzip'd or compress'd tarball. If you do the
- latter, take extra care not to overwrite something that already
- exists in that directory. Also, do not forget to add a command to
- remove the copied patch in the <buildtarget>pre-clean</buildtarget>
- target.</para>
- </note>
- </sect2>
-
- <sect2 xml:id="porting-master-sites-n">
- <title>Multiple distribution files or patches from different
- sites and subdirectories
- (<literal>MASTER_SITES:n</literal>)</title>
-
- <para>(Consider this to be a somewhat <quote>advanced topic</quote>;
- those new to this document may wish to skip this section at first).
- </para>
-
- <para>This section has information on the fetching mechanism
- known as both <literal>MASTER_SITES:n</literal> and
- <literal>MASTER_SITES_NN</literal>. We will refer to this
- mechanism as <literal>MASTER_SITES:n</literal>
- hereon.</para>
-
- <para>A little background first. OpenBSD has a neat feature
- inside both <varname>DISTFILES</varname> and
- <varname>PATCHFILES</varname> variables, both files and
- patches can be postfixed with <literal>:n</literal>
- identifiers where <literal>n</literal> both can be
- <literal>[0-9]</literal> and denote a group designation.
- For example:</para>
-
- <programlisting>DISTFILES= alpha:0 beta:1</programlisting>
-
- <para>In OpenBSD, distribution file <filename>alpha</filename>
- will be associated with variable
- <varname>MASTER_SITES0</varname> instead of our common
- <varname>MASTER_SITES</varname> and
- <filename>beta</filename> with
- <varname>MASTER_SITES1</varname>.</para>
-
- <para>This is a very interesting feature which can decrease
- that endless search for the correct download site.</para>
-
- <para>Just picture 2 files in <varname>DISTFILES</varname> and
- 20 sites in <varname>MASTER_SITES</varname>, the sites slow
- as hell where <filename>beta</filename> is carried by all
- sites in <varname>MASTER_SITES</varname>, and
- <filename>alpha</filename> can only be found in the 20th
- site. It would be such a waste to check all of them if
- maintainer knew this beforehand, would it not? Not a good
- start for that lovely weekend!</para>
-
- <para>Now that you have the idea, just imagine more
- <varname>DISTFILES</varname> and more
- <varname>MASTER_SITES</varname>. Surely our
- <quote>distfiles survey meister</quote> would appreciate the
- relief to network strain that this would bring.</para>
-
- <para>In the next sections, information will follow on the
- FreeBSD implementation of this idea. We improved a bit on
- OpenBSD's concept.</para>
-
- <sect3>
- <title>Simplified information</title>
-
- <para>This section tells you how to quickly prepare fine
- grained fetching of multiple distribution files and
- patches from different sites and subdirectories. We
- describe here a case of simplified
- <literal>MASTER_SITES:n</literal> usage. This will be
- sufficient for most scenarios. However, if you need
- further information, you will have to refer to the next
- section.</para>
-
- <para>Some applications consist of multiple distribution
- files that must be downloaded from a number of different
- sites. For example,
- <application>Ghostscript</application> consists of the
- core of the program, and then a large number of driver
- files that are used depending on the user's printer. Some
- of these driver files are supplied with the core, but many
- others must be downloaded from a variety of different
- sites.</para>
-
- <para>To support this, each entry in
- <varname>DISTFILES</varname> may be followed by a colon
- and a <quote>tag name</quote>. Each site listed in
- <varname>MASTER_SITES</varname> is then followed by a
- colon, and the tag that indicates which distribution files
- should be downloaded from this site.</para>
-
- <para>For example, consider an application with the source
- split in two parts, <filename>source1.tar.gz</filename>
- and <filename>source2.tar.gz</filename>, which must be
- downloaded from two different sites. The port's
- <filename>Makefile</filename> would include lines like
- <xref linkend="ports-master-sites-n-example-simple-use-one-file-per-site"/>.</para>
-
- <example xml:id="ports-master-sites-n-example-simple-use-one-file-per-site">
- <title>Simplified use of <literal>MASTER_SITES:n</literal>
- with 1 file per site</title>
-
- <programlisting>MASTER_SITES= ftp://ftp.example1.com/:source1 \
- ftp://ftp.example2.com/:source2
-DISTFILES= source1.tar.gz:source1 \
- source2.tar.gz:source2</programlisting>
- </example>
-
- <para>Multiple distribution files can have the same tag.
- Continuing the previous example, suppose that there was a
- third distfile, <filename>source3.tar.gz</filename>, that
- should be downloaded from
- <systemitem>ftp.example2.com</systemitem>. The
- <filename>Makefile</filename> would then be written like
- <xref linkend="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"/>.</para>
-
- <example xml:id="ports-master-sites-n-example-simple-use-more-than-one-file-per-site">
- <title>Simplified use of <literal>MASTER_SITES:n</literal>
- with more than 1 file per site</title>
-
- <programlisting>MASTER_SITES= ftp://ftp.example1.com/:source1 \
- ftp://ftp.example2.com/:source2
-DISTFILES= source1.tar.gz:source1 \
- source2.tar.gz:source2 \
- source3.tar.gz:source2</programlisting>
- </example>
- </sect3>
+ <sect2 xml:id="makefile-build_depends">
+ <title><varname>BUILD_DEPENDS</varname></title>
- <sect3>
- <title>Detailed information</title>
+ <para xml:lang="en">This variable specifies executables or files this port
+ requires to build. Like <varname>RUN_DEPENDS</varname>, it
+ is a list of
+ <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional>
+ tuples. For example,</para>
- <para>Okay, so the previous section example did not reflect
- your needs? In this section we will explain in detail how
- the fine grained fetching mechanism
- <literal>MASTER_SITES:n</literal> works and how you can
- modify your ports to use it.</para>
+ <programlisting>BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>
- <orderedlist>
- <listitem>
- <para>Elements can be postfixed with
- <literal>:n</literal> where
- <replaceable>n</replaceable> is
- <literal>[^:,]+</literal>, i.e.,
- <replaceable>n</replaceable> could conceptually be any
- alphanumeric string but we will limit it to
- <literal>[a-zA-Z_][0-9a-zA-Z_]+</literal> for
- now.</para>
-
- <para>Moreover, string matching is case sensitive;
- i.e., <literal>n</literal> is different from
- <literal>N</literal>.</para>
-
- <para>However, the following words cannot be used for
- postfixing purposes since they yield special meaning:
- <literal>default</literal>, <literal>all</literal> and
- <literal>ALL</literal> (they are used internally in
- item <xref linkend="porting-master-sites-n-what-changes-in-port-targets"/>).
- Furthermore, <literal>DEFAULT</literal> is a special
- purpose word (check item <xref linkend="porting-master-sites-n-DEFAULT-group"/>).</para>
- </listitem>
+ <para xml:lang="en">will check for an executable called
+ <command>unzip</command>, and descend into the
+ <filename>archivers/unzip</filename> subdirectory of the
+ ports tree to build and install it if it is not found.</para>
- <listitem>
- <para>Elements postfixed with <literal>:n</literal>
- belong to the group <literal>n</literal>,
- <literal>:m</literal> belong to group
- <literal>m</literal> and so forth.</para>
- </listitem>
+ <note>
+ <para xml:lang="en"><quote>build</quote> here means everything from
+ extraction to compilation. The dependency is checked from
+ within the <buildtarget xml:lang="en">extract</buildtarget> target. The
+ <replaceable>target</replaceable> part can be omitted if it
+ is the same as <varname>DEPENDS_TARGET</varname></para>
+ </note>
+ </sect2>
- <listitem xml:id="porting-master-sites-n-DEFAULT-group">
- <para>Elements without a postfix are groupless, i.e.,
- they all belong to the special group
- <literal>DEFAULT</literal>. If you postfix any
- elements with <literal>DEFAULT</literal>, you are just
- being redundant unless you want to have an element
- belonging to both <literal>DEFAULT</literal> and other
- groups at the same time (check item <xref linkend="porting-master-sites-n-comma-operator"/>).</para>
+ <sect2 xml:id="makefile-fetch_depends">
+ <title><varname>FETCH_DEPENDS</varname></title>
- <para>The following examples are equivalent but the
- first one is preferred:</para>
+ <para xml:lang="en">This variable specifies executables or files this port
+ requires to fetch. Like the previous two, it is a list of
+ <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional>
+ tuples. For example,</para>
- <programlisting>MASTER_SITES= alpha
+ <programlisting>FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting>
-MASTER_SITES= alpha:DEFAULT</programlisting>
- </listitem>
+ <para xml:lang="en">will check for an executable called
+ <command>ncftp2</command>, and descend into the
+ <filename>net/ncftp2</filename> subdirectory of the ports
+ tree to build and install it if it is not found.</para>
- <listitem>
- <para>Groups are not exclusive, an element may belong to
- several different groups at the same time and a group
- can either have either several different elements or
- none at all. Repeated elements within the same group
- will be simply that, repeated elements.</para>
- </listitem>
+ <para xml:lang="en">The dependency is checked from within the
+ <buildtarget xml:lang="en">fetch</buildtarget> target. The
+ <replaceable>target</replaceable> part can be omitted if it is
+ the same as <varname>DEPENDS_TARGET</varname>.</para>
+ </sect2>
- <listitem xml:id="porting-master-sites-n-comma-operator">
- <para>When you want an element to belong to several
- groups at the same time, you can use the comma
- operator (<literal>,</literal>).</para>
+ <sect2 xml:id="makefile-extract_depends">
+ <title><varname>EXTRACT_DEPENDS</varname></title>
- <para>Instead of repeating it several times, each time
- with a different postfix, we can list several groups
- at once in a single postfix. For instance,
- <literal>:m,n,o</literal> marks an element that
- belongs to group <literal>m</literal>,
- <literal>n</literal> and <literal>o</literal>.</para>
+ <para xml:lang="en">This variable specifies executables or files this port
+ requires for extraction. Like the previous, it is a list of
+ <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional>
+ tuples. For example,</para>
- <para>All the following examples are equivalent but the
- last one is preferred:</para>
+ <programlisting xml:lang="en">EXTRACT_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>
- <programlisting>MASTER_SITES= alpha alpha:SOME_SITE
+ <para xml:lang="en">will check for an executable called
+ <command>unzip</command>, and descend into the
+ <filename>archivers/unzip</filename> subdirectory of the
+ ports tree to build and install it if it is not found.</para>
-MASTER_SITES= alpha:DEFAULT alpha:SOME_SITE
+ <para xml:lang="en">The dependency is checked from within the
+ <buildtarget xml:lang="en">extract</buildtarget> target. The
+ <replaceable>target</replaceable> part can be omitted if it
+ is the same as <varname>DEPENDS_TARGET</varname>.</para>
-MASTER_SITES= alpha:SOME_SITE,DEFAULT
+ <note>
+ <para xml:lang="en">Use this variable only if the extraction does not
+ already work (the default assumes <command>tar</command>)
+ and cannot be made to work using
+ <literal>USES=tar</literal>, <literal>USES=lha</literal> or
+ <literal>USES=zip</literal> described in <xref linkend="uses-values"/>.</para>
+ </note>
+ </sect2>
-MASTER_SITES= alpha:DEFAULT,SOME_SITE</programlisting>
- </listitem>
+ <sect2 xml:id="makefile-patch_depends">
+ <title><varname>PATCH_DEPENDS</varname></title>
- <listitem>
- <para>All sites within a given group are sorted
- according to <varname>MASTER_SORT_AWK</varname>. All
- groups within <varname>MASTER_SITES</varname> and
- <varname>PATCH_SITES</varname> are sorted as
- well.</para>
- </listitem>
+ <para xml:lang="en">This variable specifies executables or files this port
+ requires to patch. Like the previous, it is a list of
+ <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional>
+ tuples. For example,</para>
- <listitem xml:id="porting-master-sites-n-group-semantics">
- <para>Group semantics can be used in any of the
- following variables <varname>MASTER_SITES</varname>,
- <varname>PATCH_SITES</varname>,
- <varname>MASTER_SITE_SUBDIR</varname>,
- <varname>PATCH_SITE_SUBDIR</varname>,
- <varname>DISTFILES</varname>, and
- <varname>PATCHFILES</varname> according to the
- following syntax:</para>
-
- <orderedlist>
- <listitem>
- <para>All <varname>MASTER_SITES</varname>,
- <varname>PATCH_SITES</varname>,
- <varname>MASTER_SITE_SUBDIR</varname> and
- <varname>PATCH_SITE_SUBDIR</varname> elements must
- be terminated with the forward slash
- <literal>/</literal> character. If any elements
- belong to any groups, the group postfix
- <literal>:n</literal>
- must come right after the terminator
- <literal>/</literal>. The
- <literal>MASTER_SITES:n</literal> mechanism relies
- on the existence of the terminator
- <literal>/</literal> to avoid confusing elements
- where a <literal>:n</literal> is a valid part of
- the element with occurrences where
- <literal>:n</literal> denotes group
- <literal>n</literal>. For compatibility purposes,
- since the <literal>/</literal> terminator was not
- required before in both
- <varname>MASTER_SITE_SUBDIR</varname> and
- <varname>PATCH_SITE_SUBDIR</varname> elements, if
- the postfix immediate preceding character is not
- a <literal>/</literal> then <literal>:n</literal>
- will be considered a valid part of the element
- instead of a group postfix even if an element is
- postfixed with <literal>:n</literal>. See both
- <xref linkend="ports-master-sites-n-example-detailed-use-master-site-subdir"/>
- and <xref linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para>
-
- <example xml:id="ports-master-sites-n-example-detailed-use-master-site-subdir">
- <title>Detailed use of
- <literal>MASTER_SITES:n</literal> in
- <varname>MASTER_SITE_SUBDIR</varname></title>
-
- <programlisting>MASTER_SITE_SUBDIR= old:n new/:NEW</programlisting>
-
- <itemizedlist>
- <listitem>
- <para>Directories within group
- <literal>DEFAULT</literal> -&gt; old:n</para>
- </listitem>
-
- <listitem>
- <para>Directories within group
- <literal>NEW</literal> -&gt; new</para>
- </listitem>
- </itemizedlist>
- </example>
-
- <example xml:id="ports-master-sites-n-example-detailed-use-complete-example-master-sites">
- <title>Detailed use of
- <literal>MASTER_SITES:n</literal> with comma
- operator, multiple files, multiple sites and
- multiple subdirectories</title>
-
- <programlisting>MASTER_SITES= http://site1/%SUBDIR%/ http://site2/:DEFAULT \
- http://site3/:group3 http://site4/:group4 \
- http://site5/:group5 http://site6/:group6 \
- http://site7/:DEFAULT,group6 \
- http://site8/%SUBDIR%/:group6,group7 \
- http://site9/:group8
-DISTFILES= file1 file2:DEFAULT file3:group3 \
- file4:group4,group5,group6 file5:grouping \
- file6:group7
-MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \
- directory-one/:group6,DEFAULT \
- directory</programlisting>
-
- <para>The previous example results in the
- following fine grained fetching. Sites are
- listed in the exact order they will be
- used.</para>
-
- <itemizedlist>
- <listitem>
- <para><filename>file1</filename> will be
- fetched from</para>
-
- <itemizedlist>
- <listitem>
- <para><varname>MASTER_SITE_OVERRIDE</varname></para>
- </listitem>
-
- <listitem>
- <para>http://site1/directory-trial:1/</para>
- </listitem>
-
- <listitem>
- <para>http://site1/directory-one/</para>
- </listitem>
-
- <listitem>
- <para>http://site1/directory/</para>
- </listitem>
-
- <listitem>
- <para>http://site2/</para>
- </listitem>
-
- <listitem>
- <para>http://site7/</para>
- </listitem>
-
- <listitem>
- <para><varname>MASTER_SITE_BACKUP</varname></para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para><filename>file2</filename> will be
- fetched exactly as
- <filename>file1</filename> since they
- both belong to the same group</para>
-
- <itemizedlist>
- <listitem>
- <para><varname>MASTER_SITE_OVERRIDE</varname></para>
- </listitem>
-
- <listitem>
- <para>http://site1/directory-trial:1/</para>
- </listitem>
-
- <listitem>
- <para>http://site1/directory-one/</para>
- </listitem>
-
- <listitem>
- <para>http://site1/directory/</para>
- </listitem>
-
- <listitem>
- <para>http://site2/</para>
- </listitem>
-
- <listitem>
- <para>http://site7/</para>
- </listitem>
-
- <listitem>
- <para><varname>MASTER_SITE_BACKUP</varname></para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para><filename>file3</filename> will be
- fetched from</para>
-
- <itemizedlist>
- <listitem>
- <para><varname>MASTER_SITE_OVERRIDE</varname></para>
- </listitem>
-
- <listitem>
- <para>http://site3/</para>
- </listitem>
-
- <listitem>
- <para><varname>MASTER_SITE_BACKUP</varname></para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para><filename>file4</filename> will be
- fetched from</para>
-
- <itemizedlist>
- <listitem>
- <para><varname>MASTER_SITE_OVERRIDE</varname></para>
- </listitem>
-
- <listitem>
- <para>http://site4/</para>
- </listitem>
-
- <listitem>
- <para>http://site5/</para>
- </listitem>
-
- <listitem>
- <para>http://site6/</para>
- </listitem>
-
- <listitem>
- <para>http://site7/</para>
- </listitem>
-
- <listitem>
- <para>http://site8/directory-one/</para>
- </listitem>
-
- <listitem>
- <para><varname>MASTER_SITE_BACKUP</varname></para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para><filename>file5</filename> will be
- fetched from</para>
-
- <itemizedlist>
- <listitem>
- <para><varname>MASTER_SITE_OVERRIDE</varname></para>
- </listitem>
-
- <listitem>
- <para><varname>MASTER_SITE_BACKUP</varname></para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para><filename>file6</filename> will be
- fetched from</para>
-
- <itemizedlist>
- <listitem>
- <para><varname>MASTER_SITE_OVERRIDE</varname></para>
- </listitem>
-
- <listitem>
- <para>http://site8/</para>
- </listitem>
-
- <listitem>
- <para><varname>MASTER_SITE_BACKUP</varname></para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- </example>
- </listitem>
- </orderedlist>
- </listitem>
+ <programlisting>PATCH_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/java/jfc:extract</programlisting>
- <listitem>
- <para>How do I group one of the special variables from
- <filename>bsd.sites.mk</filename>, e.g.,
- <varname>MASTER_SITE_SOURCEFORGE</varname>?</para>
+ <para xml:lang="en">will descend into the <filename>java/jfc</filename>
+ subdirectory of the ports tree to extract it.</para>
- <para>See <xref linkend="ports-master-sites-n-example-detailed-use-master-site-sourceforge"/>.</para>
+ <para xml:lang="en">The dependency is checked from within the
+ <buildtarget xml:lang="en">patch</buildtarget> target. The
+ <replaceable>target</replaceable> part can be omitted if it
+ is the same as <varname>DEPENDS_TARGET</varname>.</para>
+ </sect2>
- <example xml:id="ports-master-sites-n-example-detailed-use-master-site-sourceforge">
- <title>Detailed use of
- <literal>MASTER_SITES:n</literal> with
- <varname>MASTER_SITE_SOURCEFORGE</varname></title>
+ <sect2 xml:id="makefile-uses">
+ <title><varname>USES</varname></title>
- <programlisting>MASTER_SITES= http://site1/ ${MASTER_SITE_SOURCEFORGE:S/$/:sourceforge,TEST/}
-DISTFILES= something.tar.gz:sourceforge</programlisting>
- </example>
+ <para xml:lang="en">Parameters can be added to define different features and
+ dependencies used by the port. They are specified by adding
+ this line to the <filename>Makefile</filename>:</para>
- <para><filename>something.tar.gz</filename> will be
- fetched from all sites within
- <varname>MASTER_SITE_SOURCEFORGE</varname>.</para>
- </listitem>
+ <programlisting>USES= feature[:arguments]</programlisting>
- <listitem>
- <para>How do I use this with <varname>PATCH*</varname>
- variables?</para>
-
- <para>All examples were done with
- <varname>MASTER*</varname> variables but they work
- exactly the same for <varname>PATCH*</varname> ones as
- can be seen in <xref linkend="ports-master-sites-n-example-detailed-use-patch-sites"/>.</para>
-
- <example xml:id="ports-master-sites-n-example-detailed-use-patch-sites">
- <title>Simplified use of
- <literal>MASTER_SITES:n</literal> with
- <varname>PATCH_SITES</varname>.</title>
-
- <programlisting>PATCH_SITES= http://site1/ http://site2/:test
-PATCHFILES= patch1:test</programlisting>
- </example>
- </listitem>
- </orderedlist>
- </sect3>
+ <para xml:lang="en">For the complete list of values, please see
+ <xref linkend="uses-values"/>.</para>
- <sect3>
- <title>What does change for ports? What does not?</title>
+ <warning>
+ <para xml:lang="en"><varname>USES</varname> cannot be assigned after
+ inclusion of <filename>bsd.port.pre.mk</filename>.</para>
+ </warning>
+ </sect2>
- <orderedlist numeration="lowerroman">
- <listitem>
- <para>All current ports remain the same. The
- <literal>MASTER_SITES:n</literal> feature code is only
- activated if there are elements postfixed with
- <literal>:n</literal> like
- elements according to the aforementioned syntax rules,
- especially as shown in item <xref linkend="porting-master-sites-n-group-semantics"/>.</para>
- </listitem>
+ <sect2 xml:id="makefile-use-vars">
+ <title><varname>USE_<replaceable>*</replaceable></varname></title>
- <listitem xml:id="porting-master-sites-n-what-changes-in-port-targets">
- <para>The port targets remain the same:
- <buildtarget>checksum</buildtarget>,
- <buildtarget>makesum</buildtarget>,
- <buildtarget>patch</buildtarget>,
- <buildtarget>configure</buildtarget>,
- <buildtarget>build</buildtarget>, etc. With the obvious
- exceptions of <buildtarget>do-fetch</buildtarget>,
- <buildtarget>fetch-list</buildtarget>,
- <buildtarget>master-sites</buildtarget> and
- <buildtarget>patch-sites</buildtarget>.</para>
-
- <itemizedlist>
- <listitem>
- <para><buildtarget>do-fetch</buildtarget>: deploys the
- new grouping postfixed
- <varname>DISTFILES</varname> and
- <varname>PATCHFILES</varname> with their matching
- group elements within both
- <varname>MASTER_SITES</varname> and
- <varname>PATCH_SITES</varname> which use matching
- group elements within both
- <varname>MASTER_SITE_SUBDIR</varname> and
- <varname>PATCH_SITE_SUBDIR</varname>. Check <xref linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para>
- </listitem>
-
- <listitem>
- <para><buildtarget>fetch-list</buildtarget>: works
- like old <buildtarget>fetch-list</buildtarget> with
- the exception that it groups just like
- <buildtarget>do-fetch</buildtarget>.</para>
- </listitem>
-
- <listitem>
- <para><buildtarget>master-sites</buildtarget> and
- <buildtarget>patch-sites</buildtarget>:
- (incompatible with older versions) only return the
- elements of group <literal>DEFAULT</literal>; in
- fact, they execute targets
- <buildtarget>master-sites-default</buildtarget> and
- <buildtarget>patch-sites-default</buildtarget>
- respectively.</para>
-
- <para>Furthermore, using target either
- <buildtarget>master-sites-all</buildtarget> or
- <buildtarget>patch-sites-all</buildtarget> is
- preferred to directly checking either
- <buildtarget>MASTER_SITES</buildtarget> or
- <buildtarget>PATCH_SITES</buildtarget>. Also,
- directly checking is not guaranteed to work in any
- future versions. Check item <xref linkend="porting-master-sites-n-new-port-targets-master-sites-all"/>
- for more information on these new port
- targets.</para>
- </listitem>
-
- </itemizedlist>
- </listitem>
+ <para xml:lang="en">Several variables exist to define common dependencies
+ shared by many ports. Their use is optional, but helps to
+ reduce the verbosity of the port
+ <filename>Makefile</filename>s. Each of them is styled as
+ <varname>USE_<replaceable>*</replaceable></varname>. These
+ variables may be used only in the port
+ <filename>Makefile</filename>s and
+ <filename>ports/Mk/bsd.*.mk</filename>. They are not meant
+ for user-settable options — use
+ <varname>PORT_OPTIONS</varname> for that purpose.</para>
- <listitem>
- <para>New port targets</para>
-
- <orderedlist>
- <listitem>
- <para>There are
- <buildtarget>master-sites-<replaceable>n</replaceable></buildtarget>
- and
- <buildtarget>patch-sites-<replaceable>n</replaceable></buildtarget>
- targets which will list the elements of the
- respective group <replaceable>n</replaceable>
- within <varname>MASTER_SITES</varname> and
- <varname>PATCH_SITES</varname> respectively. For
- instance, both
- <buildtarget>master-sites-DEFAULT</buildtarget> and
- <buildtarget>patch-sites-DEFAULT</buildtarget> will
- return the elements of group
- <literal>DEFAULT</literal>,
- <buildtarget>master-sites-test</buildtarget> and
- <buildtarget>patch-sites-test</buildtarget> of group
- <literal>test</literal>, and thereon.</para>
- </listitem>
-
- <listitem xml:id="porting-master-sites-n-new-port-targets-master-sites-all">
- <para>There are new targets
- <buildtarget>master-sites-all</buildtarget> and
- <buildtarget>patch-sites-all</buildtarget> which do
- the work of the old
- <buildtarget>master-sites</buildtarget> and
- <buildtarget>patch-sites</buildtarget> ones. They
- return the elements of all groups as if they all
- belonged to the same group with the caveat that it
- lists as many
- <varname>MASTER_SITE_BACKUP</varname> and
- <varname>MASTER_SITE_OVERRIDE</varname> as there
- are groups defined within either
- <varname>DISTFILES</varname> or
- <varname>PATCHFILES</varname>; respectively for
- <buildtarget>master-sites-all</buildtarget> and
- <buildtarget>patch-sites-all</buildtarget>.</para>
- </listitem>
- </orderedlist>
- </listitem>
- </orderedlist>
- </sect3>
- </sect2>
-
- <sect2>
- <title><varname>DIST_SUBDIR</varname></title>
-
- <para>Do not let your port clutter
- <filename>/usr/ports/distfiles</filename>. If your port requires a
- lot of files to be fetched, or contains a file that has a name that
- might conflict with other ports (e.g.,
- <filename>Makefile</filename>), set <varname>DIST_SUBDIR</varname>
- to the name of the port (<literal>${PORTNAME}</literal> or
- <literal>${PKGNAMEPREFIX}${PORTNAME}</literal>
- should work fine). This will change
- <varname>DISTDIR</varname> from the default
- <filename>/usr/ports/distfiles</filename> to
- <filename>/usr/ports/distfiles/DIST_SUBDIR</filename>,
- and in effect puts everything that is required for your port into
- that subdirectory.</para>
-
- <para>It will also look at the subdirectory with the same name on the
- backup master site at <filename>ftp.FreeBSD.org</filename>.
- (Setting <varname>DISTDIR</varname> explicitly in your
- <varname>Makefile</varname> will not accomplish this, so please use
- <varname>DIST_SUBDIR</varname>.)</para>
+ <note>
+ <para xml:lang="en">It is <emphasis>always</emphasis> incorrect to set any
+ <varname>USE_<replaceable>*</replaceable></varname> in
+ <filename>/etc/make.conf</filename>. For instance,
+ setting</para>
- <note>
- <para>This does not affect the <varname>MASTER_SITES</varname> you
- define in your <filename>Makefile</filename>.</para>
- </note>
- </sect2>
-
- <sect2>
- <title><varname>ALWAYS_KEEP_DISTFILES</varname></title>
-
- <para>If your port uses binary distfiles and has a license that
- requires that the source code is provided with packages distributed
- in binary form, e.g. GPL, <varname>ALWAYS_KEEP_DISTFILES</varname>
- will instruct the &os; build cluster to keep a copy of the files
- specified in <varname>DISTFILES</varname>. Users of these ports
- will generally not need these files, so it is a good idea to only
- add the source distfiles to <varname>DISTFILES</varname> when
- <varname>PACKAGE_BUILDING</varname> is defined.
- </para>
-
- <example xml:id="ports-master-sites-n-example-always-keep-distfiles">
- <title>Use of <varname>ALWAYS_KEEP_DISTFILES</varname>.</title>
- <programlisting>.if defined(PACKAGE_BUILDING)
-DISTFILES+= <replaceable>foo.tar.gz</replaceable>
-ALWAYS_KEEP_DISTFILES= yes
-.endif</programlisting>
- </example>
+ <programlisting>USE_GCC=X.Y</programlisting>
- <para>When adding extra files to <varname>DISTFILES</varname>,
- make sure you also add them to <filename>distinfo</filename>.
- Also, the additional files will normally be extracted into
- <varname>WRKDIR</varname> as well, which for some ports may
- lead to undesirable sideeffects and require special handling.</para>
- </sect2>
- </sect1>
-
- <sect1 xml:id="makefile-maintainer">
- <title><varname>MAINTAINER</varname></title>
-
- <para>Set your mail-address here. Please. <!-- smiley
- --><emphasis>:-)</emphasis></para>
-
- <para>Note that only a single address without the comment part is
- allowed as a <varname>MAINTAINER</varname> value.
- The format used should be <literal>user@hostname.domain</literal>.
- Please do not include any descriptive text such as your real
- name in this entry&mdash;that merely confuses
- <filename>bsd.port.mk</filename>.</para>
-
- <para>The maintainer is responsible for keeping the port up to
- date, and ensuring the port works correctly.
- For a detailed description of the responsibilities of a port
- maintainer, refer to the <link xlink:href="&url.articles.contributing-ports;/maintain-port.html">The
- challenge for port maintainers</link> section.</para>
-
- <para>Changes to the port will be sent to the maintainer of
- a port for a review and an approval before being committed.
- If the maintainer does not respond to an update
- request after two weeks (excluding major public
- holidays), then that is considered a maintainer timeout, and the
- update may be made without explicit maintainer approval. If the
- maintainer does not respond within three months, then that
- maintainer is considered absent without leave, and can be
- replaced as the maintainer of the particular port in question.
- Exceptions to this are anything maintained by the &a.portmgr;, or
- the &a.security-officer;. No unauthorized commits may ever be
- made to ports maintained by those groups.</para>
-
- <para>We reserve the right to modify the maintainer's submission
- to better match existing policies and style of the Ports
- Collection without explicit blessing from the submitter.
- Also, large infrastructural changes can result in
- a port being modified without maintainer's consent.
- This kind of changes will never affect the port's
- functionality.</para>
-
- <para>The &a.portmgr; reserves the right to revoke or override
- anyone's maintainership for any reason, and the &a.security-officer;
- reserves the right to revoke or override maintainership for security
- reasons.</para>
- </sect1>
-
- <sect1 xml:id="makefile-comment">
- <title><varname>COMMENT</varname></title>
-
- <para>This is a one-line description of the port.
- <emphasis>Please</emphasis> do not include the package name (or
- version number of the software) in the comment. The comment
- should begin with a capital and end without a period. Here
- is an example:</para>
-
- <programlisting>COMMENT= A cat chasing a mouse all over the screen</programlisting>
-
- <para>The COMMENT variable should immediately follow the MAINTAINER
- variable in the <filename>Makefile</filename>.</para>
-
- <para>Please try to keep the COMMENT line less than 70
- characters, as it is displayed to users as a one-line
- summary of the port.</para>
- </sect1>
-
- <sect1 xml:id="makefile-depend">
- <title>Dependencies</title>
-
- <para>Many ports depend on other ports. There are seven variables that
- you can use to ensure that all the required bits will be on the
- user's machine. There are also some pre-supported dependency
- variables for common cases, plus a few more to control the behavior
- of dependencies.</para>
-
- <sect2>
- <title><varname>LIB_DEPENDS</varname></title>
-
- <para>This variable specifies the shared libraries this port depends
- on. It is a list of
- <replaceable>lib</replaceable>:<replaceable>dir</replaceable><optional>:target</optional>
- tuples where <replaceable>lib</replaceable> is the name of the
- shared library, <replaceable>dir</replaceable> is the
- directory in which to find it in case it is not available, and
- <replaceable>target</replaceable> is the target to call in that
- directory. For example,
- <programlisting>LIB_DEPENDS= jpeg.9:${PORTSDIR}/graphics/jpeg</programlisting>
- will check for a shared jpeg library with major version 9, and
- descend into the <filename>graphics/jpeg</filename> subdirectory
- of your ports tree to build and install it if it is not found.
- The <replaceable>target</replaceable> part can be omitted if it is
- equal to <varname>DEPENDS_TARGET</varname> (which defaults to
- <literal>install</literal>).</para>
+ <para xml:lang="en">(where X.Y is version number) would add a dependency
+ on gccXY for every port, including
+ <literal>lang/gccXY</literal> itself!</para>
+ </note>
- <note>
- <para>The <replaceable>lib</replaceable> part is a regular
- expression which is being looked up in the
- <command>ldconfig -r</command> output. Values such as
- <literal>intl.[5-7]</literal> and <literal>intl</literal> are
- allowed. The first pattern,
- <literal>intl.[5-7]</literal>, will match any of:
- <literal>intl.5</literal>, <literal>intl.6</literal> or
- <literal>intl.7</literal>. The second pattern,
- <literal>intl</literal>, will match any version of the
- <literal>intl</literal> library.</para>
- </note>
+ <table frame="none" xml:id="makefile-use-vars-table">
+ <title><varname>USE_<replaceable>*</replaceable></varname></title>
- <para>The dependency is checked twice, once from within the
- <buildtarget>extract</buildtarget> target and then from within the
- <buildtarget>install</buildtarget> target. Also, the name of the
- dependency is put into the package so that
- &man.pkg.add.1; will automatically install it if it is
- not on the user's system.</para>
- </sect2>
-
- <sect2>
- <title><varname>RUN_DEPENDS</varname></title>
-
- <para>This variable specifies executables or files this port depends
- on during run-time. It is a list of
- <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional>
- tuples where <replaceable>path</replaceable> is the name of the
- executable or file, <replaceable>dir</replaceable> is the
- directory in which to find it in case it is not available, and
- <replaceable>target</replaceable> is the target to call in that
- directory. If <replaceable>path</replaceable> starts with a slash
- (<literal>/</literal>), it is treated as a file and its existence
- is tested with <command>test -e</command>; otherwise, it is
- assumed to be an executable, and <command>which -s</command> is
- used to determine if the program exists in the search path.</para>
-
- <para>For example,</para>
-
- <programlisting>RUN_DEPENDS= ${LOCALBASE}/etc/innd:${PORTSDIR}/news/inn \
- xmlcatmgr:${PORTSDIR}/textproc/xmlcatmgr</programlisting>
-
- <para>will check if the file or directory
- <filename>/usr/local/etc/innd</filename> exists, and build and
- install it from the <filename>news/inn</filename> subdirectory of
- the ports tree if it is not found. It will also see if an
- executable called <command>xmlcatmgr</command> is in the search
- path, and descend into the <filename>textproc/xmlcatmgr</filename>
- subdirectory of your ports tree to build and install it if it is
- not found.</para>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry xml:lang="en">Variable</entry>
+ <entry xml:lang="en">Means</entry>
+ </row>
+ </thead>
- <note>
- <para>In this case, <command>innd</command> is actually an
- executable; if an executable is in a place that is not expected
- to be in the search path, you should use the full
- pathname.</para>
- </note>
+ <tbody>
+ <row>
+ <entry><varname>USE_GCC</varname></entry>
+ <entry xml:lang="en">The port requires GCC (<command>gcc</command> or
+ <command>g++</command>) to build. Some ports need any
+ GCC version, some require modern, recent versions. It
+ is typically set to <literal>any</literal> (in this
+ case, GCC from base would be used on versions of FreeBSD
+ that still have it, or <literal>lang/gcc</literal>
+ port would be installed when default C/C++ compiler is
+ Clang); or <literal>yes</literal> (means always use
+ stable, modern GCC from <literal>lang/gcc</literal>
+ port). The exact version can also be specified, with
+ a value such as <literal>4.7</literal>. The minimal
+ required version can be specified as
+ <literal>4.6+</literal>. The GCC from the base system
+ is used when it satisfies the requested version,
+ otherwise an appropriate compiler is built from the
+ port, and <varname>CC</varname> and
+ <varname>CXX</varname> are adjusted
+ accordingly.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
- <note>
- <para>The official search <envar>PATH</envar> used on the ports
- build cluster is</para>
+ <para xml:lang="en">Variables related to <application>gmake</application> and
+ <filename>configure</filename> are described in
+ <xref linkend="building"/>, while
+ <application>autoconf</application>,
+ <application>automake</application> and
+ <application>libtool</application> are described in
+ <xref linkend="using-autotools"/>.
+ <application>Perl</application> related variables are
+ described in <xref linkend="using-perl"/>. X11 variables are
+ listed in <xref linkend="using-x11"/>.
+ <xref linkend="using-gnome"/> deals with GNOME and
+ <xref linkend="using-kde"/> with KDE related variables.
+ <xref linkend="using-java"/> documents Java variables, while
+ <xref linkend="using-php"/> contains information on
+ <application>Apache</application>,
+ <application>PHP</application> and PEAR modules.
+ <application>Python</application> is discussed in
+ <xref linkend="using-python"/>, while
+ <application>Ruby</application> in
+ <xref linkend="using-ruby"/>. <xref linkend="using-sdl"/>
+ provides variables used for <application>SDL</application>
+ applications and finally, <xref linkend="using-xfce"/>
+ contains information on
+ <application>Xfce</application>.</para>
+ </sect2>
- <programlisting>/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin:/usr/X11R6/bin</programlisting>
- </note>
+ <sect2 xml:id="makefile-version-dependency">
+ <title xml:lang="en">Minimal Version of a Dependency</title>
- <para>The dependency is checked from within the
- <buildtarget>install</buildtarget> target. Also, the name of the
- dependency is put into the package so that
- &man.pkg.add.1; will automatically install it if it is
- not on the user's system. The <replaceable>target</replaceable>
- part can be omitted if it is the same as
- <varname>DEPENDS_TARGET</varname>.</para>
- </sect2>
-
- <sect2>
- <title><varname>BUILD_DEPENDS</varname></title>
-
- <para>This variable specifies executables or files this port
- requires to build. Like <varname>RUN_DEPENDS</varname>, it is a
- list of
- <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional>
- tuples. For example, <programlisting> BUILD_DEPENDS=
- unzip:${PORTSDIR}/archivers/unzip</programlisting> will check
- for an executable called <command>unzip</command>, and descend
- into the <filename>archivers/unzip</filename> subdirectory of your
- ports tree to build and install it if it is not found.</para>
+ <para xml:lang="en">A minimal version of a dependency can be specified in any
+ <varname><replaceable>*</replaceable>_DEPENDS</varname>
+ except <varname>LIB_DEPENDS</varname> using this
+ syntax:</para>
- <note>
- <para><quote>build</quote> here means everything from extraction to
- compilation. The dependency is checked from within the
- <buildtarget>extract</buildtarget> target. The
- <replaceable>target</replaceable> part can be omitted if it is
- the same as <varname>DEPENDS_TARGET</varname></para>
- </note>
- </sect2>
-
- <sect2>
- <title><varname>FETCH_DEPENDS</varname></title>
-
- <para>This variable specifies executables or files this port
- requires to fetch. Like the previous two, it is a list of
- <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional>
- tuples. For example, <programlisting> FETCH_DEPENDS=
- ncftp2:${PORTSDIR}/net/ncftp2</programlisting> will check for an
- executable called <command>ncftp2</command>, and descend into the
- <filename>net/ncftp2</filename> subdirectory of your ports tree to
- build and install it if it is not found.</para>
-
- <para>The dependency is checked from within the
- <buildtarget>fetch</buildtarget> target. The
- <replaceable>target</replaceable> part can be omitted if it is the
- same as <varname>DEPENDS_TARGET</varname>.</para>
- </sect2>
-
- <sect2>
- <title><varname>EXTRACT_DEPENDS</varname></title>
-
- <para>This variable specifies executables or files this port
- requires for extraction. Like the previous, it is a list of
- <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional>
- tuples. For example, <programlisting>EXTRACT_DEPENDS=
- unzip:${PORTSDIR}/archivers/unzip</programlisting> will check
- for an executable called <command>unzip</command>, and descend
- into the <filename>archivers/unzip</filename> subdirectory of
- your ports tree to build and install it if it is not found.</para>
-
- <para>The dependency is checked from within the
- <buildtarget>extract</buildtarget> target. The
- <replaceable>target</replaceable> part can be omitted if it is the
- same as <varname>DEPENDS_TARGET</varname>.</para>
+ <programlisting xml:lang="en">p5-Spiffy&gt;=0.26:${PORTSDIR}/devel/p5-Spiffy</programlisting>
- <note>
- <para>Use this variable only if the extraction does not already
- work (the default assumes <command>gzip</command>) and cannot
- be made to work using <varname>USE_ZIP</varname> or
- <varname>USE_BZIP2</varname> described in <xref linkend="use-vars"/>.</para>
- </note>
- </sect2>
-
- <sect2>
- <title><varname>PATCH_DEPENDS</varname></title>
-
- <para>This variable specifies executables or files this port
- requires to patch. Like the previous, it is a list of
- <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional>
- tuples. For example, <programlisting> PATCH_DEPENDS=
- ${NONEXISTENT}:${PORTSDIR}/java/jfc:extract
- </programlisting>will descend into the
- <filename>java/jfc</filename> subdirectory of your ports tree to
- extract it.</para>
-
- <para>The dependency is checked from within the
- <buildtarget>patch</buildtarget> target. The
- <replaceable>target</replaceable> part can be omitted if it is the
- same as <varname>DEPENDS_TARGET</varname>.</para>
- </sect2>
-
- <sect2 xml:id="use-vars">
- <title><varname>USE_<replaceable>*</replaceable></varname></title>
+ <para xml:lang="en">The first field contains a dependent package name, which
+ must match the entry in the package database, a comparison
+ sign, and a package version. The dependency is satisfied if
+ p5-Spiffy-0.26 or newer is installed on the machine.</para>
+ </sect2>
- <para>A number of variables exist in order to encapsulate common
- dependencies that many ports have. Although their use is
- optional, they can help to reduce the verbosity of the port
- <filename>Makefile</filename>s. Each of them is styled
- as <varname>USE_<replaceable>*</replaceable></varname>. The
- usage of these variables is restricted to the port
- <filename>Makefile</filename>s and
- <filename>ports/Mk/bsd.*.mk</filename> and is not designed
- to encapsulate user-settable options &mdash; use
- <varname>WITH_<replaceable>*</replaceable></varname> and
- <varname>WITHOUT_<replaceable>*</replaceable></varname>
- for that purpose.</para>
+ <sect2 xml:id="makefile-note-on-dependencies">
+ <title xml:lang="en">Notes on Dependencies</title>
+
+ <para xml:lang="en">As mentioned above, the default target to call when a
+ dependency is required is
+ <buildtarget xml:lang="en">DEPENDS_TARGET</buildtarget>. It defaults to
+ <literal>install</literal>. This is a user variable; it is
+ never defined in a port's <filename>Makefile</filename>. If
+ the port needs a special way to handle a dependency, use the
+ <literal>:target</literal> part of
+ <varname><replaceable>*</replaceable>_DEPENDS</varname>
+ instead of redefining
+ <varname>DEPENDS_TARGET</varname>.</para>
+
+ <para xml:lang="en">When running <command>make clean</command>, the port
+ dependencies are automatically cleaned too. If this is not
+ desirable, define
+ <varname>NOCLEANDEPENDS</varname> in the environment. This
+ may be particularly desirable if the port has something that
+ takes a long time to rebuild in its dependency list, such as
+ KDE, GNOME or Mozilla.</para>
+
+ <para xml:lang="en">To depend on another port unconditionally, use the
+ variable <literal>${NONEXISTENT}</literal> as the first field
+ of <varname>BUILD_DEPENDS</varname> or
+ <varname>RUN_DEPENDS</varname>. Use this only when
+ the source of the other port is needed. Compilation time can
+ be saved by specifying the target too. For
+ instance</para>
+
+ <programlisting xml:lang="en">BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract</programlisting>
+
+ <para xml:lang="en">will always descend to the <literal>jpeg</literal> port
+ and extract it.</para>
+ </sect2>
- <note>
- <para>It is <emphasis>always</emphasis> incorrect to set
- any <varname>USE_<replaceable>*</replaceable></varname>
- in <filename>/etc/make.conf</filename>. For instance,
- setting <programlisting>USE_GCC=3.2</programlisting>
- would adds a dependency on gcc32 for every port,
- including gcc32 itself!</para>
- </note>
+ <sect2 xml:id="makefile-circular-dependencies">
+ <title xml:lang="en">Circular Dependencies Are Fatal</title>
- <table frame="none">
- <title>The <varname>USE_<replaceable>*</replaceable></varname>
- variables</title>
+ <important>
+ <para xml:lang="en">Do not introduce any circular dependencies into the
+ ports tree!</para>
+ </important>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Variable</entry>
+ <para xml:lang="en">The ports building technology does not tolerate circular
+ dependencies. If one is introduced, someone, somewhere in the
+ world, will have their FreeBSD installation broken
+ almost immediately, with many others quickly to follow. These
+ can really be hard to detect. If in doubt, before making
+ that change, make sure to run:
+ <command>cd /usr/ports; make index</command>. That process
+ can be quite slow on older machines, but it may be able to
+ save a large number of people, including yourself,
+ a lot of grief in the process.</para>
+ </sect2>
- <entry>Means</entry>
- </row>
- </thead>
+ <sect2 xml:id="makefile-automatic-dependencies">
+ <title xml:lang="en">Problems Caused by Automatic Dependencies</title>
- <tbody>
- <row>
- <entry><varname>USE_BZIP2</varname></entry>
+ <para xml:lang="en">Dependencies must be declared either explicitly or by
+ using the
+ <link linkend="makefile-options">OPTIONS framework</link>.
+ Using other methods like automatic detection complicates
+ indexing, which causes problems for port and package
+ management.</para>
- <entry>The port's tarballs are compressed with
- <command>bzip2</command>.</entry>
- </row>
+ <example xml:id="makefile-automatic-dependencies-bad">
+ <title xml:lang="en">Wrong Declaration of an Optional Dependency</title>
- <row>
- <entry><varname>USE_ZIP</varname></entry>
+ <programlisting xml:lang="en">.include &lt;bsd.port.pre.mk&gt;
- <entry>The port's tarballs are compressed with
- <command>zip</command>.</entry>
- </row>
+.if exists(${LOCALBASE}/bin/foo)
+LIB_DEPENDS= libbar.so:${PORTSDIR}/foo/bar
+.endif</programlisting>
+ </example>
- <row>
- <entry><varname>USE_BISON</varname></entry>
+ <para xml:lang="en">The problem with trying to automatically add dependencies
+ is that files and settings outside an individual port can
+ change at any time. For example: an index is built, then a
+ batch of ports are installed. But one of the ports installs
+ the tested file. The index is now incorrect, because an
+ installed port unexpectedly has a new dependency. The index
+ may still be wrong even after rebuilding if other ports also
+ determine their need for dependencies based on the existence
+ of other files.</para>
- <entry>The port uses <command>bison</command> for
- building.</entry>
- </row>
+ <example xml:id="makefile-automatic-dependencies-good">
+ <title xml:lang="en">Correct Declaration of an Optional Dependency</title>
- <row>
- <entry><varname>USE_CDRTOOLS</varname></entry>
+ <programlisting xml:lang="en">OPTIONS_DEFINE= BAR
+BAR_DESC= Calling cellphones via bar
- <entry>該 port 需要 <application>cdrecord</application>,
- 無論是 <package>sysutils/cdrtools</package> 或 <package>sysutils/cdrtools-cjk</package> 哪一種的
- <application>cdrecord</application> 皆可,視使用者偏好而定
- 。</entry>
- </row>
+BAR_LIB_DEPENDS= libbar.so:${PORTSDIR}/foo/bar</programlisting>
+ </example>
- <row>
- <entry><varname>USE_GCC</varname></entry>
-
- <entry>The port requires a specific version of
- <command>gcc</command> to build. The exact version can be
- specified with value such as <literal>3.2</literal>.
- The minimal required version can be specified as
- <literal>3.2+</literal>. The <command>gcc</command> from
- the base system is used when it satisfies the requested
- version, otherwise an appropriate <command>gcc</command> is
- compiled from ports and the <varname>CC</varname> and
- <varname>CXX</varname> variables are adjusted.</entry>
- </row>
+ <para xml:lang="en">Testing option variables is the correct method. It will
+ not cause inconsistencies in the index of a batch of ports,
+ provided the options were defined prior to the index build.
+ Simple scripts can then be used to automate the building,
+ installation, and updating of these ports and their
+ packages.</para>
+ </sect2>
- </tbody>
- </tgroup>
- </table>
+ <sect2 xml:id="use-want">
+ <title xml:lang="en"><varname>USE_<replaceable>*</replaceable></varname> and
+ <varname>WANT_<replaceable>*</replaceable></varname></title>
- <para>Variables related to <application>gmake</application> and
- the <filename>configure</filename> script are described in
- <xref linkend="building"/>, while
- <application>autoconf</application>,
- <application>automake</application> and
- <application>libtool</application> are described in
- <xref linkend="using-autotools"/>. <application>Perl</application>
- related variables are described in <xref linkend="using-perl"/>.
- X11 variables are listed in <xref linkend="using-x11"/>. <xref linkend="using-gnome"/> deals with GNOME and <xref linkend="using-kde"/> with KDE related variables. <xref linkend="using-java"/> documents Java variables, while <xref linkend="using-php"/> contains information on
- <application>Apache</application>, <application>PHP</application>
- and PEAR modules. <application>Python</application> is discussed
- in <xref linkend="using-python"/>, while
- <application>Ruby</application> in <xref linkend="using-ruby"/>.
- <xref linkend="using-sdl"/> provides variables used for
- <application>SDL</application> applications and finally,
- <xref linkend="using-xfce"/> contains information on
- <application>Xfce</application>.</para>
-
- </sect2>
-
- <sect2>
- <title>Minimal version of a dependency</title>
-
- <para>A minimal version of a dependency can be specified in any
- <varname>*_DEPENDS</varname> variable except
- <varname>LIB_DEPENDS</varname> using the following
- syntax:</para>
-
- <programlisting>p5-Spiffy&gt;=0.26:${PORTSDIR}/devel/p5-Spiffy</programlisting>
-
- <para>The first field contains a dependent package name,
- which must match the entry in the package database,
- a comparison sign, and a package version. The dependency
- is satisfied if p5-Spiffy-0.26 or newer is installed on
- the machine.</para>
- </sect2>
-
- <sect2>
- <title>Notes on dependencies</title>
-
- <para>As mentioned above, the default target to call when a
- dependency is required is <buildtarget>DEPENDS_TARGET</buildtarget>.
- It defaults to <literal>install</literal>. This is a user
- variable; it is never defined in a port's
- <filename>Makefile</filename>. If your port needs a special way
- to handle a dependency, use the <literal>:target</literal> part of
- the <varname>*_DEPENDS</varname> variables instead of redefining
- <varname>DEPENDS_TARGET</varname>.</para>
-
- <para>When you type <command>make clean</command>, its dependencies
- are automatically cleaned too. If you do not wish this to happen,
- define the variable <varname>NOCLEANDEPENDS</varname> in your
- environment. This may be particularly desirable if the port
- has something that takes a long time to rebuild in its
- dependency list, such as KDE, GNOME or Mozilla.</para>
-
- <para>To depend on another port unconditionally, use the
- variable <varname>${NONEXISTENT}</varname> as the first field
- of <varname>BUILD_DEPENDS</varname> or
- <varname>RUN_DEPENDS</varname>. Use this only when you need to
- get the source of the other port. You can often save
- compilation time by specifying the target too. For
- instance
-
- <programlisting>BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract</programlisting>
-
- will always descend to the <literal>jpeg</literal> port and extract it.</para>
- </sect2>
-
- <sect2>
- <title>Circular dependencies are fatal</title>
+ <para xml:lang="en"><varname>USE_<replaceable>*</replaceable></varname> are
+ set by the port maintainer to define software on which this
+ port depends. A port that needs Firefox would set</para>
- <important>
- <para>Do not introduce any circular dependencies into the
- ports tree!</para>
- </important>
+ <programlisting>USE_FIREFOX= yes</programlisting>
+
+ <para xml:lang="en">Some <varname>USE_<replaceable>*</replaceable></varname>
+ can accept version numbers or other parameters. For example,
+ a port that requires Apache 2.2 would set</para>
+
+ <programlisting>USE_APACHE= 22</programlisting>
+
+ <para xml:lang="en">For more control over dependencies in some cases,
+ <varname>WANT_<replaceable>*</replaceable></varname> are
+ available to more precisely specify what is needed. For
+ example, consider the <package role="port">mail/squirrelmail</package> port. This
+ port needs some PHP modules, which are listed in
+ <varname>USE_PHP</varname>:</para>
+
+ <programlisting xml:lang="en">USE_PHP= session mhash gettext mbstring pcre openssl xml</programlisting>
+
+ <para xml:lang="en">Those modules may be available in CLI or web versions, so
+ the web version is selected with
+ <varname>WANT_<replaceable>*</replaceable></varname>:</para>
+
+ <programlisting>WANT_PHP_WEB= yes</programlisting>
+
+ <para xml:lang="en">Available
+ <varname>USE_<replaceable>*</replaceable></varname> and
+ <varname>WANT_<replaceable>*</replaceable></varname> are
+ defined in the files in
+ <filename>/usr/ports/Mk</filename>.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="makefile-masterdir">
+ <title><varname>MASTERDIR</varname></title>
+
+ <para xml:lang="en">If the port needs to build slightly different versions of
+ packages by having a variable (for instance, resolution, or
+ paper size) take different values, create one subdirectory per
+ package to make it easier for users to see what to do, but try
+ to share as many files as possible between ports. Typically, by
+ using variables cleverly, only a very short
+ <filename>Makefile</filename> is needed in all but one of the
+ directories. In the sole <filename>Makefile</filename>, use
+ <varname>MASTERDIR</varname> to specify the directory where the
+ rest of the files are. Also, use a variable as part of <link linkend="porting-pkgname"><varname>PKGNAMESUFFIX</varname></link>
+ so the packages will have different names.</para>
+
+ <para xml:lang="en">This will be best demonstrated by an example. This is part
+ of <filename>japanese/xdvi300/Makefile</filename>;</para>
+
+ <programlisting>PORTNAME= xdvi
+PORTVERSION= 17
+PKGNAMEPREFIX= ja-
+PKGNAMESUFFIX= ${RESOLUTION}
- <para>The ports building technology does not tolerate
- circular dependencies. If you introduce one, you will have
- someone, somewhere in the world, whose FreeBSD installation will
- break almost immediately, with many others quickly to follow.
- These can really be hard to detect; if in doubt, before
- you make that change, make sure you have done the following:
- <command>cd /usr/ports; make index</command>. That process
- can be quite slow on older machines, but you may be able to
- save a large number of people&mdash;including yourself&mdash;
- a lot of grief in the process.</para>
- </sect2>
-
- </sect1>
-
- <sect1 xml:id="makefile-masterdir">
- <title><varname>MASTERDIR</varname></title>
-
- <para>If your port needs to build slightly different versions of
- packages by having a variable (for instance, resolution, or paper
- size) take different values, create one subdirectory per package to
- make it easier for users to see what to do, but try to share as many
- files as possible between ports. Typically you only need a very short
- <filename>Makefile</filename> in all but one of the directories if you
- use variables cleverly. In the sole <filename>Makefile</filename>,
- you can use <varname>MASTERDIR</varname> to specify the directory
- where the rest of the files are. Also, use a variable as part of
- <link linkend="porting-pkgname"><varname>PKGNAMESUFFIX</varname></link> so
- the packages will have different names.</para>
-
- <para>This will be best demonstrated by an example. This is part of
- <filename>japanese/xdvi300/Makefile</filename>;</para>
-
- <programlisting>PORTNAME= xdvi
-PORTVERSION= 17
-PKGNAMEPREFIX= ja-
-PKGNAMESUFFIX= ${RESOLUTION}
- :
# default
-RESOLUTION?= 300
+RESOLUTION?= 300
.if ${RESOLUTION} != 118 &amp;&amp; ${RESOLUTION} != 240 &amp;&amp; \
- ${RESOLUTION} != 300 &amp;&amp; ${RESOLUTION} != 400
- @${ECHO_MSG} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\""
- @${ECHO_MSG} "Possible values are: 118, 240, 300 (default) and 400."
- @${FALSE}
+ ${RESOLUTION} != 300 &amp;&amp; ${RESOLUTION} != 400
+pre-everything::
+ @${ECHO_MSG} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\""
+ @${ECHO_MSG} "Possible values are: 118, 240, 300 (default) and 400."
+ @${FALSE}
.endif</programlisting>
- <para><package>japanese/xdvi300</package> also has all the regular
- patches, package files, etc. If you type <command>make</command>
- there, it will take the default value for the resolution (300) and
- build the port normally.</para>
+ <para xml:lang="en"><package role="port">japanese/xdvi300</package> also has all
+ the regular patches, package files, etc. Running
+ <command>make</command> there, it will take the default value
+ for the resolution (300) and build the port normally.</para>
- <para>As for other resolutions, this is the <emphasis>entire</emphasis>
- <filename>xdvi118/Makefile</filename>:</para>
+ <para xml:lang="en">As for other resolutions, this is the
+ <emphasis>entire</emphasis>
+ <filename>xdvi118/Makefile</filename>:</para>
- <programlisting>RESOLUTION= 118
-MASTERDIR= ${.CURDIR}/../xdvi300
+ <programlisting>RESOLUTION= 118
+MASTERDIR= ${.CURDIR}/../xdvi300
.include "${MASTERDIR}/Makefile"</programlisting>
- <para>(<filename>xdvi240/Makefile</filename> and
- <filename>xdvi400/Makefile</filename> are similar). The
- <varname>MASTERDIR</varname> definition tells
- <filename>bsd.port.mk</filename> that the regular set of
- subdirectories like <varname>FILESDIR</varname> and
- <varname>SCRIPTDIR</varname> are to be found under
- <filename>xdvi300</filename>. The <literal>RESOLUTION=118</literal>
- line will override the <literal>RESOLUTION=300</literal> line in
- <filename>xdvi300/Makefile</filename> and the port will be built with
- resolution set to 118.</para>
- </sect1>
-
- <sect1 xml:id="makefile-manpages">
- <title>Manpages</title>
-
- <para>The <varname>MAN[1-9LN]</varname> variables will automatically add
- any manpages to <filename>pkg-plist</filename> (this means you must
- <emphasis>not</emphasis> list manpages in the
- <filename>pkg-plist</filename>&mdash;see <link linkend="plist-sub">generating PLIST</link> for more). It also
- makes the install stage automatically compress or uncompress manpages
- depending on the setting of <varname>NOMANCOMPRESS</varname> in
- <filename>/etc/make.conf</filename>.</para>
-
- <para>If your port tries to install multiple names for manpages using
- symlinks or hardlinks, you must use the <varname>MLINKS</varname>
- variable to identify these. The link installed by your port will
- be destroyed and recreated by <filename>bsd.port.mk</filename>
- to make sure it points to the correct file. Any manpages
- listed in MLINKS must not be listed in the
- <filename>pkg-plist</filename>.</para>
+ <para xml:lang="en">(<filename>xdvi240/Makefile</filename> and
+ <filename>xdvi400/Makefile</filename> are similar).
+ <varname>MASTERDIR</varname> definition tells
+ <filename>bsd.port.mk</filename> that the regular set of
+ subdirectories like <varname>FILESDIR</varname> and
+ <varname>SCRIPTDIR</varname> are to be found under
+ <filename>xdvi300</filename>. The
+ <literal>RESOLUTION=118</literal> line will override the
+ <literal>RESOLUTION=300</literal> line in
+ <filename>xdvi300/Makefile</filename> and the port will be built
+ with resolution set to 118.</para>
+ </sect1>
+
+ <sect1 xml:id="makefile-manpages">
+ <title xml:lang="en">Man Pages</title>
+
+ <para xml:lang="en">If the port anchors its man tree somewhere other than
+ <varname>PREFIX</varname>, use
+ <varname>MANDIRS</varname> to specify those directories. Note
+ that the files corresponding to manual pages must be placed in
+ <filename>pkg-plist</filename> along with the rest of the files.
+ The purpose of <varname>MANDIRS</varname> is to enable automatic
+ compression of manual pages, therefore the file names are
+ suffixed with <filename>.gz</filename>.</para>
+ </sect1>
+
+ <sect1 xml:id="makefile-info">
+ <title xml:lang="en">Info Files</title>
+
+ <para xml:lang="en">If the package needs to install <acronym>GNU</acronym> info
+ files, list them in <varname>INFO</varname> (without the
+ trailing <literal>.info</literal>), one entry per document.
+ These files are assumed to be installed to
+ <filename>PREFIX/INFO_PATH</filename>. Change
+ <varname>INFO_PATH</varname> if the package uses a different
+ location. However, this is not recommended. These entries
+ contain just the path relative to
+ <filename>PREFIX/INFO_PATH</filename>. For example,
+ <package role="port">lang/gcc34</package> installs info files to
+ <filename>PREFIX/INFO_PATH/gcc34</filename>, and
+ <varname>INFO</varname> will be something like this:</para>
+
+ <programlisting xml:lang="en">INFO= gcc34/cpp gcc34/cppinternals gcc34/g77 ...</programlisting>
+
+ <para xml:lang="en">Appropriate installation/de-installation code will be
+ automatically added to the temporary
+ <filename>pkg-plist</filename> before package
+ registration.</para>
+ </sect1>
+
+ <sect1 xml:id="makefile-options">
+ <title xml:lang="en">Makefile Options</title>
+
+ <para xml:lang="en">Many applications can be built with optional or differing
+ configurations. Examples include choice of natural (human)
+ language, GUI versus command-line, or type of database to
+ support. Users may need a different configuration than the
+ default, so the ports system provides hooks the port author can
+ use to control which variant will be built. Supporting these
+ options properly will make users happy, and effectively provide
+ two or more ports for the price of one.</para>
+
+ <sect2 xml:id="makefile-options-options">
+ <title><varname>OPTIONS</varname></title>
+
+ <sect3 xml:id="makefile-options-background">
+ <title xml:lang="en">Background</title>
+
+ <para xml:lang="en"><varname>OPTIONS_<replaceable>*</replaceable></varname>
+ give the user installing the port a dialog showing the
+ available options, and then saves those options to
+ <filename>${PORT_DBDIR}/${OPTIONS_NAME}/options</filename>.
+ The next time the port is built, the options are
+ reused. <varname>PORT_DBDIR</varname> defaults to
+ <filename>/var/db/ports</filename>.
+ <varname>OPTIONS_NAME</varname> is to the port origin with
+ an underscore as the space separator, for example, for
+ <package role="port">dns/bind99</package> it will be
+ <literal>dns_bind99</literal>.</para>
+
+ <para xml:lang="en">When the user runs <command>make config</command> (or
+ runs <command>make build</command> for the first time), the
+ framework checks for
+ <filename>${PORT_DBDIR}/${OPTIONS_NAME}/options</filename>.
+ If that file does not exist, the values of
+ <varname>OPTIONS_<replaceable>*</replaceable></varname>
+ are used, and a dialog box is
+ displayed where the options can be enabled or disabled.
+ Then <filename>options</filename> is saved and the
+ configured variables are used when building the port.</para>
+
+ <para xml:lang="en">If a new version of the port adds new
+ <varname>OPTIONS</varname>, the dialog will be presented to
+ the user with the saved values of old
+ <varname>OPTIONS</varname> prefilled.</para>
+
+ <para xml:lang="en"><command>make showconfig</command> shows the saved
+ configuration. Use <command>make rmconfig</command>
+ to remove the saved configuration.</para>
+ </sect3>
+
+ <sect3 xml:id="makefile-options-syntax">
+ <title xml:lang="en">Syntax</title>
+
+ <para xml:lang="en"><varname>OPTIONS_DEFINE</varname> contains a list of
+ <varname>OPTIONS</varname> to be used. These are
+ independent of each other and are not grouped:</para>
+
+ <programlisting xml:lang="en">OPTIONS_DEFINE= OPT1 OPT2</programlisting>
+
+ <para xml:lang="en">Once defined, <varname>OPTIONS</varname> are
+ described (optional, but strongly recommended):</para>
+
+ <programlisting xml:lang="en">OPT1_DESC= Describe OPT1
+OPT2_DESC= Describe OPT2
+OPT3_DESC= Describe OPT3
+OPT4_DESC= Describe OPT4
+OPT5_DESC= Describe OPT5
+OPT6_DESC= Describe OPT6</programlisting>
+
+ <para xml:lang="en"><filename>ports/Mk/bsd.options.desc.mk</filename>
+ has descriptions for many common <varname>OPTIONS</varname>.
+ While often useful, override them if the
+ description is insufficient for the port.</para>
+
+ <tip>
+ <para xml:lang="en">When describing options, view it from the
+ perspective of the user: <quote>What functionality does it
+ change?</quote>
+ and <quote>Why would I want to enable this?</quote>
+ Do not just repeat the name. For example, describing the
+ <literal>NLS</literal> option as
+ <quote>include NLS support</quote> does not help the user,
+ who can already see the option name but may not know what
+ it means. Describing it as <quote>Native Language Support
+ via gettext utilities</quote> is much more
+ helpful.</para>
+ </tip>
- <para>To specify whether the manpages are compressed upon installation,
- use the <varname>MANCOMPRESSED</varname> variable. This variable can
- take three values, <literal>yes</literal>, <literal>no</literal> and
- <literal>maybe</literal>. <literal>yes</literal> means manpages are
- already installed compressed, <literal>no</literal> means they are
- not, and <literal>maybe</literal> means the software already respects
- the value of <varname>NOMANCOMPRESS</varname> so
- <filename>bsd.port.mk</filename> does not have to do anything
- special.</para>
-
- <para><varname>MANCOMPRESSED</varname> is automatically set to
- <literal>yes</literal> if <varname>USE_IMAKE</varname> is set and
- <varname>NO_INSTALL_MANPAGES</varname> is not set, and to
- <literal>no</literal> otherwise. You do not have to explicitly define
- it unless the default is not suitable for your port.</para>
-
- <para>If your port anchors its man tree somewhere other than
- <varname>MANPREFIX</varname>, you can use the
- <varname>MANPREFIX</varname> to set it. Also, if only manpages in
- certain sections go in a non-standard place, such as some <literal>perl</literal> modules
- ports, you can set individual man paths using
- <varname>MAN<replaceable>sect</replaceable>PREFIX</varname> (where
- <replaceable>sect</replaceable> is one of <literal>1-9</literal>,
- <literal>L</literal> or <literal>N</literal>).</para>
-
- <para>If your manpages go to language-specific subdirectories, set the
- name of the languages to <varname>MANLANG</varname>. The value of
- this variable defaults to <literal>""</literal> (i.e., English
- only).</para>
-
- <para>Here is an example that puts it all together.</para>
-
- <programlisting>MAN1= foo.1
-MAN3= bar.3
-MAN4= baz.4
-MLINKS= foo.1 alt-name.8
-MANLANG= "" ja
-MAN3PREFIX= ${PREFIX}/share/foobar
-MANCOMPRESSED= yes</programlisting>
-
- <para>This states that six files are installed by this port;</para>
-
- <programlisting>${MANPREFIX}/man/man1/foo.1.gz
-${MANPREFIX}/man/ja/man1/foo.1.gz
-${PREFIX}/share/foobar/man/man3/bar.3.gz
-${PREFIX}/share/foobar/man/ja/man3/bar.3.gz
-${MANPREFIX}/man/man4/baz.4.gz
-${MANPREFIX}/man/ja/man4/baz.4.gz</programlisting>
-
- <para>Additionally <filename>${MANPREFIX}/man/man8/alt-name.8.gz</filename>
- may or may not be installed by your port. Regardless, a
- symlink will be made to join the foo(1) manpage and
- alt-name(8) manpage.</para>
-
- <para>If only some manpages are translated, you can use several variables
- dynamically created from <varname>MANLANG</varname> content:</para>
-
- <programlisting>MANLANG= "" de ja
-MAN1= foo.1
-MAN1_EN= bar.1
-MAN3_DE= baz.3</programlisting>
-
- <para>This translates into this list of files:</para>
-
- <programlisting>${MANPREFIX}/man/man1/foo.1.gz
-${MANPREFIX}/man/de/man1/foo.1.gz
-${MANPREFIX}/man/ja/man1/foo.1.gz
-${MANPREFIX}/man/man1/bar.1.gz
-${MANPREFIX}/man/de/man3/baz.3.gz</programlisting>
- </sect1>
-
- <sect1 xml:id="makefile-info">
- <title>Info files</title>
-
- <para>If your package needs to install GNU info files, they should be
- listed in the <varname>INFO</varname> variable (without the trailing
- <literal>.info</literal>), one entry per document. These files
- are assumed to be installed to
- <filename>PREFIX/INFO_PATH</filename>.
- You can change <varname>INFO_PATH</varname> if your package uses
- a different location. However, this is not recommended. These entries
- contain just the path relative to
- <filename>PREFIX/INFO_PATH</filename>.
- For example, <package>lang/gcc33</package> installs
- info files to
- <filename>PREFIX/INFO_PATH/gcc33</filename>,
- and <varname>INFO</varname> will be something like this:
- <programlisting>INFO= gcc33/cpp gcc33/cppinternals gcc33/g77 ...
-</programlisting>
- Appropriate installation/de-installation code will be automatically
- added to the temporary <filename>pkg-plist</filename> before package
- registration.</para>
- </sect1>
-
- <sect1 xml:id="makefile-options">
- <title>Makefile Options</title>
-
- <para>Some large applications can be built in a number of
- configurations, adding functionality if one of a number of
- libraries or applications is available. Examples include
- choice of natural (human) language, GUI versus command-line,
- or type of database to support. Since not all users
- want those libraries or applications, the ports system
- provides hooks that the port author can use to control which
- configuration should be built. Supporting these properly will
- make users happy, and effectively provide 2 or more ports for the
- price of one.</para>
-
- <sect2>
- <title>Knobs</title>
-
- <sect3>
- <title><varname>WITH_<replaceable>*</replaceable></varname> and
- <varname>WITHOUT_<replaceable>*</replaceable></varname></title>
-
- <para>These variables are designed to be set by the system
- administrator. There are many that are standardized in
- <link xlink:href="http://www.freebsd.org/cgi/cvsweb.cgi/ports/KNOBS?rev=HEAD&amp;content-type=text/x-cvsweb-markup"><filename>ports/KNOBS</filename></link>
- file.</para>
+ <important>
+ <para xml:lang="en">Option names are always in all uppercase. They
+ cannot use mixed case or lowercase.</para>
+ </important>
- <para>When creating a port, do not make knob names specific to a
- given application. For example in Avahi port, use
- <varname>WITHOUT_MDNS</varname> instead of
- <varname>WITHOUT_AVAHI_MDNS</varname>.</para>
+ <para xml:lang="en"><varname>OPTIONS</varname> can be grouped as radio
+ choices, where only one choice from each group is
+ allowed:</para>
- <note>
- <para>You should not assume that a
- <varname>WITH_<replaceable>*</replaceable></varname>
- necessarily has a corresponding
- <varname>WITHOUT_<replaceable>*</replaceable></varname>
- variable and vice versa. In general, the default is
- simply assumed.</para>
- </note>
+ <programlisting xml:lang="en">OPTIONS_SINGLE= SG1
+OPTIONS_SINGLE_SG1= OPT3 OPT4</programlisting>
- <note>
- <para>Unless otherwise specified, these variables are only
- tested for being set or not set, rather than being set to
- some kind of variable such as <literal>YES</literal> or
- <literal>NO</literal>.</para>
- </note>
+ <warning>
+ <para xml:lang="en">There <emphasis>must</emphasis> be one of each
+ <literal>OPTIONS_SINGLE</literal> group selected at all
+ times for the options to be valid. One option of each
+ group <emphasis>must</emphasis> be added to
+ <varname>OPTIONS_DEFAULT</varname>.</para>
+ </warning>
- <table frame="none">
- <title>Common <varname>WITH_<replaceable>*</replaceable></varname>
- and <varname>WITHOUT_<replaceable>*</replaceable></varname>
- variables</title>
+ <para xml:lang="en"><varname>OPTIONS</varname> can be grouped as radio
+ choices, where none or only one choice from each group
+ is allowed:</para>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Variable</entry>
+ <programlisting xml:lang="en">OPTIONS_RADIO= RG1
+OPTIONS_RADIO_RG1= OPT7 OPT8</programlisting>
- <entry>Means</entry>
- </row>
- </thead>
+ <para xml:lang="en"><varname>OPTIONS</varname> can also be grouped as
+ <quote>multiple-choice</quote> lists, where
+ <emphasis>at least one</emphasis> option must be
+ enabled:</para>
- <tbody>
- <row xml:id="knobs-without-nls">
- <entry><varname>WITHOUT_NLS</varname></entry>
+ <programlisting xml:lang="en">OPTIONS_MULTI= MG1
+OPTIONS_MULTI_MG1= OPT5 OPT6</programlisting>
- <entry>If set, says that internationalization is not
- needed, which can save compile time. By default,
- internationalization is used.</entry>
- </row>
+ <para xml:lang="en"><varname>OPTIONS</varname> can also be grouped as
+ <quote>multiple-choice</quote> lists, where none or any
+ option can be enabled:</para>
- <row>
- <entry><varname>WITH_OPENSSL_BASE</varname></entry>
+ <programlisting xml:lang="en">OPTIONS_GROUP= GG1
+OPTIONS_GROUP_GG1= OPT9 OPT10</programlisting>
- <entry>Use the version of OpenSSL in the base system.</entry>
- </row>
+ <para xml:lang="en"><varname>OPTIONS</varname> are unset by default,
+ unless they are listed in
+ <varname>OPTIONS_DEFAULT</varname>:</para>
- <row>
- <entry><varname>WITH_OPENSSL_PORT</varname></entry>
+ <programlisting xml:lang="en">OPTIONS_DEFAULT= OPT1 OPT3 OPT6</programlisting>
- <entry>Installs the version of OpenSSL from
- <package>security/openssl</package>,
- even if the base is up to date.</entry>
- </row>
+ <para xml:lang="en"><varname>OPTIONS</varname> definitions must appear
+ before the inclusion of
+ <filename>bsd.port.options.mk</filename>.
+ <varname>PORT_OPTIONS</varname> values can only be tested
+ after the inclusion of
+ <filename>bsd.port.options.mk</filename>. Inclusion of
+ <filename>bsd.port.pre.mk</filename> can be used instead,
+ too, and is still widely used in ports written before the
+ introduction of <filename>bsd.port.options.mk</filename>.
+ But be aware that some variables will not work as expected
+ after the inclusion of <filename>bsd.port.pre.mk</filename>,
+ typically some
+ <varname>USE_<replaceable>*</replaceable></varname>
+ flags.</para>
- <row>
- <entry><varname>WITHOUT_X11</varname></entry>
+ <example xml:id="ports-options-simple-use">
+ <title xml:lang="en">Simple Use of <varname>OPTIONS</varname></title>
- <entry>If the port can be built both with and without
- X support, then it should normally be built with
- X support. If this variable is defined, then
- the version that does not have X support should
- be built instead.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <programlisting xml:lang="en">OPTIONS_DEFINE= FOO BAR
+FOO_DESC= Option foo support
+BAR_DESC= Feature bar support
- </sect3>
-
- <sect3>
- <title>Knob naming</title>
- <para>It is recommended that porters use like-named knobs, for the
- benefit of end-users and to help keep the number of knob names down.
- A list of popular knob names can be found in the
- <link xlink:href="http://www.freebsd.org/cgi/cvsweb.cgi/ports/KNOBS?rev=HEAD&amp;content-type=text/x-cvsweb-markup">KNOBS</link>
- file.</para>
-
- <para>Knob names should reflect what the knob is and does.
- When a port has a lib-prefix in the <varname>PORTNAME</varname>
- the lib-prefix should be dropped in knob naming.</para>
-
- </sect3>
- </sect2>
-
- <sect2>
- <title><varname>OPTIONS</varname></title>
-
- <sect3>
- <title>Background</title>
- <para>The <varname>OPTIONS</varname> variable gives the user who
- installs the port a dialog with the available options and saves
- them to <filename>/var/db/ports/portname/options</filename>.
- Next time when the port has to be rebuild, the options are reused.
- Never again you will have to remember all the twenty
- <varname>WITH_<replaceable>*</replaceable></varname> and
- <varname>WITHOUT_<replaceable>*</replaceable></varname> options you
- used to build this port!</para>
-
- <para>When the user runs <command>make config</command> (or runs
- <command>make build</command> for the first time), the framework will
- check for
- <filename>/var/db/ports/portname/options</filename>.
- If that file does not exist, it will use the values of
- <varname>OPTIONS</varname> to create a dialogbox where the options
- can be enabled or disabled. Then the
- <filename>options</filename> file is saved and the selected
- variables will be used when building the port.</para>
-
- <para>If a new version of the port adds new
- <varname>OPTIONS</varname>, the dialog will be presented to the
- user, with the saved values of old <varname>OPTIONS</varname>
- prefilled.</para>
-
- <para>Use <command>make showconfig</command> to see the saved
- configuration. Use <command>make rmconfig</command> to remove the
- saved configuration.</para>
- </sect3>
-
- <sect3>
- <title>Syntax</title>
- <para>The syntax for the <varname>OPTIONS</varname> variable is:
-
-<programlisting>OPTIONS= OPTION "descriptive text" default ...
-</programlisting>
-
- The value for default is either <literal>ON</literal> or
- <literal>OFF</literal>. Multiple repetitions of these three fields
- are allowed.</para>
-
- <para><varname>OPTIONS</varname> definition must appear before
- the inclusion of <filename>bsd.port.pre.mk</filename>.
- The <varname>WITH_*</varname> and <varname>WITHOUT_*</varname>
- variables can only be tested after the inclusion of
- <filename>bsd.port.pre.mk</filename>.</para>
- </sect3>
-
- <sect3>
- <title>Example</title>
- <example xml:id="ports-options-simple-use">
- <title>Simple use of <varname>OPTIONS</varname></title>
- <para><programlisting>OPTIONS= FOO "Enable option foo" On \
- BAR "Support feature bar" Off
+OPTIONS_DEFAULT=FOO
-.include &lt;bsd.port.pre.mk&gt;
+# Will add --with-foo / --without-foo
+FOO_CONFIGURE_WITH= foo
+BAR_RUN_DEPENDS= bar:${PORTSDIR}/bar/bar
+
+.include &lt;bsd.port.mk&gt;</programlisting>
+ </example>
+
+ <example xml:id="ports-options-check-unset">
+ <title xml:lang="en">Check for Unset Port
+ <varname>OPTIONS</varname></title>
+
+ <programlisting xml:lang="en">.if ! ${PORT_OPTIONS:MEXAMPLES}
+CONFIGURE_ARGS+=--without-examples
+.endif</programlisting>
+
+ <para xml:lang="en">The form shown above is discouraged. The preferred
+ method is using a configure knob to really enable and
+ disable the feature to match the option:</para>
-.if defined(WITHOUT_FOO)
-CONFIGURE_ARGS+= --without-foo
+ <programlisting xml:lang="en"># Will add --with-examples / --without-examples
+EXAMPLES_CONFIGURE_WITH= examples</programlisting>
+ </example>
+
+ <example xml:id="ports-options-practical-use">
+ <title xml:lang="en">Practical Use of <varname>OPTIONS</varname></title>
+
+ <programlisting>OPTIONS_DEFINE= EXAMPLES
+
+OPTIONS_SINGLE= BACKEND
+OPTIONS_SINGLE_BACKEND= MYSQL PGSQL BDB
+
+OPTIONS_MULTI= AUTH
+OPTIONS_MULTI_AUTH= LDAP PAM SSL
+
+EXAMPLES_DESC= Install extra examples
+MYSQL_DESC= Use MySQL as backend
+PGSQL_DESC= Use PostgreSQL as backend
+BDB_DESC= Use Berkeley DB as backend
+LDAP_DESC= Build with LDAP authentication support
+PAM_DESC= Build with PAM support
+SSL_DESC= Build with OpenSSL support
+
+OPTIONS_DEFAULT= PGSQL LDAP SSL
+
+# Will add USE_PGSQL=yes
+PGSQL_USE= pgsql=yes
+# Will add --enable-postgres / --disable-postgres
+PGSQL_CONFIGURE_ENABLE= postgres
+
+ICU_LIB_DEPENDS= libicuuc.so:${PORTSDIR}/devel/icu
+
+# Will add --with-examples / --without-examples
+EXAMPLES_CONFIGURE_WITH= examples
+
+# Check other OPTIONS
+
+.include &lt;bsd.port.mk&gt;</programlisting>
+ </example>
+ </sect3>
+
+ <sect3 xml:id="makefile-options-default">
+ <title xml:lang="en">Default Options</title>
+
+ <para xml:lang="en">These options are always on by default.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para xml:lang="en"><literal>DOCS</literal> — build and install
+ documentation.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><literal>NLS</literal> — Native Language
+ Support.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><literal>EXAMPLES</literal> — build and
+ install examples.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><literal>IPV6</literal> — IPv6 protocol
+ support.</para>
+ </listitem>
+ </itemizedlist>
+
+ <note>
+ <para xml:lang="en">There is no need to add these to
+ <varname>OPTIONS_DEFAULT</varname>. To have them active,
+ and show up in the options selection dialog, however, they
+ must be added to <varname>OPTIONS_DEFINE</varname>.</para>
+ </note>
+ </sect3>
+ </sect2>
+
+ <sect2 xml:id="makefile-options-auto-activation">
+ <title xml:lang="en">Feature Auto-Activation</title>
+
+ <para xml:lang="en">When using a GNU configure script, keep an eye on which
+ optional features are activated by auto-detection. Explicitly
+ disable optional features that are not needed by
+ adding <literal>--without-xxx</literal> or
+ <literal>--disable-xxx</literal> in
+ <varname>CONFIGURE_ARGS</varname>.</para>
+
+ <example xml:id="makefile-options-auto-activation-bad">
+ <title xml:lang="en">Wrong Handling of an Option</title>
+
+ <programlisting xml:lang="en">.if ${PORT_OPTIONS:MFOO}
+LIB_DEPENDS+= libfoo.so:${PORTSDIR}/devel/foo
+CONFIGURE_ARGS+= --enable-foo
+.endif</programlisting>
+ </example>
+
+ <para xml:lang="en">In the example above, imagine a library libfoo is
+ installed on the system. The user does not want this
+ application to use libfoo, so he toggled the option off in the
+ <literal>make config</literal> dialog. But the application's
+ configure script detects the library present in the system and
+ includes its support in the resulting executable. Now when
+ the user decides to remove libfoo from the system, the ports
+ system does not protest (no dependency on libfoo was recorded)
+ but the application breaks.</para>
+
+ <example xml:id="makefile-options-auto-activation-good">
+ <title xml:lang="en">Correct Handling of an Option</title>
+
+ <programlisting xml:lang="en">FOO_LIB_DEPENDS= libfoo.so:${PORTSDIR}/devel/foo
+# Will add --enable-foo / --disable-foo
+FOO_CONFIGURE_ENABLE= foo</programlisting>
+ </example>
+
+ <note>
+ <para xml:lang="en">Under some circumstances, the shorthand conditional
+ syntax can cause problems with complex constructs. The
+ errors are usually
+ <literal>Malformed conditional</literal>, an alternative
+ syntax can be used.</para>
+
+ <programlisting xml:lang="en">.if !empty(VARIABLE:MVALUE)</programlisting>
+
+ <para xml:lang="en">as an alternative to</para>
+
+ <programlisting xml:lang="en">.if ${VARIABLE:MVALUE}</programlisting>
+ </note>
+ </sect2>
+
+ <sect2 xml:id="options-helpers">
+ <title xml:lang="en">Options Helpers</title>
+
+ <para xml:lang="en">There are some macros to help simplify conditional values
+ which differ based on the options set.</para>
+
+ <sect3 xml:id="options_sub">
+ <title><varname>OPTIONS_SUB</varname></title>
+
+ <para xml:lang="en">If <varname>OPTIONS_SUB</varname> is set to
+ <literal>yes</literal> then each of the options added to
+ <varname>OPTIONS_DEFINE</varname> will be added to
+ <varname>PLIST_SUB</varname> and
+ <varname>SUB_LIST</varname>, for example:</para>
+
+ <programlisting xml:lang="en">OPTIONS_DEFINE= OPT1
+OPTIONS_SUB= yes</programlisting>
+
+ <para xml:lang="en">is equivalent to:</para>
+
+ <programlisting>OPTIONS_DEFINE= OPT1
+
+.include &lt;bsd.port.options.mk&gt;
+
+.if ${PORT_OPTIONS:MOPT1}
+PLIST_SUB+= OPT1="" NO_OPT1="@comment "
+SUB_LIST+= OPT1="" NO_OPT1="@comment "
+.else
+PLIST_SUB+= OPT1="@comment " NO_OPT1=""
+SUB_LIST+= OPT1="@comment " NO_OPT1=""
+.endif</programlisting>
+
+ <note>
+ <para xml:lang="en">The value of <varname>OPTIONS_SUB</varname> is
+ ignored. Setting it to any value will add
+ <varname>PLIST_SUB</varname> and
+ <varname>SUB_LIST</varname> entries for
+ <emphasis>all</emphasis> options.</para>
+ </note>
+ </sect3>
+
+ <sect3 xml:id="options-use">
+ <title><varname><replaceable>OPT</replaceable>_USE</varname> and <varname><replaceable>OPT</replaceable>_USE_OFF</varname></title>
+
+ <para xml:lang="en">When option <replaceable>OPT</replaceable> is selected,
+ for each
+ <literal><replaceable>key</replaceable>=<replaceable>value</replaceable></literal>
+ pair in
+ <varname><replaceable>OPT</replaceable>_USE</varname>,
+ <replaceable>value</replaceable> is appended to the
+ corresponding
+ <varname>USE_<replaceable>KEY</replaceable></varname>. If
+ <replaceable>value</replaceable> has spaces in it, replace
+ them with commas and they will be changed back to spaces
+ during processing.
+ <varname><replaceable>OPT</replaceable>_USE_OFF</varname>
+ works the same way, but when <literal>OPT</literal> is
+ <emphasis>not</emphasis> selected. For example:</para>
+
+ <programlisting>OPTIONS_DEFINE= OPT1
+OPT1_USE= mysql=yes xorg=x11,xextproto,xext,xrandr
+OPT1_USE_OFF= openssl=yes</programlisting>
+
+ <para xml:lang="en">is equivalent to:</para>
+
+ <programlisting>OPTIONS_DEFINE= OPT1
+
+.include &lt;bsd.port.options.mk&gt;
+
+.if ${PORT_OPTIONS:MOPT1}
+USE_MYSQL= yes
+USE_XORG= x11 xextproto xext xrandr
+.else
+USE_OPENSSL= yes
+.endif</programlisting>
+ </sect3>
+
+ <sect3 xml:id="options-configure_enable">
+ <title xml:lang="en"><varname><replaceable>OPT</replaceable>_CONFIGURE_ENABLE</varname></title>
+
+ <para xml:lang="en">When option <replaceable>OPT</replaceable> is selected,
+ for each <replaceable>entry</replaceable> in
+ <varname><replaceable>OPT</replaceable>_CONFIGURE_ENABLE</varname>
+ then
+ <literal>--enable-<replaceable>entry</replaceable></literal>
+ is appended to <varname>CONFIGURE_ARGS</varname>. When
+ option <replaceable>OPT</replaceable> is
+ <emphasis>not</emphasis> selected,
+ <literal>--disable-<replaceable>entry</replaceable></literal>
+ is appended to <varname>CONFIGURE_ARGS</varname>. An
+ optional argument can be specified with an
+ <literal>=</literal> symbol. This argument is only appended
+ to the
+ <literal>--enable-<replaceable>entry</replaceable></literal>
+ configure option. For example:</para>
+
+ <programlisting>OPTIONS_DEFINE= OPT1 OPT2
+OPT1_CONFIGURE_ENABLE= test1 test2
+OPT2_CONFIGURE_ENABLE= test2=exhaustive</programlisting>
+
+ <para xml:lang="en">is equivalent to:</para>
+
+ <programlisting>OPTIONS_DEFINE= OPT1
+
+.include &lt;bsd.port.options.mk&gt;
+
+.if ${PORT_OPTIONS:MOPT1}
+CONFIGURE_ARGS+= --enable-test1 --enable-test2
.else
-CONFIGURE_ARGS+= --with-foo
+CONFIGURE_ARGS+= --disable-test1 --disable-test2
.endif
-.if defined(WITH_BAR)
-RUN_DEPENDS+= bar:${PORTSDIR}/bar/bar
+.if ${PORT_OPTIONS:MOPT2}
+CONFIGURE_ARGS+= --enable-test2=exhaustive
+.else
+CONFIGURE_ARGS+= --disable-test2
+.endif</programlisting>
+ </sect3>
+
+ <sect3 xml:id="options-configure_with">
+ <title xml:lang="en"><varname><replaceable>OPT</replaceable>_CONFIGURE_WITH</varname></title>
+
+ <para xml:lang="en">When option <replaceable>OPT</replaceable> is selected,
+ for each <replaceable>entry</replaceable> in
+ <varname><replaceable>OPT</replaceable>_CONFIGURE_WITH</varname>
+ then
+ <literal>--with-<replaceable>entry</replaceable></literal>
+ is appended to <varname>CONFIGURE_ARGS</varname>. When
+ option <replaceable>OPT</replaceable> is
+ <emphasis>not</emphasis> selected,
+ <literal>--without-<replaceable>entry</replaceable></literal>
+ is appended to <varname>CONFIGURE_ARGS</varname>. An
+ optional argument can be specified with an
+ <literal>=</literal> symbol. This argument is only appended
+ to the
+ <literal>--with-<replaceable>entry</replaceable></literal>
+ configure option. For example:</para>
+
+ <programlisting>OPTIONS_DEFINE= OPT1 OPT2
+OPT1_CONFIGURE_WITH= test1
+OPT2_CONFIGURE_WITH= test2=exhaustive</programlisting>
+
+ <para xml:lang="en">is equivalent to:</para>
+
+ <programlisting>OPTIONS_DEFINE= OPT1 OPT2
+
+.include &lt;bsd.port.options.mk&gt;
+
+.if ${PORT_OPTIONS:MOPT1}
+CONFIGURE_ARGS+= --with-test1
+.else
+CONFIGURE_ARGS+= --without-test1
.endif
-.include &lt;bsd.port.post.mk&gt;</programlisting></para>
- </example>
- </sect3>
+.if ${PORT_OPTIONS:MOPT2}
+CONFIGURE_ARGS+= --with-test2=exhaustive
+.else
+CONFIGURE_ARGS+= --without-test2
+.endif</programlisting>
+ </sect3>
+
+ <sect3 xml:id="options-configure_on">
+ <title><varname><replaceable>OPT</replaceable>_CONFIGURE_ON</varname> and <varname><replaceable>OPT</replaceable>_CONFIGURE_OFF</varname></title>
- </sect2>
+ <para xml:lang="en">When option <replaceable>OPT</replaceable> is selected,
+ the value of
+ <varname><replaceable>OPT</replaceable>_CONFIGURE_ON</varname>,
+ if defined, is appended to
+ <varname>CONFIGURE_ARGS</varname>.
+ <varname><replaceable>OPT</replaceable>_CONFIGURE_OFF</varname>
+ works the same way, but when <literal>OPT</literal> is
+ <emphasis>not</emphasis> selected. For example:</para>
- <sect2>
- <title>Feature auto-activation</title>
+ <programlisting>OPTIONS_DEFINE= OPT1
+OPT1_CONFIGURE_ON= --add-test
+OPT1_CONFIGURE_OFF= --no-test</programlisting>
- <para>When using a GNU configure script, keep an eye on which optional
- features are activated by auto-detection. Explicitly disable
- optional features you do not wish to be used by passing respective
- <literal>--without-xxx</literal> or <literal>--disable-xxx</literal>
- in <varname>CONFIGURE_ARGS</varname>.</para>
+ <para xml:lang="en">is equivalent to:</para>
- <example>
- <title>Wrong handling of an option</title>
- <programlisting>.if defined(WITH_FOO)
-LIB_DEPENDS+= foo.0:${PORTSDIR}/devel/foo
-CONFIGURE_ARGS+= --enable-foo
+ <programlisting>OPTIONS_DEFINE= OPT1
+
+.include &lt;bsd.port.options.mk&gt;
+
+.if ${PORT_OPTIONS:MOPT1}
+CONFIGURE_ARGS+= --add-test
+.else
+CONFIGURE_ARGS+= --no-test
.endif</programlisting>
- </example>
+ </sect3>
+
+ <sect3 xml:id="options-cmake_on">
+ <title xml:lang="en"><varname><replaceable>OPT</replaceable>_CMAKE_ON</varname>
+ and
+ <varname><replaceable>OPT</replaceable>_CMAKE_OFF</varname></title>
+
+ <para xml:lang="en">When option <replaceable>OPT</replaceable> is selected,
+ the value of
+ <varname><replaceable>OPT</replaceable>_CMAKE_ON</varname>,
+ if defined, is appended to <varname>CMAKE_ARGS</varname>.
+ <varname><replaceable>OPT</replaceable>_CMAKE_OFF</varname>
+ works the same way, but when <literal>OPT</literal> is
+ <emphasis>not</emphasis> selected. For example:</para>
- <para>In the example above, imagine a library libfoo is installed on
- the system. User does not want this application to use libfoo, so he
- toggled the option off in the <literal>make config</literal> dialog.
- But the application's configure script detects the library present in
- the system and includes its support in the resulting executable. Now
- when user decides to remove libfoo from the system, the ports system
- does not protest (no dependency on libfoo was recorded) but the
- application breaks.</para>
-
- <example>
- <title>Correct handling of an option</title>
- <programlisting>.if defined(WITH_FOO)
-LIB_DEPENDS+= foo.0:${PORTSDIR}/devel/foo
-CONFIGURE_ARGS+= --enable-foo
+ <programlisting>OPTIONS_DEFINE= OPT1
+OPT1_CMAKE_ON= -DTEST:BOOL=true
+OPT1_CMAKE_OFF= -DOPTIMIZE:BOOL=true</programlisting>
+
+ <para xml:lang="en">is equivalent to:</para>
+
+ <programlisting>OPTIONS_DEFINE= OPT1
+
+.include &lt;bsd.port.options.mk&gt;
+
+.if ${PORT_OPTIONS:MOPT1}
+CMAKE_ARGS+= -DTEST:BOOL=true
.else
-CONFIGURE_ARGS+= --disable-foo
+CMAKE_ARGS+= -DOPTIMIZE:BOOL=true
.endif</programlisting>
- </example>
+ </sect3>
- <para>In the second example, the library libfoo is explicitly disabled.
- The configure script does not enable related features in the
- application, despite library's presence in the system.</para>
- </sect2>
+ <sect3 xml:id="options-qmake_on">
+ <title xml:lang="en"><varname><replaceable>OPT</replaceable>_QMAKE_ON</varname>
+ and
+ <varname><replaceable>OPT</replaceable>_QMAKE_OFF</varname></title>
- </sect1>
+ <para xml:lang="en">When option <replaceable>OPT</replaceable> is selected,
+ the value of
+ <varname><replaceable>OPT</replaceable>_QMAKE_ON</varname>,
+ if defined, is appended to <varname>QMAKE_ARGS</varname>.
+ <varname><replaceable>OPT</replaceable>_QMAKE_OFF</varname>
+ works the same way, but when <literal>OPT</literal> is
+ <emphasis>not</emphasis> selected. For example:</para>
- <sect1 xml:id="makefile-wrkdir">
- <title>Specifying the working directory</title>
+ <programlisting>OPTIONS_DEFINE= OPT1
+OPT1_QMAKE_ON= -DTEST:BOOL=true
+OPT1_QMAKE_OFF= -DPRODUCTION:BOOL=true</programlisting>
- <para>Each port is extracted in to a working directory, which must be
- writable. The ports system defaults to having the
- <varname>DISTFILES</varname> unpack in to a directory called
- <literal>${DISTNAME}</literal>. In other words, if you have
- set:</para>
+ <para xml:lang="en">is equivalent to:</para>
- <programlisting>PORTNAME= foo
-PORTVERSION= 1.0</programlisting>
+ <programlisting>OPTIONS_DEFINE= OPT1
- <para>then the port's distribution files contain a top-level directory,
- <filename>foo-1.0</filename>, and the rest of the files are located
- under that directory.</para>
+.include &lt;bsd.port.options.mk&gt;
- <para>There are a number of variables you can override if that is not the
- case.</para>
+.if ${PORT_OPTIONS:MOPT1}
+QMAKE_ARGS+= -DTEST:BOOL=true
+.else
+QMAKE_ARGS+= -DPRODUCTION:BOOL=true
+.endif</programlisting>
+ </sect3>
- <sect2>
- <title><varname>WRKSRC</varname></title>
+ <sect3 xml:id="options-implies">
+ <title xml:lang="en"><varname><replaceable>OPT</replaceable>_IMPLIES</varname></title>
- <para>The variable lists the name of the directory that is created when
- the application's distfiles are extracted. If our previous example
- extracted into a directory called <filename>foo</filename> (and not
- <filename>foo-1.0</filename>) you would write:</para>
+ <para xml:lang="en">Provides a way to add dependencies between
+ options.</para>
- <programlisting>WRKSRC= ${WRKDIR}/foo</programlisting>
+ <para xml:lang="en">When <replaceable>OPT</replaceable> is selected, all the
+ options listed in this variable will be selected too. Using
+ the <link linkend="options-configure_enable"><varname><replaceable>OPT</replaceable>_CONFIGURE_ENABLE</varname></link>
+ described earlier to illustrate:</para>
- <para>or possibly</para>
+ <programlisting>OPTIONS_DEFINE= OPT1 OPT2
+OPT1_IMPLIES= OPT2
- <programlisting>WRKSRC= ${WRKDIR}/${PORTNAME}</programlisting>
- </sect2>
+OPT1_CONFIGURE_ENABLE= opt1
+OPT2_CONFIGURE_ENABLE= opt2</programlisting>
- <sect2>
- <title><varname>NO_WRKSUBDIR</varname></title>
+ <para xml:lang="en">Is equivalent to:</para>
- <para>If the port does not extract in to a subdirectory at all then
- you should set <varname>NO_WRKSUBDIR</varname> to indicate
- that.</para>
+ <programlisting>OPTIONS_DEFINE= OPT1 OPT2
- <programlisting>NO_WRKSUBDIR= yes</programlisting>
- </sect2>
- </sect1>
+.include &lt;bsd.port.options.mk&gt;
- <sect1 xml:id="conflicts">
- <title><varname>CONFLICTS</varname></title>
+.if ${PORT_OPTIONS:MOPT1}
+CONFIGURE_ARGS+= --enable-opt1
+.else
+CONFIGURE_ARGS+= --disable-opt1
+.endif
- <para>If your package cannot coexist with other packages
- (because of file conflicts, runtime incompatibility, etc.),
- list the other package names in the <varname>CONFLICTS</varname>
- variable. You can use shell globs like <literal>*</literal> and
- <literal>?</literal> here. Packages names should be
- enumerated the same way they appear in
- <filename>/var/db/pkg</filename>. Please make sure that
- <varname>CONFLICTS</varname> does not match this port's
- package itself, or else forcing its installation with
- <varname>FORCE_PKG_REGISTER</varname> will no longer work.
- </para>
+.if ${PORT_OPTIONS:MOPT2} || ${PORT_OPTIONS:MOPT1}
+CONFIGURE_ARGS+= --enable-opt2
+.else
+CONFIGURE_ARGS+= --disable-opt2
+.endif</programlisting>
- <note>
- <para><varname>CONFLICTS</varname> automatically sets
- <varname>IGNORE</varname>, which is more fully documented
- in <xref linkend="dads-noinstall"/>.</para>
- </note>
+ <example xml:id="options-implies-ex1">
+ <title xml:lang="en">Simple Use of
+ <varname><replaceable>OPT</replaceable>_IMPLIES</varname></title>
+
+ <para xml:lang="en">This port has a <literal>X11</literal> option, and a
+ <literal>GNOME</literal> option that needs the
+ <literal>X11</literal> option to be selected to
+ build.</para>
+
+ <programlisting>OPTIONS_DEFINE= X11 GNOME
+OPTIONS_DEFAULT= X11
+
+X11_USE= xorg=xi,xextproto
+GNOME_USE= gnome=gtk30
+GNOME_IMPLIES= X11</programlisting>
+ </example>
+ </sect3>
+
+ <sect3 xml:id="options-prevents">
+ <title xml:lang="en"><varname><replaceable>OPT</replaceable>_PREVENTS</varname>
+ and
+ <varname><replaceable>OPT</replaceable>_PREVENTS_MSG</varname></title>
+
+ <para xml:lang="en">Provides a way to add conflicts between options.</para>
- <para>When removing one of several conflicting ports, it is advisable to
- retain the <varname>CONFLICTS</varname> entries in those other ports
- for a few months to cater for users who only update once in a
- while.</para>
- </sect1>
+ <para xml:lang="en">When <replaceable>OPT</replaceable> is selected, all the
+ options listed in this variable must be un-selected. If
+ <varname><replaceable>OPT</replaceable>_PREVENTS_MSG</varname>
+ is also selected, its content will be shown, explaining why
+ they conflict. For example:</para>
+
+ <programlisting xml:lang="en">OPTIONS_DEFINE= OPT1 OPT2
+OPT1_PREVENTS= OPT2
+OPT1_PREVENTS_MSG= OPT1 and OPT2 enable conflicting options</programlisting>
+
+ <para xml:lang="en">Is roughly equivalent to:</para>
+
+ <programlisting xml:lang="en">OPTIONS_DEFINE= OPT1 OPT2
+
+.include &lt;bsd.port.options.mk&gt;
+
+.if ${PORT_OPTIONS:MOPT2} || ${PORT_OPTIONS:MOPT1}
+BROKEN= Option OPT1 conflicts with OPT2 (select only one)
+.endif</programlisting>
- <sect1 xml:id="install">
- <title>Installing files</title>
+ <para xml:lang="en">The only difference is that the first one will write an
+ error after running <command>make config</command>,
+ suggesting changing the selected options.</para>
- <sect2 xml:id="install-macros">
- <title>INSTALL_* macros</title>
+ <example xml:id="options-prevents-ex1">
+ <title xml:lang="en">Simple Use of
+ <varname><replaceable>OPT</replaceable>_PREVENTS</varname></title>
- <para>Do use the macros provided in <filename>bsd.port.mk</filename>
- to ensure correct modes and ownership of files in your own
- <buildtarget>*-install</buildtarget> targets.</para>
+ <para xml:lang="en">This port has <literal>X509</literal> and
+ <literal>SCTP</literal> options. Both options add
+ patches, but the patches conflict with each other, so they
+ cannot be selected at the same time.</para>
+
+ <programlisting>OPTIONS_DEFINE= X509 SCTP
+
+SCTP_PATCHFILES= ${PORTNAME}-6.8p1-sctp-2573.patch.gz:-p1
+SCTP_CONFIGURE_WITH= sctp
+
+X509_PATCH_SITES= http://www.roumenpetrov.info/openssh/x509/:x509
+X509_PATCHFILES= ${PORTNAME}-7.0p1+x509-8.5.diff.gz:-p1:x509
+X509_PREVENTS= SCTP
+X509_PREVENTS_MSG= X509 and SCTP patches conflict</programlisting>
+ </example>
+ </sect3>
+
+ <sect3 xml:id="options-vars">
+ <title xml:lang="en"><varname><replaceable>OPT</replaceable>_VARS</varname>
+ and
+ <varname><replaceable>OPT</replaceable>_VARS_OFF</varname></title>
+
+ <para xml:lang="en">Provides a generic way to set and append to
+ variables.</para>
+
+ <warning><para xml:lang="en">Before using
+ <varname><replaceable>OPT</replaceable>_VARS</varname> and
+ <varname><replaceable>OPT</replaceable>_VARS_OFF</varname>,
+ see if there is already a more specific helper available in
+ <xref linkend="options-variables"/>.</para></warning>
+
+ <para xml:lang="en">When option <replaceable>OPT</replaceable> is selected,
+ and <varname><replaceable>OPT</replaceable>_VARS</varname>
+ defined,
+ <literal><replaceable>key</replaceable>=<replaceable>value</replaceable></literal>
+ and
+ <literal><replaceable>key</replaceable>+=<replaceable>value</replaceable></literal>
+ pairs are evaluated from
+ <varname><replaceable>OPT</replaceable>_VARS</varname>. An
+ <literal>=</literal> cause the existing value of
+ <literal>KEY</literal> to be overwritten, an
+ <literal>+=</literal> appends to the value.
+ <varname><replaceable>OPT</replaceable>_VARS_OFF</varname>
+ works the same way, but when <literal>OPT</literal> is
+ <emphasis>not</emphasis> selected.</para>
+
+ <programlisting xml:lang="en">OPTIONS_DEFINE= OPT1 OPT2 OPT3
+OPT1_VARS= also_build+=bin1
+OPT2_VARS= also_build+=bin2
+OPT3_VARS= bin3_build=yes
+OPT3_VARS_OFF= bin3_build=no
+
+MAKE_ARGS= ALSO_BUILD="${ALSO_BUILD}" BIN3_BUILD="${BIN3_BUILD}"</programlisting>
+
+ <para xml:lang="en">is equivalent to:</para>
+
+ <programlisting xml:lang="en">OPTIONS_DEFINE= OPT1 OPT2
+
+MAKE_ARGS= ALSO_BUILD="${ALSO_BUILD}" BIN3_BUILD="${BIN3_BUILD}"
+
+.include &lt;bsd.port.options.mk&gt;
+
+.if ${PORT_OPTIONS:MOPT1}
+ALSO_BUILD+= bin1
+.endif
+
+.if ${PORT_OPTIONS:MOPT2}
+ALSO_BUILD+= bin2
+.endif
+
+.if ${PORT_OPTIONS:MOPT2}
+BIN3_BUILD= yes
+.else
+BIN3_BUILD= no
+.endif</programlisting>
+
+ <tip>
+ <para xml:lang="en">Values containing whitespace must be enclosed in
+ quotes:</para>
+
+ <programlisting xml:lang="en">OPT_VARS= foo="bar baz"</programlisting>
+
+ <para xml:lang="en">This is due to the way <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> variable expansion
+ deals with whitespace. When <literal>OPT_VARS= foo=bar
+ baz</literal> is expanded, the variable ends up
+ containing two strings, <literal>foo=bar</literal> and
+ <literal>baz</literal>. But the submitter probably
+ intended there to be only one string, <literal>foo=bar
+ baz</literal>. Quoting the value prevents whitespace
+ from being used as a delimiter.</para>
+ </tip>
+ </sect3>
+
+ <sect3 xml:id="options-dependencies">
+ <title xml:lang="en">Dependencies,
+ <varname><replaceable>OPT</replaceable>_<replaceable>DEPTYPE</replaceable></varname>
+ and
+ <varname><replaceable>OPT</replaceable>_<replaceable>DEPTYPE</replaceable>_OFF</varname></title>
+
+ <para xml:lang="en">For any of these dependency types:</para>
<itemizedlist>
<listitem>
- <para><varname>INSTALL_PROGRAM</varname> is a command to install
- binary executables.</para>
+ <para><varname>PKG_DEPENDS</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>EXTRACT_DEPENDS</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>PATCH_DEPENDS</varname></para>
</listitem>
<listitem>
- <para><varname>INSTALL_SCRIPT</varname> is a command to install
- executable scripts.</para>
+ <para><varname>FETCH_DEPENDS</varname></para>
</listitem>
<listitem>
- <para><varname>INSTALL_KLD</varname> is a command to install
- kernel loadable modules. Some architectures don't like it when
- the modules are stripped, therefor use this command instead
- of <varname>INSTALL_PROGRAM</varname>.</para>
+ <para><varname>BUILD_DEPENDS</varname></para>
</listitem>
<listitem>
- <para><varname>INSTALL_DATA</varname> is a command to install
- sharable data.</para>
+ <para xml:lang="en"><varname>LIB_DEPENDS</varname></para>
</listitem>
<listitem>
- <para><varname>INSTALL_MAN</varname> is a command to install
- manpages and other documentation (it does not compress
- anything).</para>
+ <para><varname>RUN_DEPENDS</varname></para>
</listitem>
</itemizedlist>
- <para>These are basically the <command>install</command> command with
- all the appropriate flags.</para>
- </sect2>
-
- <sect2 xml:id="install-strip">
- <title>Stripping Binaries</title>
-
- <para>Do not strip binaries manually unless you have to. All binaries
- should be stripped, but the <buildtarget>INSTALL_PROGRAM</buildtarget>
- macro will install and strip a binary at the same time (see the next
- section).</para>
-
- <para>If you need to strip a file, but do not wish to use the
- <varname>INSTALL_PROGRAM</varname> macro,
- <varname>${STRIP_CMD}</varname> will strip your program. This is
- typically done within the <literal>post-install</literal>
- target. For example:</para>
-
- <programlisting>post-install:
- ${STRIP_CMD} ${PREFIX}/bin/xdl</programlisting>
-
- <para>Use the &man.file.1; command on the installed executable to
- check whether the binary is stripped or not. If it does not say
- <literal>not stripped</literal>, it is stripped. Additionally,
- &man.strip.1; will not strip a previously stripped program; it
- will instead exit cleanly.</para>
- </sect2>
-
- <sect2 xml:id="install-copytree">
- <title>Installing a whole tree of files</title>
-
- <para>Sometimes, there is a need to install a big number of files,
- preserving their hierarchical organization, ie. copying over a whole
- directory tree from <varname>WRKSRC</varname> to a target directory
- under <varname>PREFIX</varname>.</para>
-
- <para>Two macros exists for this situation. The advantage of using
- these macros instead of <command>cp</command> is that they guarantee
- proper file ownership and permissions on target files. First macro,
- <varname>COPYTREE_BIN</varname>, will set all the installed files to
- be executable, thus being suitable for installing into
- <filename>PREFIX/bin</filename>. The second
- macro, <varname>COPYTREE_SHARE</varname>, does not set executable
- permissions on files, and is therefore suitable for installing files
- under <filename>PREFIX/share</filename>
- target.</para>
-
- <programlisting>post-install:
- ${MKDIR} ${EXAMPLESDIR}
- (cd ${WRKSRC}/examples/ &amp;&amp; ${COPYTREE_SHARE} \* ${EXAMPLESDIR})</programlisting>
-
- <para>This example will install the contents of
- <filename>examples</filename> directory in the vendor distfile to the
- proper examples location of your port.</para>
-
- <programlisting>post-install:
- ${MKDIR} ${DATADIR}/summer
- (cd ${WRKSRC}/temperatures/ &amp;&amp; ${COPYTREE_SHARE} "June July August" ${DATADIR}/summer/)</programlisting>
-
- <para>And this example will install the data of summer months to the
- <filename>summer</filename> subdirectory of a
- <filename>DATADIR</filename>.</para>
-
- <para>Additional <command>find</command> arguments can be passed via
- the third argument to the <varname>COPYTREE_*</varname> macros.
- For example, to install all files from the first example except
- Makefiles, one can use the following command.</para>
-
- <programlisting>post-install:
- ${MKDIR} ${EXAMPLESDIR}
- (cd ${WRKSRC}/examples/ &amp;&amp; \
- ${COPYTREE_SHARE} \* ${EXAMPLESDIR} "! -name Makefile")</programlisting>
-
- <para>Note that these macros does not add the installed files to
- <filename>pkg-plist</filename>. You still need to list them.</para>
- </sect2>
-
- <sect2 xml:id="install-documentation">
- <title>Install additional documentation</title>
-
- <para>If your software has some documentation other than the standard
- man and info pages that you think is useful for the user, install it
- under <filename>PREFIX/share/doc</filename>.
- This can be done, like the previous item, in the
- <buildtarget>post-install</buildtarget> target.</para>
-
- <para>Create a new directory for your port. The directory name should
- reflect what the port is. This usually means
- <varname>PORTNAME</varname>. However, if you
- think the user might want different versions of the port to be
- installed at the same time, you can use the whole
- <varname>PKGNAME</varname>.</para>
-
- <para>Make the installation dependent on the variable
- <varname>NOPORTDOCS</varname> so that users can disable it in
- <filename>/etc/make.conf</filename>, like this:</para>
-
- <programlisting>post-install:
-.if !defined(NOPORTDOCS)
- ${MKDIR} ${DOCSDIR}
- ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${DOCSDIR}
+ <para xml:lang="en">When option <replaceable>OPT</replaceable> is
+ selected, the value of
+ <varname><replaceable>OPT</replaceable>_<replaceable>DEPTYPE</replaceable></varname>,
+ if defined, is appended to
+ <literal><replaceable>DEPTYPE</replaceable></literal>.
+ <varname><replaceable>OPT</replaceable>_<replaceable>DEPTYPE</replaceable>_OFF</varname>
+ works the same, but when <literal>OPT</literal> is
+ <emphasis>not</emphasis>
+ selected. For example:</para>
+
+ <programlisting xml:lang="en">OPTIONS_DEFINE= OPT1
+OPT1_LIB_DEPENDS= liba.so:${PORTSDIR}/devel/a
+OPT1_LIB_DEPENDS_OFF= libb.so:${PORTSDIR}/devel/b</programlisting>
+
+ <para xml:lang="en">is equivalent to:</para>
+
+ <programlisting>OPTIONS_DEFINE= OPT1
+
+.include &lt;bsd.port.options.mk&gt;
+
+.if ${PORT_OPTIONS:MOPT1}
+LIB_DEPENDS+= liba.so:${PORTSDIR}/devel/a
+.else
+LIB_DEPENDS+= libb.so:${PORTSDIR}/devel/b
.endif</programlisting>
+ </sect3>
- <para>Here are some handy variables and how they are expanded
- by default when used
- in the <filename>Makefile</filename>:</para>
+ <sect3 xml:id="options-variables">
+ <title xml:lang="en">Generic Variables Replacement,
+ <varname><replaceable>OPT</replaceable>_<replaceable>VARIABLE</replaceable></varname>
+ and
+ <varname><replaceable>OPT</replaceable>_<replaceable>VARIABLE</replaceable>_OFF</varname></title>
+
+ <para xml:lang="en">For any of these variables:</para>
<itemizedlist>
<listitem>
- <para><varname>DATADIR</varname> gets expanded to
- <filename>PREFIX/share/PORTNAME</filename>.</para>
+ <para><varname>ALL_TARGET</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>BROKEN</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>CATEGORIES</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>CFLAGS</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>CONFIGURE_ENV</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>CONFLICTS</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>CONFLICTS_BUILD</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>CONFLICTS_INSTALL</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>CPPFLAGS</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>CXXFLAGS</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>DESKTOP_ENTRIES</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>DISTFILES</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>EXTRA_PATCHES</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>EXTRACT_ONLY</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>GH_ACCOUNT</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>GH_PROJECT</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>GH_TAGNAME</varname></para>
</listitem>
<listitem>
- <para><varname>DATADIR_REL</varname> gets expanded to
- <filename>share/PORTNAME</filename>.</para>
+ <para><varname>GH_TUPLE</varname></para>
</listitem>
<listitem>
- <para><varname>DOCSDIR</varname> gets expanded to
- <filename>PREFIX/share/doc/PORTNAME</filename>.</para>
+ <para><varname>IGNORE</varname></para>
</listitem>
<listitem>
- <para><varname>DOCSDIR_REL</varname> gets expanded to
- <filename>share/doc/PORTNAME</filename>.</para>
+ <para><varname>INFO</varname></para>
</listitem>
<listitem>
- <para><varname>EXAMPLESDIR</varname> gets expanded to
- <filename>PREFIX/share/examples/PORTNAME</filename>.</para>
+ <para><varname>INSTALL_TARGET</varname></para>
</listitem>
<listitem>
- <para><varname>EXAMPLESDIR_REL</varname> gets expanded to
- <filename>share/examples/PORTNAME</filename>.</para>
+ <para><varname>LDFLAGS</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>LIBS</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>MAKE_ARGS</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>MAKE_ENV</varname></para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><varname>PATCHFILES</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>PATCH_SITES</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>PLIST_DIRS</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>PLIST_DIRSTRY</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>PLIST_FILES</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>PLIST_SUB</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>PORTDOCS</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>PORTEXAMPLES</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>SUB_FILES</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>SUB_LIST</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>TEST_TARGET</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>USES</varname></para>
</listitem>
</itemizedlist>
- <note>
- <para><varname>NOPORTDOCS</varname> only controls additional
- documentation installed in <varname>DOCSDIR</varname>. It does not
- apply to standard man pages and info pages. Things installed in
- <varname>DATADIR</varname> and <varname>EXAMPLESDIR</varname>
- are controlled by <varname>NOPORTDATA</varname> and
- <varname>NOPORTEXAMPLES</varname>, respectively.</para>
- </note>
+ <para xml:lang="en">When option <replaceable>OPT</replaceable> is
+ selected, the value of
+ <varname><replaceable>OPT</replaceable>_<replaceable>ABOVEVARIABLE</replaceable></varname>,
+ if defined, is appended to
+ <literal><replaceable>ABOVEVARIABLE</replaceable></literal>.
+ <varname><replaceable>OPT</replaceable>_<replaceable>ABOVEVARIABLE</replaceable>_OFF</varname>
+ works the same way, but when <literal>OPT</literal> is
+ <emphasis>not</emphasis>
+ selected. For example:</para>
+
+ <programlisting>OPTIONS_DEFINE= OPT1
+OPT1_USES= gmake
+OPT1_CFLAGS_OFF= -DTEST</programlisting>
+
+ <para xml:lang="en">is equivalent to:</para>
- <para>These variables are exported to <varname>PLIST_SUB</varname>.
- Their values will appear there as pathnames relative to
- <filename>PREFIX</filename> if possible.
- That is, <filename>share/doc/PORTNAME</filename>
- will be substituted for <literal>%%DOCSDIR%%</literal>
- in the packing list by default, and so on.
- (See more on <filename>pkg-plist</filename> substitution
- <link linkend="plist-sub">here</link>.)</para>
-
- <para>All conditionally installed documentation files and directories should
- be included in <filename>pkg-plist</filename> with the
- <literal>%%PORTDOCS%%</literal> prefix, for example:</para>
-
- <programlisting>%%PORTDOCS%%%%DOCSDIR%%/AUTHORS
-%%PORTDOCS%%%%DOCSDIR%%/CONTACT
-%%PORTDOCS%%@dirrm %%DOCSDIR%%</programlisting>
-
- <para>As an alternative to enumerating the documentation files
- in <filename>pkg-plist</filename>, a port can set the variable
- <varname>PORTDOCS</varname> to a list of file names and shell
- glob patterns to add to the final packing list.
- The names will be relative to <varname>DOCSDIR</varname>.
- Therefore, a port that utilizes <varname>PORTDOCS</varname> and
- uses a non-default location for its documentation should set
- <varname>DOCSDIR</varname> accordingly.
- If a directory is listed in <varname>PORTDOCS</varname>
- or matched by a glob pattern from this variable,
- the entire subtree of contained files and directories will be
- registered in the final packing list. If <varname>NOPORTDOCS</varname>
- is defined then files and directories listed in
- <varname>PORTDOCS</varname> would not be installed and neither
- would be added to port packing list.
- Installing the documentation at <varname>PORTDOCS</varname>
- as shown above remains up to the port itself.
- A typical example of utilizing <varname>PORTDOCS</varname>
- looks as follows:</para>
-
- <programlisting>PORTDOCS= README.* ChangeLog docs/*</programlisting>
+ <programlisting>OPTIONS_DEFINE= OPT1
+
+.include &lt;bsd.port.options.mk&gt;
+
+.if ${PORT_OPTIONS:MOPT1}
+USES+= gmake
+.else
+CFLAGS+= -DTEST
+.endif</programlisting>
<note>
- <para>The equivalents of <varname>PORTDOCS</varname> for files
- installed under <varname>DATADIR</varname> and
- <varname>EXAMPLESDIR</varname> are <varname>PORTDATA</varname>
- and <varname>PORTEXAMPLES</varname>, respectively.</para>
-
- <para>You can also use the <filename>pkg-message</filename> file to
- display messages upon installation. See <link linkend="porting-message">the section on using
- <filename>pkg-message</filename></link> for details.
- The <filename>pkg-message</filename> file does not need to be
- added to <filename>pkg-plist</filename>.</para>
+ <para xml:lang="en">Some variables are not in this list, in particular
+ <varname>PKGNAMEPREFIX</varname> and
+ <varname>PKGNAMESUFFIX</varname>. This is intentional. A
+ port <emphasis>must not</emphasis> change its name when
+ its option set changes.</para>
</note>
- </sect2>
-
- <sect2 xml:id="install-subdirs">
- <title>Subdirectories under PREFIX</title>
-
- <para>Try to let the port put things in the right subdirectories of
- <varname>PREFIX</varname>. Some ports lump everything and put it in
- the subdirectory with the port's name, which is incorrect. Also,
- many ports put everything except binaries, header files and manual
- pages in a subdirectory of <filename>lib</filename>, which does
- not work well with the BSD paradigm. Many of the files should be
- moved to one of the following: <filename>etc</filename>
- (setup/configuration files), <filename>libexec</filename>
- (executables started internally), <filename>sbin</filename>
- (executables for superusers/managers), <filename>info</filename>
- (documentation for info browser) or <filename>share</filename>
- (architecture independent files). See &man.hier.7; for details;
- the rules governing
- <filename>/usr</filename> pretty much apply to
- <filename>/usr/local</filename> too. The exception are ports
- dealing with USENET <quote>news</quote>. They may use
- <filename>PREFIX/news</filename> as a destination
- for their files.</para>
- </sect2>
-
- </sect1>
-
- </chapter>
-
- <chapter xml:id="special">
- <title>Special considerations</title>
-
- <para>There are some more things you have to take into account when you
- create a port. This section explains the most common of those.</para>
-
- <sect1 xml:id="porting-shlibs">
- <title>Shared Libraries</title>
-
- <para>If your port installs one or more shared libraries, define a
- <varname>USE_LDCONFIG</varname> make variable, which will instruct
- a <filename>bsd.port.mk</filename> to run
- <literal>&dollar;{LDCONFIG} -m</literal> on the directory where the
- new library is installed (usually
- <filename>PREFIX/lib</filename>) during
- <buildtarget>post-install</buildtarget> target to register it into the
- shared library cache. This variable, when defined, will also
- facilitate addition of an appropriate
- <literal>@exec /sbin/ldconfig -m</literal> and
- <literal>@unexec /sbin/ldconfig -R</literal> pair into your
- <filename>pkg-plist</filename> file, so that a user who installed
- the package can start using the shared library immediately and
- de-installation will not cause the system to still believe the
- library is there.</para>
-
- <programlisting>USE_LDCONFIG= yes</programlisting>
-
- <para>If you need, you can override the default directory
- by setting the <varname>USE_LDCONFIG</varname>
- value to a list of directories into which
- shared libraries are to be installed. For example if your port
- installs shared libraries into
- <filename>PREFIX/lib/foo</filename> and
- <filename>PREFIX/lib/bar</filename> directories
- you could use the following in your
- <filename>Makefile</filename>:</para>
-
- <programlisting>USE_LDCONFIG= ${PREFIX}/lib/foo ${PREFIX}/lib/bar</programlisting>
-
- <para>Please
- double-check, often this is not necessary at all or can be avoided
- through <literal>-rpath</literal> or setting <envar>LD_RUN_PATH</envar>
- during linking (see <package>lang/moscow_ml</package>
- for an example), or through a shell-wrapper which sets
- <varname>LD_LIBRARY_PATH</varname> before invoking the binary, like
- <package>www/mozilla</package> does.</para>
-
- <para>When installing 32-bit libraries on 64-bit system, use
- <varname>USE_LDCONFIG32</varname> instead.</para>
-
- <para>Try to keep shared library version numbers in the
- <filename>libfoo.so.0</filename> format. Our runtime linker only
- cares for the major (first) number.</para>
-
- <para>When the major library version number increments in the update
- to the new port version, all other ports that link to the affected
- library should have their <varname>PORTREVISION</varname> incremented,
- to force recompilation with the new library version.</para>
-
- </sect1>
-
- <sect1 xml:id="porting-restrictions">
- <title>Ports with distribution restrictions</title>
-
- <para>Licenses vary, and some of them place restrictions on how the
- application can be packaged, whether it can be sold for profit, and so
- on.</para>
- <important>
- <para>It is your responsibility as a porter to read the licensing
- terms of the software and make sure that the FreeBSD project will
- not be held accountable for violating them by redistributing the
- source or compiled binaries either via FTP/HTTP or CD-ROM. If in doubt,
- please contact the &a.ports;.</para>
- </important>
+ <warning>
+ <para xml:lang="en">Some of these variables, at least
+ <varname>ALL_TARGET</varname> and
+ <varname>INSTALL_TARGET</varname>, have their default
+ values set <emphasis>after</emphasis> the options are
+ processed.</para>
- <para>In situations like this, the variables described in the following
- sections can be set.</para>
-
- <sect2>
- <title><varname>NO_PACKAGE</varname></title>
-
- <para>This variable indicates that we may not generate a binary
- package of the application. For instance, the license may
- disallow binary redistribution, or it may prohibit distribution
- of packages created from patched sources.</para>
-
- <para>However, the port's <varname>DISTFILES</varname> may be
- freely mirrored on FTP/HTTP. They may also be distributed on
- a CD-ROM (or similar media) unless <varname>NO_CDROM</varname>
- is set as well.</para>
-
- <para><varname>NO_PACKAGE</varname> should also be used if the binary
- package is not generally useful, and the application should always
- be compiled from the source code. For example, if the application
- has configuration information that is site specific hard coded in to
- it at compile time, set <varname>NO_PACKAGE</varname>.</para>
-
- <para><varname>NO_PACKAGE</varname> should be set to a string
- describing the reason why the package should not be
- generated.</para>
- </sect2>
-
- <sect2>
- <title><varname>NO_CDROM</varname></title>
-
- <para>This variable alone indicates that, although we are allowed
- to generate binary packages, we may put neither those packages
- nor the port's <varname>DISTFILES</varname> onto a CD-ROM (or
- similar media) for resale. However, the binary packages and
- the port's <varname>DISTFILES</varname> will still be available
- via FTP/HTTP.</para>
-
- <para>If this variable is set along with
- <varname>NO_PACKAGE</varname>, then only the port's
- <varname>DISTFILES</varname> will be available, and only via
- FTP/HTTP.</para>
-
- <para><varname>NO_CDROM</varname> should be set to a string
- describing the reason why the port cannot be redistributed
- on CD-ROM. For instance, this should be used if the port's license
- is for <quote>non-commercial</quote> use only.</para>
- </sect2>
-
- <sect2>
- <title><varname>NOFETCHFILES</varname></title>
-
- <para>Files defined in the <varname>NOFETCHFILES</varname>
- variable are not fetchable from any of the
- <varname>MASTER_SITES</varname>. An example of such a
- file is when the file is supplied on CD-ROM by the
- vendor.</para>
-
- <para>Tools which check for the availability of these files
- on the <varname>MASTER_SITES</varname> should ignore these
- files and not report about them.</para>
- </sect2>
-
- <sect2>
- <title><varname>RESTRICTED</varname></title>
-
- <para>Set this variable alone if the application's license permits
- neither mirroring the application's <varname>DISTFILES</varname>
- nor distributing the binary package in any way.</para>
-
- <para><varname>NO_CDROM</varname> or <varname>NO_PACKAGE</varname>
- should not be set along with <varname>RESTRICTED</varname>
- since the latter variable implies the former ones.</para>
-
- <para><varname>RESTRICTED</varname> should be set to a string
- describing the reason why the port cannot be redistributed.
- Typically, this indicates that the port contains proprietary
- software and that the user will need to manually download the
- <varname>DISTFILES</varname>, possibly after registering for the
- software or agreeing to accept the terms of an
- <acronym>EULA</acronym>.</para>
- </sect2>
-
- <sect2>
- <title><varname>RESTRICTED_FILES</varname></title>
-
- <para>When <varname>RESTRICTED</varname> or <varname>NO_CDROM</varname>
- is set, this variable defaults to <literal>${DISTFILES}
- ${PATCHFILES}</literal>, otherwise it is empty. If only some of the
- distribution files are restricted, then set this variable to list
- them.</para>
-
- <para>Note that the port committer should add an entry to
- <filename>/usr/ports/LEGAL</filename> for every listed distribution
- file, describing exactly what the restriction entails.</para>
- </sect2>
- </sect1>
-
- <sect1 xml:id="building">
- <title>Building mechanisms</title>
-
- <sect2 xml:id="using-make">
- <title><command>make</command>, <command>gmake</command>, and
- <command>imake</command></title>
-
- <para>If your port uses <application>GNU make</application>, set
- <literal>USE_GMAKE=yes</literal>.</para>
-
- <table frame="none">
- <title>Variables for ports related to gmake</title>
+ <para xml:lang="en">With these lines in the
+ <filename>Makefile</filename>:</para>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Variable</entry>
+ <programlisting>ALL_TARGET= all
- <entry>Means</entry>
- </row>
- </thead>
+DOCS_ALL_TARGET= doc</programlisting>
- <tbody>
- <row>
- <entry><varname>USE_GMAKE</varname></entry>
+ <para xml:lang="en">If the <literal>DOCS</literal> option is enabled,
+ <varname>ALL_TARGET</varname> will have a final value of
+ <literal>all doc</literal>; if the option is disabled, it
+ would have a value of <literal>all</literal>.</para>
- <entry>The port requires <command>gmake</command> to
- build.</entry>
- </row>
+ <para xml:lang="en">With only the options helper line in the
+ <filename>Makefile</filename>:</para>
- <row>
- <entry><varname>GMAKE</varname></entry>
+ <programlisting>DOCS_ALL_TARGET= doc</programlisting>
- <entry>The full path for <command>gmake</command> if it is not
- in the <envar>PATH</envar>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <para xml:lang="en">If the <literal>DOCS</literal> option is enabled,
+ <varname>ALL_TARGET</varname> will have a final value of
+ <literal>doc</literal>; if the option is disabled, it
+ would have a value of <literal>all</literal>.</para>
+ </warning>
- <para>If your port is an X application that creates
- <filename>Makefile</filename> files from
- <filename>Imakefile</filename> files using
- <application>imake</application>, then set
- <literal>USE_IMAKE=yes</literal>. This will cause the
- configure stage to automatically do an <command>xmkmf -a</command>.
- If the <option>-a</option> flag is a problem for your port, set
- <literal>XMKMF=xmkmf</literal>. If the port uses
- <application>imake</application> but does not understand the
- <buildtarget>install.man</buildtarget> target,
- <literal>NO_INSTALL_MANPAGES=yes</literal> should be set.</para>
-
- <para>If your port's source <filename>Makefile</filename> has
- something else than <buildtarget>all</buildtarget> as the main build
- target, set <varname>ALL_TARGET</varname> accordingly. Same goes
- for <buildtarget>install</buildtarget> and
- <varname>INSTALL_TARGET</varname>.</para>
-
- </sect2>
-
- <sect2 xml:id="using-configure">
- <title><command>configure</command> script</title>
-
- <para>If your port uses the <command>configure</command> script to
- generate <filename>Makefile</filename> files from
- <filename>Makefile.in</filename> files, set
- <literal>GNU_CONFIGURE=yes</literal>. If you want to give extra
- arguments to the <command>configure</command> script (the default
- argument is <literal>--prefix=&dollar;{PREFIX}
- --infodir=&dollar;{PREFIX}/&dollar;{INFO_PATH}
- --mandir=&dollar;{MANPREFIX}/man
- --build=&dollar;{CONFIGURE_TARGET}</literal>), set those
- extra arguments in <varname>CONFIGURE_ARGS</varname>. Extra
- environment variables can be passed using
- <varname>CONFIGURE_ENV</varname> variable.</para>
-
- <table frame="none">
- <title>Variables for ports that use configure</title>
+ </sect3>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Variable</entry>
+ <sect3 xml:id="options-targets">
+ <title xml:lang="en">Additional Build Targets,
+ <buildtarget xml:lang="en"><replaceable>TARGET</replaceable>-<replaceable>OPT</replaceable>-on</buildtarget>
+ and
+ <buildtarget xml:lang="en"><replaceable>TARGET</replaceable>-<replaceable>OPT</replaceable>-on</buildtarget></title>
- <entry>Means</entry>
- </row>
- </thead>
+ <para xml:lang="en">These <filename>Makefile</filename> targets can accept
+ optional extra build targets:</para>
- <tbody>
- <row>
- <entry><varname>GNU_CONFIGURE</varname></entry>
+ <itemizedlist>
+ <listitem>
+ <para><buildtarget>pre-fetch</buildtarget></para>
+ </listitem>
- <entry>The port uses <command>configure</command> script to
- prepare build.</entry>
- </row>
+ <listitem>
+ <para><buildtarget xml:lang="en">do-fetch</buildtarget></para>
+ </listitem>
- <row>
- <entry><varname>HAS_CONFIGURE</varname></entry>
+ <listitem>
+ <para><buildtarget>post-fetch</buildtarget></para>
+ </listitem>
- <entry>Same as <varname>GNU_CONFIGURE</varname>, except
- default configure target is not added to
- <varname>CONFIGURE_ARGS</varname>.</entry>
- </row>
+ <listitem>
+ <para><buildtarget>pre-extract</buildtarget></para>
+ </listitem>
- <row>
- <entry><varname>CONFIGURE_ARGS</varname></entry>
+ <listitem>
+ <para><buildtarget xml:lang="en">do-extract</buildtarget></para>
+ </listitem>
- <entry>Additional arguments passed to
- <command>configure</command> script.</entry>
- </row>
+ <listitem>
+ <para><buildtarget xml:lang="en">post-extract</buildtarget></para>
+ </listitem>
- <row>
- <entry><varname>CONFIGURE_ENV</varname></entry>
+ <listitem>
+ <para><buildtarget>pre-patch</buildtarget></para>
+ </listitem>
- <entry>Additional environment variables to be set
- for <command>configure</command> script run.</entry>
- </row>
+ <listitem>
+ <para><buildtarget>do-patch</buildtarget></para>
+ </listitem>
- <row>
- <entry><varname>CONFIGURE_TARGET</varname></entry>
+ <listitem>
+ <para><buildtarget>post-patch</buildtarget></para>
+ </listitem>
- <entry>Override default configure target. Default value is
- <literal>&dollar;{MACHINE_ARCH}-portbld-freebsd&dollar;{OSREL}</literal>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </sect2>
+ <listitem>
+ <para><buildtarget>pre-configure</buildtarget></para>
+ </listitem>
- <sect2 xml:id="using-scons">
- <title>Using <command>scons</command></title>
+ <listitem>
+ <para><buildtarget>do-configure</buildtarget></para>
+ </listitem>
- <para>If your port uses <application>SCons</application>, define
- <literal>USE_SCONS=yes</literal>.</para>
+ <listitem>
+ <para><buildtarget>post-configure</buildtarget></para>
+ </listitem>
- <table frame="none">
- <title>Variables for ports that use <command>scons</command></title>
+ <listitem>
+ <para><buildtarget>pre-build</buildtarget></para>
+ </listitem>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Variable</entry>
+ <listitem>
+ <para><buildtarget>do-build</buildtarget></para>
+ </listitem>
- <entry>Means</entry>
- </row>
- </thead>
+ <listitem>
+ <para><buildtarget>post-build</buildtarget></para>
+ </listitem>
- <tbody>
- <row>
- <entry><varname>SCONS_ARGS</varname></entry>
+ <listitem>
+ <para><buildtarget>pre-install</buildtarget></para>
+ </listitem>
- <entry>Port specific SCons flags passed to the SCons
- environment.</entry>
- </row>
+ <listitem>
+ <para><buildtarget>do-install</buildtarget></para>
+ </listitem>
- <row>
- <entry><varname>SCONS_BUILDENV</varname></entry>
+ <listitem>
+ <para><buildtarget>post-install</buildtarget></para>
+ </listitem>
- <entry>Variables to be set in system environment.</entry>
- </row>
+ <listitem>
+ <para><buildtarget>post-stage</buildtarget></para>
+ </listitem>
- <row>
- <entry><varname>SCONS_ENV</varname></entry>
+ <listitem>
+ <para><buildtarget>pre-package</buildtarget></para>
+ </listitem>
- <entry>Variables to be set in SCons environment.</entry>
- </row>
+ <listitem>
+ <para><buildtarget>do-package</buildtarget></para>
+ </listitem>
- <row>
- <entry><varname>SCONS_TARGET</varname></entry>
+ <listitem>
+ <para><buildtarget>post-package</buildtarget></para>
+ </listitem>
+ </itemizedlist>
- <entry>Last argument passed to SCons, similar to
- <varname>MAKE_TARGET</varname>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </sect2>
- </sect1>
-
- <sect1 xml:id="using-autotools">
- <title>Using GNU autotools</title>
-
- <sect2 xml:id="using-autotools-introduction">
- <title>Introduction</title>
-
- <para>The various GNU autotools provide an abstraction mechanism for
- building a piece of software over a wide variety of operating
- systems and machine architectures. Within the Ports Collection,
- an individual port can make use of these tools via a simple
- construct:</para>
+ <para xml:lang="en">When option <replaceable>OPT</replaceable> is
+ selected, the target
+ <buildtarget xml:lang="en"><replaceable>TARGET</replaceable>-<replaceable>OPT</replaceable>-on</buildtarget>,
+ if defined, is executed after
+ <buildtarget xml:lang="en"><replaceable>TARGET</replaceable></buildtarget>.
+ <buildtarget xml:lang="en"><replaceable>TARGET</replaceable>-<replaceable>OPT</replaceable>-off</buildtarget>
+ works the same way, but when <literal>OPT</literal> is
+ <emphasis>not</emphasis> selected. For example:</para>
- <programlisting>USE_AUTOTOOLS= <replaceable>tool</replaceable>:<replaceable>version</replaceable>[:<replaceable>operation</replaceable>] ...</programlisting>
+ <programlisting>OPTIONS_DEFINE= OPT1
- <para>At the time of writing, <replaceable>tool</replaceable> can be
- one of <literal>libtool</literal>, <literal>libltdl</literal>,
- <literal>autoconf</literal>, <literal>autoheader</literal>,
- <literal>automake</literal> or <literal>aclocal</literal>.</para>
+post-patch-OPT1-on:
+ @${REINPLACE_CMD} -e '/opt1/d' ${WRKSRC}/Makefile
+post-patch-OPT1-off:
+ @${REINPLACE_CMD} -e '/opt1/s|/usr/bin/|${LOCALBASE}/bin/|' ${WRKSRC}/Makefile</programlisting>
- <para><replaceable>version</replaceable> specifies the particular
- tool revision to be used (see
- <literal>devel/{automake,autoconf,libtool}[0-9]+</literal> for
- valid versions).</para>
-
- <para><replaceable>operation</replaceable> is an optional extension
- to modify how the tool is used.</para>
+ <para xml:lang="en">is equivalent to:</para>
- <para>Multiple tools can be specified at once, either by including
- them all on a single line, or using the <literal>+=</literal>
- Makefile construct.</para>
+ <programlisting>OPTIONS_DEFINE= OPT1
- <para>Finally, there is the special tool, called
- <literal>autotools</literal>, which is a convenience function
- to bring in all available versions of the autotools to allow
- for cross-development work. This can also be accomplished
- by installing the <literal>devel/autotools</literal> port.</para>
-
- </sect2>
-
- <sect2 xml:id="using-libtool">
- <title><command>libtool</command></title>
-
- <para>Shared libraries using the GNU building framework usually use
- <command>libtool</command> to adjust the compilation and
- installation of shared libraries to match the specifics of the
- underlying operating system. The usual practice is to use copy of
- <command>libtool</command> bundled with the application. In case
- you need to use external <command>libtool</command>, you can use
- the version provided by The Ports Collection:</para>
-
- <programlisting>USE_AUTOTOOLS= libtool:<replaceable>version</replaceable>[:env]</programlisting>
-
- <para>With no additional operations,
- <literal>libtool:version</literal> tells
- the building framework to patch the configure script with the
- system-installed copy of <command>libtool</command>.
- The <varname>GNU_CONFIGURE</varname> is implied.
- Further, a number of make and shell
- variables will be assigned for onward use by the port. See
- <filename>bsd.autotools.mk</filename> for details.</para>
-
- <para>With the <literal>:env</literal> operation, only the
- environment will be set up.</para>
-
- <para>Finally, <varname>LIBTOOLFLAGS</varname> and
- <varname>LIBTOOLFILES</varname> can be optionally set to override
- the most likely arguments to, and files patched by,
- <command>libtool</command>. Most ports are unlikely to need this.
- See <filename>bsd.autotools.mk</filename> for further
- details.</para>
-
- </sect2>
-
- <sect2 xml:id="using-libltdl">
- <title><command>libltdl</command></title>
-
- <para>Some ports make use of the <command>libltdl</command> library
- package, which is part of the <command>libtool</command> suite.
- Use of this library does not automatically necessitate the use of
- <command>libtool</command> itself, so a separate construct is
- provided.</para>
-
- <programlisting>USE_AUTOTOOLS= libltdl:<replaceable>version</replaceable></programlisting>
-
- <para>Currently, all this does is to bring in a
- <varname>LIB_DEPENDS</varname> on the appropriate
- <command>libltdl</command> port, and is provided as a convenience
- function to help eliminate any dependencies on the autotools ports
- outside of the <varname>USE_AUTOTOOLS</varname> framework. There
- are no optional operations for this tool.</para>
-
- </sect2>
-
- <sect2 xml:id="using-autoconf">
- <title><command>autoconf</command> and
- <command>autoheader</command></title>
-
- <para>Some ports do not contain a configure script, but do contain an
- autoconf template in the <filename>configure.ac</filename> file.
- You can use the following assignments to let
- <command>autoconf</command> create the configure script, and also
- have <command>autoheader</command> create template headers for use
- by the configure script.</para>
-
- <programlisting>USE_AUTOTOOLS= autoconf:<replaceable>version</replaceable>[:env]</programlisting>
-
- <para>and</para>
-
- <programlisting>USE_AUTOTOOLS= autoheader:<replaceable>version</replaceable></programlisting>
-
- <para>which also implies the use of
- <literal>autoconf:version</literal>.</para>
-
- <para>Similarly to <command>libtool</command>, the inclusion of the
- optional <literal>:env</literal> operation simply sets up the
- environment for further use. Without it, patching and
- reconfiguration of the port is carried out.</para>
-
- <para>The additional optional variables
- <varname>AUTOCONF_ARGS</varname> and
- <varname>AUTOHEADER_ARGS</varname> can be overridden by the port
- <filename>Makefile</filename> if specifically requested. As with
- the <command>libtool</command> equivalents, most ports are unlikely
- to need this.</para>
-
- </sect2>
-
- <sect2 xml:id="using-automake">
- <title><command>automake</command> and
- <command>aclocal</command></title>
-
- <para>Some packages only contain <filename>Makefile.am</filename>
- files. These have to be converted into
- <filename>Makefile.in</filename> files using
- <command>automake</command>, and the further processed by
- <command>configure</command> to generate an actual
- <filename>Makefile</filename>.</para>
-
- <para>Similarly, packages occasionally do not ship with included
- <filename>aclocal.m4</filename> files, again required to build the
- software. This can be achieved with <command>aclocal</command>,
- which scans <filename>configure.ac</filename> or
- <filename>configure.in</filename>.</para>
-
- <para><command>aclocal</command> has a similar relationship to
- <command>automake</command> as <command>autoheader</command> does
- to <command>autoconf</command>, described in the previous section.
- <command>aclocal</command> implies the use of
- <command>automake</command>, thus we have:</para>
-
- <programlisting>USE_AUTOTOOLS= automake:<replaceable>version</replaceable>[:<replaceable>env</replaceable>]</programlisting>
-
- <para>and</para>
-
- <programlisting>USE_AUTOTOOLS= aclocal:<replaceable>version</replaceable></programlisting>
-
- <para>which also implies the use of
- <literal>automake:version</literal>.</para>
-
- <para>Similarly to <command>libtool</command> and
- <command>autoconf</command>, the inclusion of the optional
- <literal>:env</literal> operation simply sets up the environment
- for further use. Without it, reconfiguration of the port is
- carried out.</para>
-
- <para>As with
- <command>autoconf</command> and <command>autoheader</command>, both
- <command>automake</command> and <command>aclocal</command> have
- optional argument variables, <varname>AUTOMAKE_ARGS</varname> and
- <varname>ACLOCAL_ARGS</varname> respectively, which may be
- overriden by the port <filename>Makefile</filename> if
- required.</para>
-
- </sect2>
- </sect1>
-
- <sect1 xml:id="using-gettext">
- <title>Using GNU <literal>gettext</literal></title>
-
- <sect2>
- <title>Basic usage</title>
-
- <para>If your port requires <literal>gettext</literal>,
- just set <varname>USE_GETTEXT</varname> to <literal>yes</literal>,
- and your port will grow the dependency on <package>devel/gettext</package>. The value of
- <varname>USE_GETTEXT</varname> can also specify the required
- version of the <literal>libintl</literal> library, the basic
- part of <literal>gettext</literal>, but using this
- feature is <emphasis>strongly discouraged</emphasis>:
- Your port should work with just the current version of
- <package>devel/gettext</package>.</para>
-
- <para>A rather common case is a port using
- <literal>gettext</literal> and <command>configure</command>.
- Generally, GNU <command>configure</command> should be
- able to locate <literal>gettext</literal> automatically.
- If it ever fails to, hints at the location of
- <literal>gettext</literal> can be passed in
- <envar>CPPFLAGS</envar> and <envar>LDFLAGS</envar> as
- follows:</para>
-
- <programlisting>USE_GETTEXT= yes
-CPPFLAGS+= -I${LOCALBASE}/include
-LDFLAGS+= -L${LOCALBASE}/lib
-
-GNU_CONFIGURE= yes
-CONFIGURE_ENV= CPPFLAGS="${CPPFLAGS}" \
- LDFLAGS="${LDFLAGS}"</programlisting>
-
- <para>Of course, the code can be more compact if there are no
- more flags to pass to <command>configure</command>:</para>
-
- <programlisting>USE_GETTEXT= yes
-GNU_CONFIGURE= yes
-CONFIGURE_ENV= CPPFLAGS="-I${LOCALBASE}/include" \
- LDFLAGS="-L${LOCALBASE}/lib"</programlisting>
-
- </sect2>
-
- <sect2>
- <title>Optional usage</title>
-
- <para>Some software products allow for disabling NLS,
- e.g., through passing <option>--disable-nls</option> to
- <command>configure</command>. In that case, your port
- should use <literal>gettext</literal> conditionally,
- depending on the status of <link linkend="knobs-without-nls"><varname>WITHOUT_NLS</varname></link>.
- For ports of low to medium complexity, you can rely on the
- following idiom:</para>
-
- <programlisting>GNU_CONFIGURE= yes
-
-.if !defined(WITHOUT_NLS)
-USE_GETTEXT= yes
-PLIST_SUB+= NLS=""
+.include &lt;bsd.port.options.mk&gt;
+
+post-patch:
+.if ${PORT_OPTIONS:MOPT1}
+ @${REINPLACE_CMD} -e '/opt1/d' ${WRKSRC}/Makefile
.else
-CONFIGURE_ARGS+= --disable-nls
-PLIST_SUB+= NLS="@comment "
+ @${REINPLACE_CMD} -e '/opt1/s|/usr/bin/|${LOCALBASE}/bin/|' ${WRKSRC}/Makefile
.endif</programlisting>
+ </sect3>
+ </sect2>
+ </sect1>
- <para>The next item on your to-do list is to arrange so that
- the message catalog files are included in the packing list
- conditionally. The <filename>Makefile</filename> part of
- this task is already provided by the idiom. It is explained
- in the section on <link linkend="plist-sub">advanced
- <filename>pkg-plist</filename> practices</link>. In a
- nutshell, each occurrence of <literal>%%NLS%%</literal> in
- <filename>pkg-plist</filename> will be replaced by
- <quote><literal>@comment&nbsp;</literal></quote> if NLS is
- disabled, or by a null string if NLS is enabled. Consequently,
- the lines prefixed by <literal>%%NLS%%</literal> will become
- mere comments in the final packing list if NLS is off;
- otherwise the prefix will be just left out. All you need
- to do now is insert <literal>%%NLS%%</literal> before each
- path to a message catalog file in <filename>pkg-plist</filename>.
- For example:</para>
-
- <programlisting>%%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo
-%%NLS%%share/locale/no/LC_MESSAGES/foobar.mo</programlisting>
+ <sect1 xml:id="makefile-wrkdir">
+ <title xml:lang="en">Specifying the Working Directory</title>
+
+ <para xml:lang="en">Each port is extracted into a working directory, which must
+ be writable. The ports system defaults to having
+ <varname>DISTFILES</varname> unpack in to a directory called
+ <literal>${DISTNAME}</literal>. In other words, if the
+ <filename>Makefile</filename> has:</para>
+
+ <programlisting xml:lang="en">PORTNAME= foo
+PORTVERSION= 1.0</programlisting>
+
+ <para xml:lang="en">then the port's distribution files contain a top-level
+ directory, <filename>foo-1.0</filename>, and the rest of the
+ files are located under that directory.</para>
+
+ <para xml:lang="en">A number of variables can be overridden if that is
+ not the case.</para>
+
+ <sect2 xml:id="makefile-wrksrc">
+ <title><varname>WRKSRC</varname></title>
+
+ <para xml:lang="en">The variable lists the name of the directory that is
+ created when the application's distfiles are extracted. If
+ our previous example extracted into a directory called
+ <filename>foo</filename> (and not
+ <filename>foo-1.0</filename>) write:</para>
+
+ <programlisting>WRKSRC= ${WRKDIR}/foo</programlisting>
+
+ <para xml:lang="en">or possibly</para>
+
+ <programlisting>WRKSRC= ${WRKDIR}/${PORTNAME}</programlisting>
+ </sect2>
+
+ <sect2 xml:id="makefile-wrksrc_subdir">
+ <title xml:lang="en"><varname>WRKSRC_SUBDIR</varname></title>
+
+ <para xml:lang="en">If the source files needed for the port are in a
+ subdirectory of the extracted distribution file, set
+ <varname>WRKSRC_SUBDIR</varname> to that directory.</para>
- <para>In high complexity cases, you may need to use more advanced
- techniques than the recipe given here, such as <link linkend="plist-dynamic">dynamic packing list generation</link>.</para>
- </sect2>
-
- <sect2>
- <title>Handling message catalog directories</title>
-
- <para>There is a point to note about installing message catalog
- files. The target directories for them, which reside under
- <filename>LOCALBASE/share/locale</filename>,
- should rarely be created and removed by your port. The
- most popular languages have their respective directories
- listed in <filename>/etc/mtree/BSD.local.dist</filename>;
- that is, they are a part of the base system. The directories
- for many other languages are governed by the <package>devel/gettext</package> port. You may want
- to consult its <filename>pkg-plist</filename> and see whether
- your port is going to install a message catalog file for a
- unique language.</para>
- </sect2>
- </sect1>
-
- <sect1 xml:id="using-perl">
- <title>Using <literal>perl</literal></title>
-
- <para>If <varname>MASTER_SITES</varname> is set to
- <varname>MASTER_SITE_PERL_CPAN</varname>, then preferred value of
- <varname>MASTER_SITE_SUBDIR</varname> is top-level hierarchy name.
- For example, the recommend value for <literal>p5-Module-Name</literal>
- is <literal>Module</literal>. The top-level hierarchy can be examined
- at <link xlink:href="http://cpan.org/modules/by-module/">cpan.org</link>.
- This keeps the port working when the author of the module
- changes.</para>
-
- <para>The exception to this rule is when the relevant directory does not
- exist or the distfile does not exist in the directory. In such case, using
- author's id as <varname>MASTER_SITE_SUBDIR</varname> is allowed.</para>
-
- <para>All of the tunable knobs below accept both <literal>YES</literal>
- and a version string, like <literal>5.8.0+</literal>. Using
- <literal>YES</literal> means that the port can be used with all
- of the supported <application>Perl</application> versions. If a port
- only works with specific versions of <application>Perl</application>,
- it can be indicated with a version string, specifying a minimal version
- (e.g. <literal>5.7.3+</literal>), a maximal version (e.g.
- <literal>5.8.0-</literal>) or an exact version (e.g.
- <literal>5.8.3</literal>).</para>
-
- <table frame="none">
- <title>Variables for ports that use <literal>perl</literal></title>
+ <programlisting>WRKSRC_SUBDIR= src</programlisting>
+ </sect2>
+
+ <sect2 xml:id="makefile-no_wrksubdir">
+ <title><varname>NO_WRKSUBDIR</varname></title>
+
+ <para xml:lang="en">If the port does not extract in to a subdirectory at all,
+ then set <varname>NO_WRKSUBDIR</varname> to
+ indicate that.</para>
+
+ <programlisting>NO_WRKSUBDIR= yes</programlisting>
+
+ <note>
+ <para xml:lang="en">Because <varname>WRKDIR</varname> is the only directory
+ that is supposed to be writable during the build, and is
+ used to store many files recording the status of the build,
+ the port's extraction will be forced into a
+ subdirectory.</para>
+ </note>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="conflicts">
+ <title xml:lang="en">Conflict Handling</title>
+
+ <para xml:lang="en">There are three different variables to register a conflict
+ between packages and ports: <varname>CONFLICTS</varname>,
+ <varname>CONFLICTS_INSTALL</varname> and
+ <varname>CONFLICTS_BUILD</varname>.</para>
+
+ <note>
+ <para xml:lang="en">The conflict variables automatically set the variable
+ <varname>IGNORE</varname>, which is more fully documented in
+ <xref linkend="dads-noinstall"/>.</para>
+ </note>
+
+ <para xml:lang="en">When removing one of several conflicting ports, it is
+ advisable to retain <varname>CONFLICTS</varname> in
+ those other ports for a few months to cater for users who only
+ update once in a while.</para>
+
+ <sect2 xml:id="conflicts-conflicts_install">
+ <title><varname>CONFLICTS_INSTALL</varname></title>
+
+ <para xml:lang="en">If the package cannot coexist with other packages
+ (because of file conflicts, runtime incompatibilities, etc.),
+ list the other package names in
+ <varname>CONFLICTS_INSTALL</varname>. Use
+ shell globs like <literal>*</literal> and <literal>?</literal>
+ here. Enumerate package names in there, not port names or
+ origins. Please make sure
+ that <varname>CONFLICTS_INSTALL</varname> does not match this
+ port's package itself. Otherwise enforcing its installation
+ with <varname>FORCE_PKG_REGISTER</varname> will no longer
+ work. <varname>CONFLICTS_INSTALL</varname> check is done
+ after the build stage and prior to the install stage.</para>
+ </sect2>
+
+ <sect2 xml:id="conflicts-conflicts_build">
+ <title><varname>CONFLICTS_BUILD</varname></title>
+
+ <para xml:lang="en">If the port cannot be built when other specific ports are
+ already installed, list the other port names in
+ <varname>CONFLICTS_BUILD</varname>. Use
+ shell globs like <literal>*</literal> and <literal>?</literal>
+ here. Use package names, not port names or origins.
+ <varname>CONFLICTS_BUILD</varname> check is done prior to the
+ build stage. Build conflicts are not recorded in the
+ resulting package.</para>
+ </sect2>
+
+ <sect2 xml:id="conflicts-conflicts">
+ <title><varname>CONFLICTS</varname></title>
+
+ <para xml:lang="en">If the port cannot be built if a certain port is already
+ installed and the resulting package cannot coexist with the
+ other package, list the other package name in
+ <varname>CONFLICTS</varname>. use shell
+ globs like <literal>*</literal> and <literal>?</literal> here.
+ Enumerate package names in there, not port names or
+ origins. Please make sure that
+ <varname>CONFLICTS</varname> does not match this
+ port's package itself. Otherwise enforcing its installation
+ with <varname>FORCE_PKG_REGISTER</varname> will no longer
+ work. <varname>CONFLICTS</varname> check is done prior to the
+ build stage and prior to the install stage.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="install">
+ <title xml:lang="en">Installing Files</title>
+
+ <sect2 xml:id="install-macros">
+ <title xml:lang="en"><varname>INSTALL_<replaceable>*</replaceable></varname>
+ Macros</title>
+
+ <para xml:lang="en">Use the macros provided in
+ <filename>bsd.port.mk</filename> to ensure correct modes of
+ files in the port's <buildtarget xml:lang="en">*-install</buildtarget>
+ targets. Set ownership directly in
+ <filename>pkg-plist</filename> with the corresponding entries,
+ such as
+ <literal>@(<replaceable>owner</replaceable>,<replaceable>group</replaceable>,)</literal>,
+ <literal>@owner <replaceable>owner</replaceable></literal>,
+ and <literal>@group
+ <replaceable>group</replaceable></literal>.
+ These operators work until overridden, or until the end
+ of <filename>pkg-plist</filename>, so do not forget to reset
+ them after they are no longer needed. The default ownership
+ is <literal>root:wheel</literal>. See <xref linkend="plist-keywords-base"/> for more information.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para xml:lang="en"><varname>INSTALL_PROGRAM</varname> is a command to
+ install binary executables.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><varname>INSTALL_SCRIPT</varname> is a command to
+ install executable scripts.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><varname>INSTALL_LIB</varname> is a command to install
+ shared libraries (but not static libraries).</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><varname>INSTALL_KLD</varname> is a command to
+ install kernel loadable modules. Some architectures
+ do not like having the modules stripped, so
+ use this command instead of
+ <varname>INSTALL_PROGRAM</varname>.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><varname>INSTALL_DATA</varname> is a command to
+ install sharable data, including static libraries.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><varname>INSTALL_MAN</varname> is a command to
+ install manpages and other documentation (it does not
+ compress anything).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para xml:lang="en">These variables are set to the <citerefentry><refentrytitle>install</refentrytitle><manvolnum>1</manvolnum></citerefentry> command
+ with the appropriate flags for each situation.</para>
+
+ <important>
+ <para xml:lang="en">Do not use <varname>INSTALL_LIB</varname> to install
+ static libraries, because stripping them renders them
+ useless. Use <varname>INSTALL_DATA</varname>
+ instead.</para>
+ </important>
+ </sect2>
+
+ <sect2 xml:id="install-strip">
+ <title xml:lang="en">Stripping Binaries and Shared Libraries</title>
+
+ <para xml:lang="en">Installed binaries should be stripped. Do not strip
+ binaries manually unless absolutely required. The
+ <varname>INSTALL_PROGRAM</varname> macro installs and
+ strips a binary at the same time. The
+ <varname>INSTALL_LIB</varname> macro does the same thing to
+ shared libraries.</para>
+
+ <para xml:lang="en">When a file must be stripped, but neither
+ <varname>INSTALL_PROGRAM</varname> nor
+ <varname>INSTALL_LIB</varname> macros are desirable,
+ <literal>${STRIP_CMD}</literal> strips the program or
+ shared library. This is typically done within the
+ <buildtarget xml:lang="en">post-install</buildtarget> target. For
+ example:</para>
+
+ <programlisting xml:lang="en">post-install:
+ ${STRIP_CMD} ${STAGEDIR}${PREFIX}/bin/xdl</programlisting>
+
+ <para xml:lang="en">When multiple files need to be stripped:</para>
+
+ <programlisting xml:lang="en">post-install:
+.for l in geometry media body track world
+ ${STRIP_CMD} ${STAGEDIR}${PREFIX}/lib/lib${PORTNAME}-${l}.so.0
+.endfor</programlisting>
+
+ <para xml:lang="en">Use <citerefentry><refentrytitle>file</refentrytitle><manvolnum>1</manvolnum></citerefentry> on a file to determine if it has been
+ stripped. Binaries are reported by <citerefentry><refentrytitle>file</refentrytitle><manvolnum>1</manvolnum></citerefentry> as
+ <literal>stripped</literal>, or
+ <literal>not stripped</literal>. Additionally, <citerefentry><refentrytitle>strip</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ will detect programs that have already been stripped and exit
+ cleanly.</para>
+ </sect2>
+
+ <sect2 xml:id="install-copytree">
+ <title xml:lang="en">Installing a Whole Tree of Files</title>
+
+ <para xml:lang="en">Sometimes, a large number of files must be installed while
+ preserving their hierarchical organization. For example,
+ copying over a whole directory tree from
+ <varname>WRKSRC</varname> to a target directory under
+ <varname>PREFIX</varname>. Note that
+ <varname>PREFIX</varname>, <varname>EXAMPLESDIR</varname>,
+ <varname>DATADIR</varname>, and other path variables must
+ always be prepended with <varname>STAGEDIR</varname> to
+ respect staging (see <xref linkend="staging"/>).</para>
+
+ <para xml:lang="en">Two macros exist for this situation. The advantage of
+ using these macros instead of <command>cp</command> is that
+ they guarantee proper file ownership and permissions on target
+ files. The first macro, <varname>COPYTREE_BIN</varname>, will
+ set all the installed files to be executable, thus being
+ suitable for installing into <filename>PREFIX/bin</filename>.
+ The second macro, <varname>COPYTREE_SHARE</varname>, does not
+ set executable permissions on files, and is therefore suitable
+ for installing files under <filename>PREFIX/share</filename>
+ target.</para>
+
+ <programlisting>post-install:
+ ${MKDIR} ${STAGEDIR}${EXAMPLESDIR}
+ (cd ${WRKSRC}/examples &amp;&amp; ${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR})</programlisting>
+
+ <para xml:lang="en">This example will install the contents of the
+ <filename>examples</filename> directory in the vendor distfile
+ to the proper examples location of the port.</para>
+
+ <programlisting>post-install:
+ ${MKDIR} ${STAGEDIR}${DATADIR}/summer
+ (cd ${WRKSRC}/temperatures &amp;&amp; ${COPYTREE_SHARE} "June July August" ${STAGEDIR}${DATADIR}/summer)</programlisting>
+
+ <para xml:lang="en">And this example will install the data of summer months to
+ the <filename>summer</filename> subdirectory of a
+ <filename>DATADIR</filename>.</para>
+
+ <para xml:lang="en">Additional <command>find</command> arguments can be
+ passed via the third argument to
+ <varname>COPYTREE_<replaceable>*</replaceable></varname>
+ macros. For example, to install
+ all files from the first example except Makefiles, one can use
+ these commands.</para>
+
+ <programlisting>post-install:
+ ${MKDIR} ${STAGEDIR}${EXAMPLESDIR}
+ (cd ${WRKSRC}/examples &amp;&amp; \
+ ${COPYTREE_SHARE} . ${STAGEDIR}${EXAMPLESDIR} "! -name Makefile")</programlisting>
+
+ <para xml:lang="en">These macros do not add the installed files to
+ <filename>pkg-plist</filename>. They must be added manually.
+ For optional documentation (<varname>PORTDOCS</varname>, see
+ <xref linkend="install-documentation"/>) and examples
+ (<varname>PORTEXAMPLES</varname>), the
+ <literal>%%PORTDOCS%%</literal> or
+ <literal>%%PORTEXAMPLES%%</literal> prefixes must be prepended
+ in <filename>pkg-plist</filename>.</para>
+ </sect2>
+
+ <sect2 xml:id="install-documentation">
+ <title xml:lang="en">Install Additional Documentation</title>
+
+ <para xml:lang="en">If the software has some documentation other than the
+ standard man and info pages that is useful for the
+ user, install it under <varname>DOCSDIR</varname>
+ This can be done, like the previous item, in the
+ <buildtarget xml:lang="en">post-install</buildtarget> target.</para>
+
+ <para xml:lang="en">Create a new directory for the port. The directory name
+ is <varname>DOCSDIR</varname>. This usually equals
+ <varname>PORTNAME</varname>. However, if the user
+ might want different versions of the port to be installed at
+ the same time, the whole
+ <varname>PKGNAME</varname> can be used.</para>
+
+ <para xml:lang="en">Since only the files listed in
+ <filename>pkg-plist</filename> are installed, it is safe to
+ always install documentation to <varname>STAGEDIR</varname>
+ (see <xref linkend="staging"/>). Hence <literal>.if</literal>
+ blocks are only needed when the installed files are large
+ enough to cause significant I/O overhead.</para>
+
+ <programlisting xml:lang="en">post-install:
+ ${MKDIR} ${STAGEDIR}${DOCSDIR}
+ ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${STAGEDIR}${DOCSDIR}</programlisting>
+
+ <para xml:lang="en">Here are some handy variables and how they are expanded by
+ default when used in the <filename>Makefile</filename>:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para xml:lang="en"><varname>DATADIR</varname> gets expanded to
+ <filename>PREFIX/share/PORTNAME</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><varname>DATADIR_REL</varname> gets expanded to
+ <filename>share/PORTNAME</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><varname>DOCSDIR</varname> gets expanded to
+ <filename>PREFIX/share/doc/PORTNAME</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><varname>DOCSDIR_REL</varname> gets expanded to
+ <filename>share/doc/PORTNAME</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><varname>EXAMPLESDIR</varname> gets expanded to
+ <filename>PREFIX/share/examples/PORTNAME</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en"><varname>EXAMPLESDIR_REL</varname> gets expanded to
+ <filename>share/examples/PORTNAME</filename>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <note>
+ <para xml:lang="en">The <literal>DOCS</literal> option only controls
+ additional documentation installed in
+ <varname>DOCSDIR</varname>. It does not apply to standard
+ man pages and info pages. Things installed in
+ <varname>DATADIR</varname> and
+ <varname>EXAMPLESDIR</varname> are controlled by
+ <literal>DATA</literal> and <literal>EXAMPLES</literal>
+ options, respectively.</para>
+ </note>
+
+ <para xml:lang="en">These variables are exported to
+ <varname>PLIST_SUB</varname>. Their values will appear there
+ as pathnames relative to <filename>PREFIX</filename> if
+ possible. That is, <filename>share/doc/PORTNAME</filename>
+ will be substituted for <literal>%%DOCSDIR%%</literal> in the
+ packing list by default, and so on. (See more on
+ <filename>pkg-plist</filename> substitution
+ <link linkend="plist-sub">here</link>.)</para>
+
+ <para xml:lang="en">All conditionally installed documentation files and
+ directories are included in
+ <filename>pkg-plist</filename> with the
+ <literal>%%PORTDOCS%%</literal> prefix, for example:</para>
+
+ <programlisting xml:lang="en">%%PORTDOCS%%%%DOCSDIR%%/AUTHORS
+%%PORTDOCS%%%%DOCSDIR%%/CONTACT</programlisting>
+
+ <para xml:lang="en">As an alternative to enumerating the documentation files
+ in <filename>pkg-plist</filename>, a port can set the variable
+ <varname>PORTDOCS</varname> to a list of file names and shell
+ glob patterns to add to the final packing list. The names
+ will be relative to <varname>DOCSDIR</varname>. Therefore, a
+ port that utilizes <varname>PORTDOCS</varname>, and uses a
+ non-default location for its documentation, must set
+ <varname>DOCSDIR</varname> accordingly. If a directory is
+ listed in <varname>PORTDOCS</varname> or matched by a glob
+ pattern from this variable, the entire subtree of contained
+ files and directories will be registered in the final packing
+ list. If the <literal>DOCS</literal> option has been unset
+ then files and directories listed in
+ <varname>PORTDOCS</varname> would not be installed or added to
+ port packing list. Installing the documentation at
+ <varname>PORTDOCS</varname> as shown above remains up to the
+ port itself. A typical example of utilizing
+ <varname>PORTDOCS</varname> looks as follows:</para>
+
+ <programlisting xml:lang="en">PORTDOCS= README.* ChangeLog docs/*</programlisting>
+
+ <note>
+ <para xml:lang="en">The equivalents of <varname>PORTDOCS</varname> for files
+ installed under <varname>DATADIR</varname> and
+ <varname>EXAMPLESDIR</varname> are
+ <varname>PORTDATA</varname> and
+ <varname>PORTEXAMPLES</varname>, respectively.</para>
+
+ <para xml:lang="en">The contents of <filename>pkg-message</filename> are
+ displayed upon installation. See
+ <link linkend="porting-message">the section on using
+ <filename>pkg-message</filename></link> for details.
+ <filename>pkg-message</filename> does not need to be added
+ to <filename>pkg-plist</filename>.</para>
+ </note>
+ </sect2>
+
+ <sect2 xml:id="install-subdirs">
+ <title xml:lang="en">Subdirectories Under <varname>PREFIX</varname></title>
+
+ <para xml:lang="en">Try to let the port put things in the right subdirectories
+ of <varname>PREFIX</varname>. Some ports lump everything and
+ put it in the subdirectory with the port's name, which is
+ incorrect. Also, many ports put everything except binaries,
+ header files and manual pages in a subdirectory of
+ <filename>lib</filename>, which does not work well with the
+ BSD paradigm. Many of the files must be moved to one of these
+ directories: <filename>etc</filename> (setup/configuration
+ files), <filename>libexec</filename> (executables started
+ internally), <filename>sbin</filename> (executables for
+ superusers/managers), <filename>info</filename> (documentation
+ for info browser) or <filename>share</filename> (architecture
+ independent files). See <citerefentry><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details; the rules
+ governing <filename>/usr</filename> pretty much apply to
+ <filename>/usr/local</filename> too. The exception are ports
+ dealing with USENET <quote>news</quote>. They may use
+ <filename>PREFIX/news</filename> as a destination for their
+ files.</para>
+ </sect2>
+ </sect1>
+</chapter>
+
+
+<!--
+ The FreeBSD Documentation Project
+
+ $FreeBSD$
+-->
+<chapter version="5.0" xml:id="special">
+
+ <title xml:lang="en">Special Considerations</title>
+
+ <para xml:lang="en">This section explains the most common things to consider when
+ creating a port.</para>
+
+ <sect1 xml:id="staging">
+ <title xml:lang="en">Staging</title>
+
+ <para xml:lang="en"><filename>bsd.port.mk</filename> expects ports to work
+ with a <quote>stage directory</quote>. This means that a port
+ must not install files directly to the regular destination
+ directories (that is, under <varname>PREFIX</varname>, for
+ example) but instead into a separate directory from which the
+ package is then built. In many cases, this does not require
+ root privileges, making it possible to build packages as an
+ unprivileged user. With staging, the port is built and
+ installed into the stage directory,
+ <varname>STAGEDIR</varname>. A package is created from the
+ stage directory and then installed on the system. Automake
+ tools refer to this concept as <varname>DESTDIR</varname>, but
+ in FreeBSD, <varname>DESTDIR</varname> has a different meaning
+ (see <xref linkend="porting-prefix"/>).</para>
+
+ <note>
+ <para xml:lang="en">No port <emphasis>really</emphasis> needs to be root. It
+ can mostly be avoided by using <link linkend="uses-uidfix"><literal>USES=uidfix</literal></link>.
+ If the port still runs commands like <citerefentry><refentrytitle>chown</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>chgrp</refentrytitle><manvolnum>1</manvolnum></citerefentry>, or forces owner or group with <citerefentry><refentrytitle>install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ then use <link linkend="uses-fakeroot"><literal>USES=fakeroot</literal></link>
+ to fake those calls. Some patching of the port's
+ <filename>Makefiles</filename> will be needed.</para>
+ </note>
+
+ <para xml:lang="en">Meta ports, or ports that do not install files themselves
+ but only depend on other ports, must avoid needlessly
+ extracting the <citerefentry><refentrytitle>mtree</refentrytitle><manvolnum>8</manvolnum></citerefentry> to the stage directory. This is
+ the basic directory layout of the package, and these empty
+ directories will be seen as orphans. To prevent
+ <citerefentry><refentrytitle>mtree</refentrytitle><manvolnum>8</manvolnum></citerefentry> extraction, add this line:</para>
+
+ <programlisting>NO_MTREE= yes</programlisting>
+
+ <tip>
+ <para xml:lang="en">Metaports should use <link linkend="uses-metaport"><literal>USES=metaport</literal></link>.
+ It sets up defaults for ports that do not fetch, build, or
+ install anything.</para>
+ </tip>
+
+ <para xml:lang="en">Staging is enabled by prepending
+ <varname>STAGEDIR</varname> to paths used in the
+ <buildtarget xml:lang="en">pre-install</buildtarget>,
+ <buildtarget xml:lang="en">do-install</buildtarget>, and
+ <buildtarget xml:lang="en">post-install</buildtarget> targets (see the
+ examples through the book). Typically, this includes
+ <varname>PREFIX</varname>, <varname>ETCDIR</varname>,
+ <varname>DATADIR</varname>, <varname>EXAMPLESDIR</varname>,
+ <varname>MANPREFIX</varname>, <varname>DOCSDIR</varname>, and
+ so on. Directories should be created as part of the
+ <buildtarget xml:lang="en">post-install</buildtarget> target. Avoid using
+ absolute paths whenever possible.</para>
+
+ <para xml:lang="en">When creating a symlink, <varname>STAGEDIR</varname>
+ is prepended to the target path only. For
+ example:</para>
+
+ <programlisting xml:lang="en">${LN} -sf <replaceable>libfoo.so.42</replaceable> ${STAGEDIR}${PREFIX}/lib/<replaceable>libfoo.so</replaceable></programlisting>
+
+ <para xml:lang="en">The source path
+ <filename>${PREFIX}/lib/<replaceable>libfoo.so.42</replaceable></filename>
+ looks fine but could, in fact, be incorrect. Absolute paths can
+ point to a wrong location, like when a remote file system has
+ been mounted with <acronym>NFS</acronym> under a non-root mount
+ point. Relative paths are less fragile, and often much
+ shorter.</para>
+
+ <para xml:lang="en">Ports that install kernel modules must prepend
+ <varname>STAGEDIR</varname> to their destination, by default
+ <filename>/boot/modules</filename>.</para>
+ </sect1>
+
+ <sect1 xml:id="bundled-libs">
+ <title xml:lang="en">Bundled Libraries</title>
+
+ <para xml:lang="en">This section explains why bundled dependencies are
+ considered bad and what to do about them.</para>
+
+ <sect2 xml:id="bundled-libs-why-bad">
+ <title xml:lang="en">Why Bundled Libraries Are Bad</title>
+
+ <para xml:lang="en">Some software requires the porter to locate third-party
+ libraries and add the required dependencies to the port.
+ Other software bundles all necessary libraries into the
+ distribution file. The second approach seems easier at
+ first, but there are some serious drawbacks:</para>
+
+ <para xml:lang="en">This list is loosely based on the <link xlink:href="https://fedoraproject.org/wiki/Packaging:No_Bundled_Libraries">Fedora</link>
+ and <link xlink:href="http://wiki.gentoo.org/wiki/Why_not_bundle_dependencies">Gentoo</link>
+ wikis, both licensed under the <link xlink:href="http://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA
+ 3.0</link> license.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>安全性</term>
+
+ <listitem>
+ <para xml:lang="en">If vulnerabilities are found in the upstream library
+ and fixed there, they might not be fixed in the library
+ bundled with the port. One reason could be that the
+ author is not aware of the problem. This means that the
+ porter must fix them, or upgrade to a non-vulnerable
+ version, and send a patch to the author. This all takes
+ time, which results in software being vulnerable longer
+ than necessary. This in turn makes it harder to
+ coordinate a fix without unnecessarily leaking
+ information about the vulnerability.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>臭蟲</term>
+
+ <listitem>
+ <para xml:lang="en">This problem is similar to the problem with security
+ in the last paragraph, but generally less severe.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term xml:lang="en">Forking</term>
+
+ <listitem>
+ <para xml:lang="en">It is easier for the author to fork the upstream
+ library once it is bundled. While convenient on first
+ sight, it means that the code diverges from upstream
+ making it harder to address security or other problems
+ with the software. A reason for this is that patching
+ becomes harder.</para>
+
+ <para xml:lang="en">Another problem of forking is that because code
+ diverges from upstream, bugs get solved over and over
+ again instead of just once at a central location. This
+ defeats the idea of open source software in the first
+ place.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term xml:lang="en">Symbol collision</term>
+
+ <listitem>
+ <para xml:lang="en">When a library is installed on the system, it might
+ collide with the bundled version. This can cause
+ immediate errors at compile or link time. It can also
+ cause errors when running the program which might be
+ harder to track down. The latter problem could be
+ caused because the versions of the two libraries are
+ incompatible.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term xml:lang="en">Licensing</term>
+
+ <listitem>
+ <para xml:lang="en">When bundling projects from different sources,
+ license issues can arise more easily, especially when
+ licenses are incompatible.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>浪費資源</term>
+
+ <listitem>
+ <para xml:lang="en">Bundled libraries waste resources on several levels.
+ It takes longer to build the actual application,
+ especially if these libraries are already present on the
+ system. At run-time, they can take up unnecessary
+ memory when the system-wide library is already loaded by
+ one program and the bundled library is loaded by another
+ program.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>浪費努力</term>
+
+ <listitem>
+ <para xml:lang="en">When a library needs patches for FreeBSD, these patches
+ have to be duplicated again in the bundled library.
+ This wastes developer time because the patches might not
+ apply cleanly. It can also be hard to notice that these
+ patches are required in the first place.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2 xml:id="bundled-libs-practices">
+ <title xml:lang="en">What to do About Bundled Libraries</title>
+
+ <para xml:lang="en">Whenever possible, use the unbundled version of the
+ library by adding a <varname>LIB_DEPENDS</varname> to the
+ port. If such a port does not exist yet, consider creating
+ it.</para>
+
+ <para xml:lang="en">Only use bundled libraries if the upstream has a
+ good track record on security and using unbundled versions
+ leads to overly complex patches.</para>
+
+ <note>
+ <para xml:lang="en">In some very special cases, for example emulators, like
+ <application>Wine</application>, a port has to bundle
+ libraries, because they are in a different architecture, or
+ they have been modified to fit the software's use. In that
+ case, those libraries should not be exposed to other ports
+ for linking. Add <literal>BUNDLE_LIBS=yes</literal> to the
+ port's <filename>Makefile</filename>. This will tell
+ <citerefentry><refentrytitle>pkg</refentrytitle><manvolnum>8</manvolnum></citerefentry> to not compute provided libraries. Always ask
+ the Ports Management Team <email>portmgr@FreeBSD.org</email> before adding this to a port.</para>
+ </note>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="porting-shlibs">
+ <title>共用函式庫</title>
+
+ <para xml:lang="en">If the port installs one or more shared libraries, define
+ a <varname>USE_LDCONFIG</varname> make variable, which will
+ instruct a <filename>bsd.port.mk</filename> to run
+ <literal>${LDCONFIG} -m</literal> on the directory
+ where the new library is installed (usually
+ <filename>PREFIX/lib</filename>) during
+ <buildtarget xml:lang="en">post-install</buildtarget> target to register it
+ into the shared library cache. This variable, when defined,
+ will also facilitate addition of an appropriate
+ <literal>@exec /sbin/ldconfig -m</literal> and
+ <literal>@unexec /sbin/ldconfig -R</literal> pair into
+ <filename>pkg-plist</filename>, so that a user who
+ installed the package can start using the shared library
+ immediately and de-installation will not cause the system to
+ still believe the library is there.</para>
+
+ <programlisting xml:lang="en">USE_LDCONFIG= yes</programlisting>
+
+ <para xml:lang="en">The default directory can be overridden by
+ setting <varname>USE_LDCONFIG</varname> to a list of
+ directories into which shared libraries are to be installed.
+ For example, if the port installs shared libraries into
+ <filename>PREFIX/lib/foo</filename> and
+ <filename>PREFIX/lib/bar</filename>
+ use this in
+ <filename>Makefile</filename>:</para>
+
+ <programlisting xml:lang="en">USE_LDCONFIG= ${PREFIX}/lib/foo ${PREFIX}/lib/bar</programlisting>
+
+ <para xml:lang="en">Please double-check, often this is not necessary at all or
+ can be avoided through <literal>-rpath</literal> or setting
+ <envar>LD_RUN_PATH</envar> during linking (see
+ <package role="port">lang/moscow_ml</package> for an
+ example), or through a shell-wrapper which sets
+ <varname>LD_LIBRARY_PATH</varname> before invoking the binary,
+ like <package role="port">www/seamonkey</package>
+ does.</para>
+
+ <para xml:lang="en">When installing 32-bit libraries on 64-bit system, use
+ <varname>USE_LDCONFIG32</varname> instead.</para>
+
+ <para xml:lang="en">If the software uses <link linkend="using-autotools">autotools</link>, and specifically
+ <command>libtool</command>, add <link linkend="uses-libtool"><literal>USES=libtool</literal></link>.</para>
+
+ <para xml:lang="en">When the major library version number increments in the
+ update to the new port version, all other ports that link to
+ the affected library must have their
+ <varname>PORTREVISION</varname> incremented, to force
+ recompilation with the new library version.</para>
+ </sect1>
+
+ <sect1 xml:id="porting-restrictions">
+ <title xml:lang="en">Ports with Distribution Restrictions or Legal
+ Concerns</title>
+
+ <para xml:lang="en">Licenses vary, and some of them place restrictions on how
+ the application can be packaged, whether it can be sold for
+ profit, and so on.</para>
+
+ <important>
+ <para xml:lang="en">It is the responsibility of a porter to read the
+ licensing terms of the software and make sure that the
+ FreeBSD project will not be held accountable for violating
+ them by redistributing the source or compiled binaries
+ either via FTP/HTTP or CD-ROM. If in doubt, please contact
+ the <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports">FreeBSD ports mailing list</link>.</para>
+ </important>
+
+ <para xml:lang="en">In situations like this, the variables described in the
+ next sections can be set.</para>
+
+ <sect2 xml:id="porting-restrictions-no_package">
+ <title><varname>NO_PACKAGE</varname></title>
+
+ <para xml:lang="en">This variable indicates that we may not generate a
+ binary package of the application. For instance, the
+ license may disallow binary redistribution, or it may
+ prohibit distribution of packages created from patched
+ sources.</para>
+
+ <para xml:lang="en">However, the port's <varname>DISTFILES</varname> may be
+ freely mirrored on FTP/HTTP. They may also be distributed
+ on a CD-ROM (or similar media) unless
+ <varname>NO_CDROM</varname> is set as well.</para>
+
+ <para xml:lang="en">If the
+ binary package is not generally useful, and the application
+ must always be compiled from the source code, use
+ <varname>NO_PACKAGE</varname>. For
+ example, if the application has configuration information
+ that is site specific hard coded into it at compile time,
+ set <varname>NO_PACKAGE</varname>.</para>
+
+ <para xml:lang="en">Set <varname>NO_PACKAGE</varname> to a string
+ describing the reason why the package cannot be
+ generated.</para>
+ </sect2>
+
+ <sect2 xml:id="porting-restrictions-no_cdrom">
+ <title><varname>NO_CDROM</varname></title>
+
+ <para xml:lang="en">This variable alone indicates that, although we are
+ allowed to generate binary packages, we may put neither
+ those packages nor the port's <varname>DISTFILES</varname>
+ onto a CD-ROM (or similar media) for resale. However, the
+ binary packages and the port's <varname>DISTFILES</varname>
+ will still be available via FTP/HTTP.</para>
+
+ <para xml:lang="en"> If this variable is set along with
+ <varname>NO_PACKAGE</varname>, then only the port's
+ <varname>DISTFILES</varname> will be available, and only via
+ FTP/HTTP.</para>
+
+ <para xml:lang="en">Set <varname>NO_CDROM</varname> to a string
+ describing the reason why the port cannot be redistributed
+ on CD-ROM. For instance, use this if the port's
+ license is for <quote>non-commercial</quote> use
+ only.</para>
+ </sect2>
+
+ <sect2 xml:id="porting-restrictions-nofetchfiles">
+ <title><varname>NOFETCHFILES</varname></title>
+
+ <para xml:lang="en">Files defined in <varname>NOFETCHFILES</varname>
+ are not fetchable from any of
+ <varname>MASTER_SITES</varname>. An example of such a file
+ is when the file is supplied on CD-ROM by the vendor.</para>
+
+ <para xml:lang="en">Tools which check for the availability of these files
+ on <varname>MASTER_SITES</varname> have to ignore these
+ files and not report about them.</para>
+ </sect2>
+
+ <sect2 xml:id="porting-restrictions-restricted">
+ <title><varname>RESTRICTED</varname></title>
+
+ <para xml:lang="en">Set this variable alone if the application's license
+ permits neither mirroring the application's
+ <varname>DISTFILES</varname> nor distributing the binary
+ package in any way.</para>
+
+ <para xml:lang="en">Do not set <varname>NO_CDROM</varname> or
+ <varname>NO_PACKAGE</varname> along with
+ <varname>RESTRICTED</varname>, since the latter variable
+ implies the former ones.</para>
+
+ <para xml:lang="en">Set <varname>RESTRICTED</varname> to a string
+ describing the reason why the port cannot be redistributed.
+ Typically, this indicates that the port contains proprietary
+ software and that the user will need to manually download
+ the <varname>DISTFILES</varname>, possibly after registering
+ for the software or agreeing to accept the terms of an
+ <acronym>EULA</acronym>.</para>
+ </sect2>
+
+ <sect2 xml:id="porting-restrictions-restricted_files">
+ <title><varname>RESTRICTED_FILES</varname></title>
+
+ <para xml:lang="en">When <varname>RESTRICTED</varname> or
+ <varname>NO_CDROM</varname> is set, this variable defaults
+ to <literal>${DISTFILES} ${PATCHFILES}</literal>, otherwise
+ it is empty. If only some of the distribution files are
+ restricted, then set this variable to list them.</para>
+
+ </sect2>
+
+ <sect2 xml:id="porting-restrictions-legal_text">
+ <title><varname>LEGAL_TEXT</varname></title>
+
+ <para xml:lang="en">If the port has legal concerns not addressed by the
+ above variables, set <varname>LEGAL_TEXT</varname>
+ to a string explaining the concern. For
+ example, if special permission was obtained for FreeBSD to
+ redistribute the binary, this variable must indicate
+ so.</para>
+ </sect2>
+
+ <sect2 xml:id="porting-restrictions-legal">
+ <title><filename>/usr/ports/LEGAL</filename> 和 <varname>LEGAL</varname></title>
+
+ <para xml:lang="en">A port which sets any of the above variables must also
+ be added to <filename>/usr/ports/LEGAL</filename>. The
+ first column is a glob which matches the restricted
+ distfiles. The second column is the port's origin. The
+ third column is the output of
+ <command>make -VLEGAL</command>.</para>
+ </sect2>
+
+ <sect2 xml:id="porting-restrictions-examples">
+ <title>範例</title>
+
+ <para xml:lang="en">The preferred way to state "the distfiles for this port
+ must be fetched manually" is as follows:</para>
+
+ <programlisting xml:lang="en">.if !exists(${DISTDIR}/${DISTNAME}${EXTRACT_SUFX})
+IGNORE= may not be redistributed because of licensing reasons. Please visit <replaceable>some-website</replaceable> to accept their license and download ${DISTFILES} into ${DISTDIR}
+.endif</programlisting>
+
+ <para xml:lang="en">This both informs the user, and sets the proper metadata
+ on the user's machine for use by automated programs.</para>
+
+ <para xml:lang="en">Note that this stanza must be preceded by an inclusion
+ of <filename>bsd.port.pre.mk</filename>.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="building">
+ <title xml:lang="en">Building Mechanisms</title>
+
+ <sect2 xml:id="parallel-builds">
+ <title xml:lang="en">Building Ports in Parallel</title>
+
+ <para xml:lang="en">The FreeBSD ports framework supports parallel building
+ using multiple <command>make</command> sub-processes, which
+ allows <acronym>SMP</acronym> systems to utilize all of
+ their available <acronym>CPU</acronym> power, allowing port
+ builds to be faster and more effective.</para>
+
+ <para xml:lang="en">This is achieved by passing <varname>-jX</varname> flag
+ to <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> running on vendor code. This is the default
+ build behavior of ports. Unfortunately, not all ports
+ handle parallel building well and it may be required to
+ explicitly disable this feature by adding the
+ <literal>MAKE_JOBS_UNSAFE=yes</literal> variable. It is
+ used when a port is known to be broken with
+ <varname>-jX</varname>.</para>
+ </sect2>
+
+ <sect2 xml:id="using-make">
+ <title><command>make</command>, <command>gmake</command>, <command>fmake</command>, 和 <command>imake</command></title>
+
+ <para xml:lang="en">Several differing <literal>make</literal>
+ implementations exist. Ported software often requires a
+ particular implementation, like <acronym>GNU</acronym>
+ <command>make</command>, known in FreeBSD as
+ <command>gmake</command>, or <command>fmake</command>, the
+ legacy FreeBSD <command>make</command>.</para>
+
+ <para xml:lang="en">If the port uses <application>GNU make</application>,
+ add <literal>gmake</literal> to <literal>USES</literal>. If
+ the legacy FreeBSD <command>make</command> is needed, add
+ <literal>fmake</literal> there.</para>
+
+ <para xml:lang="en"><varname>MAKE_CMD</varname> can be used to reference the
+ specific command configured by the <literal>USES</literal>
+ setting in the port's <filename>Makefile</filename>. In
+ rare cases when more than one <literal>make</literal>
+ implementation is listed in <literal>USES</literal>, the
+ variables <varname>GMAKE</varname> (for the
+ <acronym>GNU</acronym> version) or <varname>FMAKE</varname>
+ (for the legacy FreeBSD version) are available.
+ Only use <varname>MAKE_CMD</varname> within the
+ application <filename>Makefile</filename>s in
+ <varname>WRKSRC</varname> to call the
+ <command>make</command> implementation expected by the
+ ported software.</para>
+
+ <para xml:lang="en">If the port is an X application that uses
+ <application>imake</application> to create
+ <filename>Makefile</filename>s from
+ <filename>Imakefile</filename>s, set <literal>USES=
+ imake</literal>.. See the <link linkend="uses-imake"><literal>USES=imake</literal></link>
+ section of <xref linkend="uses"/> for more details.</para>
+
+ <para xml:lang="en">If the port's source <filename>Makefile</filename> has
+ something other than <buildtarget xml:lang="en">all</buildtarget> as the
+ main build target, set <varname>ALL_TARGET</varname>
+ accordingly. The same goes for
+ <buildtarget xml:lang="en">install</buildtarget> and
+ <varname>INSTALL_TARGET</varname>.</para>
+ </sect2>
+
+ <sect2 xml:id="using-configure">
+ <title xml:lang="en"><command>configure</command> Script</title>
+
+ <para xml:lang="en">If the port uses the <command>configure</command>
+ script to generate <filename>Makefile</filename> from
+ <filename>Makefile.in</filename>, set
+ <literal>GNU_CONFIGURE=yes</literal>. To give
+ extra arguments to the <command>configure</command> script
+ (the default argument is <literal>--prefix=${PREFIX}
+ --infodir=${PREFIX}/${INFO_PATH}
+ --mandir=${MANPREFIX}/man
+ --build=${CONFIGURE_TARGET}</literal>), set those
+ extra arguments in <varname>CONFIGURE_ARGS</varname>. Extra
+ environment variables can be passed using
+ <varname>CONFIGURE_ENV</varname>.</para>
+
+ <table frame="none" xml:id="using-configure-variables">
+ <title xml:lang="en">Variables for Ports That Use
+ <command>configure</command></title>
<tgroup cols="2">
<thead>
<row>
- <entry>Variable</entry>
-
- <entry>Means</entry>
+ <entry xml:lang="en">Variable</entry>
+ <entry xml:lang="en">Means</entry>
</row>
</thead>
<tbody>
<row>
- <entry><varname>USE_PERL5</varname></entry>
-
- <entry>Says that the port uses <literal>perl 5</literal> to build and run.</entry>
- </row>
-
- <row>
- <entry><varname>USE_PERL5_BUILD</varname></entry>
-
- <entry>Says that the port uses <literal>perl 5</literal> to build.</entry>
+ <entry><varname>GNU_CONFIGURE</varname></entry>
+ <entry xml:lang="en">The port uses <command>configure</command>
+ script to prepare build.</entry>
</row>
<row>
- <entry><varname>USE_PERL5_RUN</varname></entry>
-
- <entry>Says that the port uses <literal>perl 5</literal> to run.</entry>
+ <entry><varname>HAS_CONFIGURE</varname></entry>
+ <entry xml:lang="en">Same as <varname>GNU_CONFIGURE</varname>,
+ except default configure target is not added to
+ <varname>CONFIGURE_ARGS</varname>.</entry>
</row>
<row>
- <entry><varname>PERL</varname></entry>
-
- <entry>The full path of <literal>perl 5</literal>, either in the
- system or installed from a port, but without the version
- number. Use this if you need to replace
- <quote><literal>#!</literal></quote>lines in scripts.</entry>
+ <entry><varname>CONFIGURE_ARGS</varname></entry>
+ <entry xml:lang="en">Additional arguments passed to
+ <command>configure</command> script.</entry>
</row>
<row>
- <entry><varname>PERL_CONFIGURE</varname></entry>
-
- <entry>Configure using Perl's MakeMaker. It implies
- <varname>USE_PERL5</varname>.</entry>
+ <entry><varname>CONFIGURE_ENV</varname></entry>
+ <entry xml:lang="en">Additional environment variables to be set
+ for <command>configure</command> script run.</entry>
</row>
<row>
- <entry><varname>PERL_MODBUILD</varname></entry>
-
- <entry>Configure, build and install using Module::Build. It
- implies <varname>PERL_CONFIGURE</varname>.</entry>
+ <entry xml:lang="en"><varname>CONFIGURE_TARGET</varname></entry>
+ <entry xml:lang="en">Override default configure target. Default
+ value is
+ <literal>${MACHINE_ARCH}-portbld-freebsd${OSREL}</literal>.</entry>
</row>
</tbody>
</tgroup>
+ </table>
+ </sect2>
+
+ <sect2 xml:id="using-cmake">
+ <title xml:lang="en">Using <command>cmake</command></title>
+
+ <para xml:lang="en">For ports that use <application>CMake</application>,
+ define <literal>USES= cmake</literal>, or
+ <literal>USES= cmake:outsource</literal> to build in a
+ separate directory (see below).</para>
+
+ <table frame="none" xml:id="using-cmake-variables">
+ <title xml:lang="en">Variables for Ports That Use
+ <command>cmake</command></title>
<tgroup cols="2">
<thead>
<row>
- <entry>Read only variables</entry>
-
- <entry>Means</entry>
+ <entry xml:lang="en">Variable</entry>
+ <entry xml:lang="en">Means</entry>
</row>
</thead>
<tbody>
<row>
- <entry><varname>PERL_VERSION</varname></entry>
-
- <entry>The full version of <literal>perl</literal> installed (e.g.,
- <literal>5.00503</literal>).</entry>
+ <entry><varname>CMAKE_ARGS</varname></entry>
+ <entry xml:lang="en">Port specific <application>CMake</application>
+ flags to be passed to the <command>cmake</command>
+ binary.</entry>
</row>
<row>
- <entry><varname>PERL_VER</varname></entry>
-
- <entry>The short version of <literal>perl</literal> installed (e.g.,
- <literal>5.005</literal>).</entry>
+ <entry><varname>CMAKE_BUILD_TYPE</varname></entry>
+ <entry xml:lang="en">Type of build (<application>CMake</application>
+ predefined build profiles). Default is
+ <literal>Release</literal>, or
+ <literal>Debug</literal> if
+ <varname>WITH_DEBUG</varname> is set.</entry>
</row>
<row>
- <entry><varname>PERL_LEVEL</varname></entry>
-
- <entry>The installed <literal>perl</literal> version as an integer of the form <literal>MNNNPP</literal>
- (e.g., <literal>500503</literal>).</entry>
+ <entry><varname>CMAKE_ENV</varname></entry>
+ <entry xml:lang="en">Environment variables to be set for the
+ <command>cmake</command> binary. Default is
+ <literal>${CONFIGURE_ENV}</literal>.</entry>
</row>
<row>
- <entry><varname>PERL_ARCH</varname></entry>
-
- <entry>Where <literal>perl</literal> stores architecture dependent libraries.
- Defaults to <literal>${ARCH}-freebsd</literal>.</entry>
+ <entry><varname>CMAKE_SOURCE_PATH</varname></entry>
+ <entry xml:lang="en">Path to the source directory. Default is
+ <literal>${WRKSRC}</literal>.</entry>
</row>
+ </tbody>
+ </tgroup>
+ </table>
- <row>
- <entry><varname>PERL_PORT</varname></entry>
+ <table frame="none" xml:id="using-cmake-user-variables">
+ <title xml:lang="en">Variables the Users Can Define for
+ <command>cmake</command> Builds</title>
- <entry>Name of the <literal>perl</literal> port that is
- installed (e.g., <literal>perl5</literal>).</entry>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry xml:lang="en">Variable</entry>
+ <entry xml:lang="en">Means</entry>
</row>
+ </thead>
+ <tbody>
<row>
- <entry><varname>SITE_PERL</varname></entry>
+ <entry><varname>CMAKE_VERBOSE</varname></entry>
+ <entry xml:lang="en">Enable verbose build output. Default not set,
+ unless <varname>BATCH</varname> or
+ <varname>PACKAGE_BUILDING</varname> are set.</entry>
+ </row>
- <entry>Directory name where site specific
- <literal>perl</literal> packages go.
- This value is added to PLIST_SUB.</entry>
+ <row>
+ <entry><varname>CMAKE_NOCOLOR</varname></entry>
+ <entry xml:lang="en">Disables color build output. Default not set,
+ unless <varname>BATCH</varname> or
+ <varname>PACKAGE_BUILDING</varname> are set.</entry>
</row>
</tbody>
</tgroup>
</table>
- <note>
- <para>Perl 模組的 port,由於沒有正式的網站,所以
- <filename>pkg-descr</filename> 內的 WWW 應該指向至
- <systemitem>cpan.org</systemitem>。 比較好的 URL 格式是
- <literal>http://search.cpan.org/dist/Module-Name/</literal>
- (包括結尾的 / 斜線符號)。</para>
- </note>
+ <para xml:lang="en"><application>CMake</application> supports these
+ build profiles: <literal>Debug</literal>,
+ <literal>Release</literal>,
+ <literal>RelWithDebInfo</literal> and
+ <literal>MinSizeRel</literal>. <literal>Debug</literal> and
+ <literal>Release</literal> profiles respect system
+ <literal>*FLAGS</literal>, <literal>RelWithDebInfo</literal>
+ and <literal>MinSizeRel</literal> will set
+ <varname>CFLAGS</varname> to <literal>-O2 -g</literal> and
+ <literal>-Os -DNDEBUG</literal> correspondingly. The
+ lower-cased value of <varname>CMAKE_BUILD_TYPE</varname> is
+ exported to <varname>PLIST_SUB</varname> and must be
+ used if the port installs
+ <filename><replaceable>*</replaceable>.cmake</filename>
+ depending on the build type (see
+ <package role="port">deskutils/strigi</package> for an
+ example). Please note that some projects may define their own
+ build profiles and/or force particular build type by setting
+ <literal>CMAKE_BUILD_TYPE</literal> in
+ <filename>CMakeLists.txt</filename>. To make a port for such
+ a project respect <varname>CFLAGS</varname> and
+ <varname>WITH_DEBUG</varname>, the
+ <literal>CMAKE_BUILD_TYPE</literal> definitions must be
+ removed from those files.</para>
+
+ <para xml:lang="en">Most <application>CMake</application>-based projects
+ support an out-of-source method of building. The
+ out-of-source build for a port can be requested by using the
+ <literal>:outsource</literal> suffix. When enabled,
+ <varname>CONFIGURE_WRKSRC</varname>,
+ <varname>BUILD_WRKSRC</varname> and
+ <varname>INSTALL_WRKSRC</varname> will be set to
+ <literal>${WRKDIR}/.build</literal> and this
+ directory will be used to keep all files generated during
+ configuration and build stages, leaving the source directory
+ intact.</para>
+
+ <example xml:id="using-cmake-example">
+ <title xml:lang="en"><literal>USES= cmake</literal> Example</title>
+
+ <para xml:lang="en">This snippet demonstrates the use of
+ <application>CMake</application> for a port.
+ <varname>CMAKE_SOURCE_PATH</varname> is not usually
+ required, but can be set when the sources are not located
+ in the top directory, or if only a subset of the project
+ is intended to be built by the port.</para>
+
+ <programlisting xml:lang="en">USES= cmake:outsource
+CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting>
+ </example>
+ </sect2>
- </sect1>
-
- <sect1 xml:id="using-x11">
- <title>Using X11</title>
-
- <sect2 xml:id="x11-variables">
- <title>X.Org components</title>
-
- <para>The X11 implementation available in The Ports Collection is X.Org.
- If your application depends on X components, set
- <varname>USE_XORG</varname> to the list of required components.
- Available components, at the time of writing, are:</para>
-
- <para><literal>bigreqsproto compositeproto damageproto dmx dmxproto
- evieproto fixesproto fontcacheproto fontenc fontsproto fontutil
- glproto ice inputproto kbproto libfs oldx printproto randrproto
- recordproto renderproto resourceproto scrnsaverproto sm trapproto
- videoproto x11 xau xaw xaw6 xaw7 xaw8 xbitmaps xcmiscproto xcomposite
- xcursor xdamage xdmcp xevie xext xextproto xf86bigfontproto
- xf86dgaproto xf86driproto xf86miscproto xf86rushproto
- xf86vidmodeproto xfixes xfont xfontcache xft xi xinerama
- xineramaproto xkbfile xkbui xmu xmuu xorg-server xp xpm xprintapputil
- xprintutil xpr oto xproxymngproto xrandr xrender xres xscrnsaver xt
- xtrans xtrap xtst xv xvmc xxf86dga xxf86misc xxf86vm</literal>.</para>
-
- <para>Always up-to-date list can be found in
- <filename>/usr/ports/Mk/bsd.xorg.mk</filename>.</para>
-
- <para>The Mesa Project is an effort to provide free OpenGL
- implementation. You can specify a dependency on various components
- of this project with <varname>USE_GL</varname> variable.
- Valid options are: <literal>glut, glu, glw, gl</literal> and
- <literal>linux</literal>. For backwards compatibility, the value
- of <literal>yes</literal> maps to <literal>glu</literal>.</para>
-
- <example xml:id="use-xorg-example">
- <title>USE_XORG example</title>
- <programlisting>USE_XORG= xrender xft xkbfile xt xaw
-USE_GL= glu</programlisting>
- </example>
+ <sect2 xml:id="using-scons">
+ <title xml:lang="en">Using <command>scons</command></title>
- <para>Many ports define <varname>USE_XLIB</varname>, which makes
- the port depend on all the 50 or so libraries. This variable
- exists for backwards compatibility, as it predates modular X.Org,
- and should not be used on new ports.</para>
+ <para xml:lang="en">If the port uses <application>SCons</application>,
+ define <literal>USE_SCONS=yes</literal>.</para>
- <table frame="none">
- <title>Variables for ports that use X</title>
+ <table frame="none" xml:id="using-scons-variables">
+ <title xml:lang="en">Variables for Ports That Use
+ <command>scons</command></title>
<tgroup cols="2">
- <tbody>
+ <thead>
<row>
- <entry><varname>USE_XLIB</varname></entry>
-
- <entry>The port uses the X libraries. Deprecated - use a list of
- X.Org components in <varname>USE_XORG</varname> variable
- instead.</entry>
+ <entry xml:lang="en">Variable</entry>
+ <entry xml:lang="en">Means</entry>
</row>
+ </thead>
+ <tbody>
<row>
- <entry><varname>USE_IMAKE</varname></entry>
-
- <entry>會用到 <command>imake</command> 的 port。</entry>
+ <entry><varname>SCONS_ARGS</varname></entry>
+ <entry xml:lang="en">Port specific SCons flags passed to the SCons
+ environment.</entry>
</row>
<row>
- <entry><varname>USE_X_PREFIX</varname></entry>
-
- <entry>Deprecated. Today it is equivalent to
- <varname>USE_XLIB</varname> and can be replaced by it
- freely.</entry>
+ <entry><varname>SCONS_BUILDENV</varname></entry>
+ <entry xml:lang="en">Variables to be set in system
+ environment.</entry>
</row>
<row>
- <entry><varname>XMKMF</varname></entry>
+ <entry><varname>SCONS_ENV</varname></entry>
+ <entry xml:lang="en">Variables to be set in SCons
+ environment.</entry>
+ </row>
- <entry>Set to the path of <command>xmkmf</command> if not in the
- <envar>PATH</envar>. Defaults to <literal>xmkmf
- -a</literal>.</entry>
+ <row>
+ <entry><varname>SCONS_TARGET</varname></entry>
+ <entry xml:lang="en">Last argument passed to SCons, similar to
+ <varname>MAKE_TARGET</varname>.</entry>
</row>
</tbody>
</tgroup>
</table>
- <table frame="none">
- <title>Variables for depending on individual parts of X11</title>
+ <para xml:lang="en">To make third party <filename>SConstruct</filename>
+ respect everything that is passed to SCons in
+ <varname>SCONS_ENV</varname> (that is, most importantly,
+ <varname>CC/CXX/CFLAGS/CXXFLAGS</varname>), patch
+ <filename>SConstruct</filename> so build
+ <literal>Environment</literal> is constructed like
+ this:</para>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry><varname>X_IMAKE_PORT</varname></entry>
+ <programlisting xml:lang="en">env = Environment(**ARGUMENTS)</programlisting>
- <entry>Port providing <command>imake</command> and several
- other utilities used to build X11.</entry>
- </row>
+ <para xml:lang="en">It may be then modified with
+ <literal>env.Append</literal> and
+ <literal>env.Replace</literal>.</para>
+ </sect2>
+ </sect1>
- <row>
- <entry><varname>X_LIBRARIES_PORT</varname></entry>
+ <sect1 xml:id="using-autotools">
+ <title>使用 GNU Autotools</title>
- <entry>Port providing X11 libraries.</entry>
- </row>
+ <sect2 xml:id="using-autotools-introduction">
+ <title>楔子</title>
- <row>
- <entry><varname>X_CLIENTS_PORT</varname></entry>
+ <para xml:lang="en">The various GNU autotools provide an abstraction
+ mechanism for building a piece of software over a wide
+ variety of operating systems and machine architectures.
+ Within the Ports Collection, an individual port can make use
+ of these tools via a simple construct:</para>
+
+ <programlisting xml:lang="en">USE_AUTOTOOLS= <replaceable>tool</replaceable>[:env] ...</programlisting>
+
+ <para xml:lang="en">At the time of writing, <replaceable>tool</replaceable>
+ can be one of <literal>autoconf</literal>,
+ <literal>autoheader</literal>, <literal>automake</literal>,
+ <literal>aclocal</literal>, <literal>libtoolize</literal>.
+ It can also be one the older
+ legacy of <literal>autoconf213</literal>,
+ <literal>autoheader213</literal>,
+ <literal>automake14</literal>,
+ <literal>aclocal14</literal>.</para>
+
+ <para xml:lang="en"><replaceable>env</replaceable> is used to specify that the
+ environmental variables are needed. It also adds a build
+ dependency on the tool. The relevant tool is
+ <emphasis>not</emphasis> ran as part of the
+ <buildtarget xml:lang="en">run-autotools</buildtarget> target.</para>
+
+ <para xml:lang="en">Multiple tools can be specified at once, either by
+ including them all on a single line, or using the
+ <literal>+=</literal> Makefile construct.</para>
+ </sect2>
- <entry>Port providing X clients.</entry>
- </row>
+ <sect2 xml:id="using-libtool">
+ <title xml:lang="en"><command>libtool</command> and
+ <command>libtoolize</command></title>
- <row>
- <entry><varname>X_SERVER_PORT</varname></entry>
+ <para xml:lang="en">Ports shipping with their own copy of libtool (search for
+ a file named ltmain.sh) need to have
+ <literal>USES=libtool</literal>. If a port has
+ <literal>USE_AUTOTOOLS=libtoolize</literal> it probably also
+ needs <literal>USES=libtool</literal>. See the <link linkend="uses-libtool">USES=libtool</link> section in <xref linkend="uses"/> for more details.</para>
- <entry>Port providing X server.</entry>
- </row>
+ </sect2>
- <row>
- <entry><varname>X_FONTSERVER_PORT</varname></entry>
+ <sect2 xml:id="using-libltdl">
+ <title xml:lang="en"><filename>libltdl.so</filename></title>
- <entry>Port providing font server.</entry>
- </row>
+ <para xml:lang="en">Some ports make use of the <filename>libltdl.so</filename>
+ library package, which is part of the
+ <command>libtool</command> suite. Use of this library does
+ not automatically necessitate the use of
+ <command>libtool</command> itself. If the port needs
+ <filename>libltdl.so</filename>, add a dependency on
+ it:</para>
- <row>
- <entry><varname>X_PRINTSERVER_PORT</varname></entry>
+ <programlisting xml:lang="en">LIB_DEPENDS= libltdl.so:${PORTSDIR}/devel/libltdl</programlisting>
+ </sect2>
- <entry>Port providing print server.</entry>
- </row>
+ <sect2 xml:id="using-autoconf">
+ <title xml:lang="en"><command>autoconf</command> and
+ <command>autoheader</command></title>
- <row>
- <entry><varname>X_VFBSERVER_PORT</varname></entry>
+ <para xml:lang="en">Some ports do not contain a configure script, but do
+ contain an autoconf template in
+ <filename>configure.ac</filename>. Use these
+ assignments to let <command>autoconf</command>
+ create the configure script, and also have
+ <command>autoheader</command> create template headers for
+ use by the configure script.</para>
- <entry>Port providing virtual framebuffer server.</entry>
- </row>
+ <programlisting xml:lang="en">USE_AUTOTOOLS= autoconf[:env]</programlisting>
- <row>
- <entry><varname>X_NESTSERVER_PORT</varname></entry>
+ <para xml:lang="en">and</para>
- <entry>Port providing a nested X server.</entry>
- </row>
+ <programlisting xml:lang="en">USE_AUTOTOOLS= autoheader</programlisting>
- <row>
- <entry><varname>X_FONTS_ENCODINGS_PORT</varname></entry>
+ <para xml:lang="en">which also implies the use of
+ <literal>autoconf</literal>.</para>
- <entry>Port providing encodings for fonts.</entry>
- </row>
+ <para xml:lang="en">The additional optional variables
+ <varname>AUTOCONF_ARGS</varname> and
+ <varname>AUTOHEADER_ARGS</varname> can be overridden by the
+ port <filename>Makefile</filename> if specifically
+ requested. Most ports are unlikely to need this. See
+ <filename>bsd.autotools.mk</filename> for further
+ details.</para>
+ </sect2>
- <row>
- <entry><varname>X_FONTS_MISC_PORT</varname></entry>
+ <sect2 xml:id="using-automake">
+ <title xml:lang="en"><command>automake</command> and
+ <command>aclocal</command></title>
- <entry>Port providing miscellaneous bitmap fonts.</entry>
- </row>
+ <para xml:lang="en">Some packages only contain
+ <filename>Makefile.am</filename>. These have to be
+ converted into <filename>Makefile.in</filename> using
+ <command>automake</command>, and the further processed by
+ <command>configure</command> to generate an actual
+ <filename>Makefile</filename>.</para>
- <row>
- <entry><varname>X_FONTS_100DPI_PORT</varname></entry>
+ <para xml:lang="en">Similarly, packages occasionally do not ship with
+ an included <filename>aclocal.m4</filename>, again
+ required to build the software. This can be achieved with
+ <command>aclocal</command>, which scans
+ <filename>configure.ac</filename> or
+ <filename>configure.in</filename>.</para>
+
+ <para xml:lang="en"><command>aclocal</command> has a similar relationship to
+ <command>automake</command> as <command>autoheader</command>
+ does to <command>autoconf</command>, described in the
+ previous section. <command>aclocal</command> implies the
+ use of <command>automake</command>, thus we have:</para>
+
+ <programlisting xml:lang="en">USE_AUTOTOOLS= automake[:<replaceable>env</replaceable>]</programlisting>
+
+ <para xml:lang="en">and</para>
+
+ <programlisting xml:lang="en">USE_AUTOTOOLS= aclocal</programlisting>
+
+ <para xml:lang="en">As with <command>autoconf</command> and
+ <command>autoheader</command>, both
+ <command>automake</command> and <command>aclocal</command>
+ have optional argument variables,
+ <varname>AUTOMAKE_ARGS</varname> and
+ <varname>ACLOCAL_ARGS</varname> respectively, which may be
+ overridden by the port <filename>Makefile</filename> if
+ required.</para>
+ </sect2>
+ </sect1>
- <entry>Port providing 100dpi bitmap fonts.</entry>
- </row>
+ <sect1 xml:id="using-gettext">
+ <title>使用 GNU <literal>gettext</literal></title>
- <row>
- <entry><varname>X_FONTS_75DPI_PORT</varname></entry>
+ <sect2 xml:id="using-gettext-basic">
+ <title>基本用法</title>
- <entry>Port providing 75dpi bitmap fonts.</entry>
- </row>
+ <para xml:lang="en">If the port requires <literal>gettext</literal>, set
+ <literal>USES= gettext</literal>, and the port will inherit
+ a dependency on <filename>libintl.so</filename> from
+ <package role="port">devel/gettext</package>. Other
+ values for <literal>gettext</literal> usage are listed in
+ <link linkend="uses-gettext"><literal>USES=gettext</literal></link>.</para>
- <row>
- <entry><varname>X_FONTS_CYRILLIC_PORT</varname></entry>
+ <para xml:lang="en">A rather common case is a port using
+ <literal>gettext</literal> and <command>configure</command>.
+ Generally, GNU <command>configure</command> should be able
+ to locate <literal>gettext</literal> automatically.</para>
- <entry>Port providing cyrillic bitmap fonts.</entry>
- </row>
+ <programlisting>USES= gettext
+GNU_CONFIGURE= yes</programlisting>
- <row>
- <entry><varname>X_FONTS_TTF_PORT</varname></entry>
+ <para xml:lang="en">If it ever fails to, hints at the location of
+ <literal>gettext</literal> can be passed in
+ <envar>CPPFLAGS</envar> and <envar>LDFLAGS</envar> as
+ follows:</para>
- <entry>Port providing &truetype; fonts.</entry>
- </row>
+ <programlisting>USES= gettext
+CPPFLAGS+= -I${LOCALBASE}/include
+LDFLAGS+= -L${LOCALBASE}/lib
- <row>
- <entry><varname>X_FONTS_TYPE1_PORT</varname></entry>
+GNU_CONFIGURE= yes</programlisting>
+ </sect2>
- <entry>Port providing Type1 fonts.</entry>
- </row>
+ <sect2 xml:id="using-gettext-optional">
+ <title xml:lang="en">Optional Usage</title>
+
+ <para xml:lang="en">Some software products allow for disabling
+ <acronym>NLS</acronym>. For example, through passing
+ <option>--disable-nls</option> to
+ <command>configure</command>. In that case, the port must use
+ <literal>gettext</literal> conditionally, depending on the
+ status of the <literal>NLS</literal> option. For ports of low
+ to medium complexity, use this idiom:</para>
+
+ <programlisting>GNU_CONFIGURE= yes
+
+OPTIONS_DEFINE= NLS
+OPTIONS_SUB= yes
+
+NLS_USES= gettext
+NLS_CONFIGURE_ENABLE= nls
+.include &lt;bsd.port.mk&gt;</programlisting>
+
+ <para xml:lang="en">Or using the older way of using options:</para>
+
+ <programlisting>GNU_CONFIGURE= yes
+
+OPTIONS_DEFINE= NLS
+
+.include &lt;bsd.port.options.mk&gt;
+
+.if ${PORT_OPTIONS:MNLS}
+USES+= gettext
+PLIST_SUB+= NLS=""
+.else
+CONFIGURE_ARGS+= --disable-nls
+PLIST_SUB+= NLS="@comment "
+.endif
+
+.include &lt;bsd.port.mk&gt;</programlisting>
+
+ <para xml:lang="en">The next item on the to-do list is to arrange so that
+ the message catalog files are included in the packing list
+ conditionally. The <filename>Makefile</filename> part of
+ this task is already provided by the idiom. It is explained
+ in the section on <link linkend="plist-sub">advanced
+ <filename>pkg-plist</filename> practices</link>. In a
+ nutshell, each occurrence of <literal>%%NLS%%</literal> in
+ <filename>pkg-plist</filename> will be replaced by
+ <quote><literal>@comment </literal></quote> if NLS is
+ disabled, or by a null string if NLS is enabled.
+ Consequently, the lines prefixed by
+ <literal>%%NLS%%</literal> will become mere comments in the
+ final packing list if NLS is off; otherwise the prefix will
+ be just left out. Then insert
+ <literal>%%NLS%%</literal> before each path to a message
+ catalog file in <filename>pkg-plist</filename>. For
+ example:</para>
+
+ <programlisting>%%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo
+%%NLS%%share/locale/no/LC_MESSAGES/foobar.mo</programlisting>
+
+ <para xml:lang="en">In high complexity cases, more advanced techniques
+ may be needed, such as
+ <link linkend="plist-dynamic">dynamic packing list
+ generation</link>.</para>
+ </sect2>
+
+ <sect2 xml:id="using-gettext-catalog-directories">
+ <title xml:lang="en">Handling Message Catalog Directories</title>
+
+ <para xml:lang="en">There is a point to note about installing message
+ catalog files. The target directories for them, which
+ reside under
+ <filename>LOCALBASE/share/locale</filename>,
+ must not be created and removed by a port. The most
+ popular languages have their respective directories listed
+ in
+ <filename>PORTSDIR/Templates/BSD.local.dist</filename>.
+ The directories for many other languages are governed by the
+ <package role="port">devel/gettext</package> port.
+ Consult its <filename>pkg-plist</filename> and see whether
+ the port is going to install a message catalog file for a
+ unique language.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="using-perl">
+ <title>使用 <application>Perl</application></title>
+
+ <para xml:lang="en">If <varname>MASTER_SITES</varname> is set to
+ <literal>CPAN</literal>, the correct subdirectory is usually
+ selected automatically. If the default subdirectory is wrong,
+ <literal>CPAN/Module</literal> can be used to change it.
+ <varname>MASTER_SITES</varname> can also be set to the old
+ <varname>MASTER_SITE_PERL_CPAN</varname>, then the preferred
+ value of <varname>MASTER_SITE_SUBDIR</varname> is the
+ top-level hierarchy name. For example, the recommended value
+ for <literal>p5-Module-Name</literal> is
+ <literal>Module</literal>. The top-level hierarchy can be
+ examined at <link xlink:href="http://cpan.org/modules/by-module/">cpan.org</link>.
+ This keeps the port working when the author of the module
+ changes.</para>
+
+ <para xml:lang="en">The exception to this rule is when the relevant directory
+ does not exist or the distfile does not exist in that
+ directory. In such case, using author's id as
+ <varname>MASTER_SITE_SUBDIR</varname> is allowed.
+ The <literal>CPAN:AUTHOR</literal> macro can be used, which will
+ be translated to the hashed author directory. For example,
+ <literal>CPAN:AUTHOR</literal> will be converted to
+ <literal>authors/id/A/AU/AUTHOR</literal>.</para>
+
+ <para xml:lang="en">When a port needs <application>Perl</application> support,
+ it must set <literal>USES=perl5</literal> with the optional
+ <varname>USE_PERL5</varname> described in <link linkend="uses-perl5">the perl5 USES description</link>.</para>
+
+ <table frame="none" xml:id="using-perl-variables">
+ <title xml:lang="en">Read-Only Variables for Ports That Use
+ <application>Perl</application></title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>唯讀變數</entry>
+ <entry xml:lang="en">Means</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><varname>PERL</varname></entry>
+ <entry xml:lang="en">The full path of the Perl 5 interpreter,
+ either in the system or installed from a port, but
+ without the version number. Use this when the software
+ needs the path to the <application>Perl</application>
+ interpreter. To replace
+ <quote><literal>#!</literal></quote>lines in scripts,
+ use <link linkend="uses-shebangfix">USES=shebangfix</link>.</entry>
+ </row>
+
+ <row>
+ <entry><varname>PERL_VERSION</varname></entry>
+ <entry xml:lang="en">The full version of Perl installed (for example,
+ <literal>5.8.9</literal>).</entry>
+ </row>
+
+ <row>
+ <entry><varname>PERL_LEVEL</varname></entry>
+ <entry xml:lang="en">The installed Perl version as
+ an integer of the form <literal>MNNNPP</literal>
+ (for example, <literal>500809</literal>).</entry>
+ </row>
+
+ <row>
+ <entry><varname>PERL_ARCH</varname></entry>
+ <entry xml:lang="en">Where Perl stores architecture
+ dependent libraries. Defaults to
+ <literal>${ARCH}-freebsd</literal>.</entry>
+ </row>
+
+ <row>
+ <entry><varname>PERL_PORT</varname></entry>
+ <entry xml:lang="en">Name of the Perl port that is installed (for
+ example, <literal>perl5</literal>).</entry>
+ </row>
+
+ <row>
+ <entry><varname>SITE_PERL</varname></entry>
+ <entry xml:lang="en">Directory name where site specific
+ Perl packages go. This value is
+ added to <varname>PLIST_SUB</varname>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <note>
+ <para xml:lang="en">Ports of Perl modules which do not have an official
+ website must link to <systemitem>cpan.org</systemitem> in
+ the WWW line of <filename>pkg-descr</filename>. The
+ preferred URL form is
+ <literal>http://search.cpan.org/dist/Module-Name/</literal>
+ (including the trailing slash).</para>
+ </note>
+
+ <note>
+ <para xml:lang="en">Do not use <literal>${SITE_PERL}</literal> in dependency
+ declarations. Doing so assumes that
+ <filename>perl5.mk</filename> has been included, which is
+ not always true. Ports depending on this port will have
+ incorrect dependencies if this port's files move later in an
+ upgrade. The right way to declare Perl module dependencies
+ is shown in the example below.</para>
+ </note>
+
+ <example xml:id="use-perl-dependency-example">
+ <title>Perl 相依性範例</title>
+
+ <programlisting>p5-IO-Tee&gt;=0.64:${PORTSDIR}/devel/p5-IO-Tee</programlisting>
+ </example>
+
+ <para xml:lang="en">For Perl ports that install manual pages, the macro
+ <varname>PERL5_MAN3</varname> can be used
+ inside <filename>pkg-plist</filename>. For example,</para>
+
+ <programlisting>lib/perl5/5.14/man/man3/AnyEvent::I3.3.gz</programlisting>
+
+ <para xml:lang="en">can be replaced with</para>
+
+ <programlisting>%%PERL5_MAN3%%/AnyEvent::I3.3.gz</programlisting>
+
+ <note>
+ <para xml:lang="en">There are no <varname>PERL5_MANx</varname> macros for the
+ other sections (<replaceable>x</replaceable> in
+ <literal>1</literal>, <literal>2</literal> and
+ <literal>4</literal> to <literal>9</literal>) because those
+ get installed in the regular directories.</para>
+ </note>
+ </sect1>
+
+ <sect1 xml:id="using-x11">
+ <title>使用 X11</title>
+
+ <sect2 xml:id="x11-variables">
+ <title xml:lang="en">X.Org Components</title>
+
+ <para xml:lang="en">The X11 implementation available in The Ports Collection
+ is X.Org. If the application depends on X components, set
+ <varname>USE_XORG</varname> to the list of required
+ components. Available components, at the time of writing,
+ are:</para>
+
+ <para xml:lang="en"><literal>bigreqsproto compositeproto damageproto dmx
+ dmxproto dri2proto dri3proto evieproto fixesproto
+ fontcacheproto fontenc fontsproto fontutil glproto ice
+ inputproto kbproto libfs oldx pciaccess pixman presentproto
+ printproto randrproto recordproto renderproto resourceproto
+ scrnsaverproto sm trapproto videoproto x11 xau xaw xaw6 xaw7
+ xbitmaps xcb xcmiscproto xcomposite xcursor xdamage xdmcp
+ xevie xext xextproto xf86bigfontproto xf86dgaproto
+ xf86driproto xf86miscproto xf86rushproto xf86vidmodeproto
+ xfixes xfont xfontcache xft xi xinerama xineramaproto
+ xkbfile xkbui xmu xmuu xorg-macros xorg-server xp xpm
+ xprintapputil xprintutil xproto xproxymngproto xrandr
+ xrender xres xscrnsaver xshmfence xt xtrans xtrap xtst xv
+ xvmc xxf86dga xxf86misc xxf86vm</literal>.</para>
+
+ <para xml:lang="en">Always up-to-date list can be found in
+ <filename>/usr/ports/Mk/bsd.xorg.mk</filename>.</para>
+
+ <para xml:lang="en">The Mesa Project is an effort to provide free OpenGL
+ implementation. To specify a dependency on various
+ components of this project, use <varname>USE_GL</varname>.
+ Valid options are:
+ <literal>egl, gl, glesv2, glew, glu, glut, glw</literal> and
+ <literal>linux</literal>. For backwards compatibility, the
+ value of <literal>yes</literal> maps to
+ <literal>glu</literal>.</para>
+
+ <example xml:id="use-xorg-example">
+ <title><varname>USE_XORG</varname> 範例</title>
+
+ <programlisting xml:lang="en">USE_XORG= xrender xft xkbfile xt xaw
+USE_GL= glu</programlisting>
+ </example>
+
+ <table frame="none" xml:id="using-xorg-variables">
+ <title xml:lang="en">Variables for Ports That Use X</title>
+
+ <tgroup cols="2">
+ <tbody>
<row>
- <entry><varname>X_MANUALS_PORT</varname></entry>
+ <entry xml:lang="en"><varname>USES= imake</varname></entry>
+ <entry xml:lang="en">The port uses <command>imake</command>.</entry>
+ </row>
- <entry>Port providing developer oriented manual pages</entry>
+ <row>
+ <entry><varname>XMKMF</varname></entry>
+ <entry xml:lang="en">Set to the path of <command>xmkmf</command> if
+ not in the <envar>PATH</envar>. Defaults to
+ <literal>xmkmf -a</literal>.</entry>
</row>
</tbody>
</tgroup>
</table>
<example xml:id="using-x11-vars">
- <title>Using some X11 related variables in port</title>
- <programlisting># Use X11 libraries and depend on
-# font server as well as cyrillic fonts.
-RUN_DEPENDS= ${LOCALBASE}/bin/xfs:${X_FONTSERVER_PORT} \
- ${LOCALBASE}/lib/X11/fonts/cyrillic/crox1c.pcf.gz:${X_FONTS_CYRILLIC_PORT}
+ <title>使用 X11 相關變數</title>
-USE_XORG= yes</programlisting>
+ <programlisting># Use some X11 libraries
+USE_XORG= x11 xpm</programlisting>
</example>
+ </sect2>
- </sect2>
+ <sect2 xml:id="x11-motif">
+ <title xml:lang="en">Ports That Require Motif</title>
+
+ <para xml:lang="en">If the port requires a Motif library, define
+ <varname>USES= motif</varname> in the
+ <filename>Makefile</filename>. Default Motif implementation
+ is
+ <package role="port">x11-toolkits/open-motif</package>.
+ Users can choose
+ <package role="port">x11-toolkits/lesstif</package>
+ instead by setting <varname>WANT_LESSTIF</varname>
+ in their <filename>make.conf</filename>.</para>
+
+ <para xml:lang="en"><varname>MOTIFLIB</varname> will be set by
+ <filename>motif.mk</filename> to reference the
+ appropriate Motif library. Please patch the source of the
+ port to use <literal>${MOTIFLIB}</literal> wherever
+ the Motif library is referenced in the original
+ <filename>Makefile</filename> or
+ <filename>Imakefile</filename>.</para>
+
+ <para xml:lang="en">There are two common cases:</para>
- <sect2 xml:id="x11-motif">
- <title>Ports that require Motif</title>
+ <itemizedlist>
+ <listitem>
+ <para xml:lang="en">If the port refers to the Motif library as
+ <literal>-lXm</literal> in its
+ <filename>Makefile</filename> or
+ <filename>Imakefile</filename>, substitute
+ <literal>${MOTIFLIB}</literal> for it.</para>
+ </listitem>
- <para>If your port requires a Motif library, define
- <varname>USE_MOTIF</varname> in the <filename>Makefile</filename>.
- Default Motif implementation is
- <package>x11-toolkits/open-motif</package>.
- Users can choose
- <package>x11-toolkits/lesstif</package> instead
- by setting <varname>WANT_LESSTIF</varname> variable.</para>
+ <listitem>
+ <para xml:lang="en">If the port uses <literal>XmClientLibs</literal> in
+ its <filename>Imakefile</filename>, change it to
+ <literal>${MOTIFLIB} ${XTOOLLIB}
+ ${XLIB}</literal>.</para>
+ </listitem>
+ </itemizedlist>
- <para>The <varname>MOTIFLIB</varname> variable will be set by
- <filename>bsd.port.mk</filename> to reference the appropriate
- Motif library. Please patch the source of your port to
- use <literal>&dollar;{MOTIFLIB}</literal> wherever the Motif library is referenced in the original
- <filename>Makefile</filename> or
- <filename>Imakefile</filename>.</para>
+ <para xml:lang="en">Note that <varname>MOTIFLIB</varname> (usually) expands
+ to <literal>-L/usr/local/lib -lXm -lXp</literal> or
+ <literal>/usr/local/lib/libXm.a</literal>, so there is no
+ need to add <literal>-L</literal> or <literal>-l</literal>
+ in front.</para>
+ </sect2>
- <para>There are two common cases:</para>
+ <sect2 xml:id="x11-fonts">
+ <title>X11 字型</title>
- <itemizedlist>
- <listitem>
- <para>If the port refers to the Motif library as
- <literal>-lXm</literal> in its <filename>Makefile</filename> or
- <filename>Imakefile</filename>, simply substitute
- <literal>&dollar;{MOTIFLIB}</literal> for it.</para>
- </listitem>
+ <para xml:lang="en">If the port installs fonts for the X Window System, put
+ them in
+ <filename>LOCALBASE/lib/X11/fonts/local</filename>.</para>
+ </sect2>
- <listitem>
- <para>If the port uses <literal>XmClientLibs</literal> in its
- <filename>Imakefile</filename>, change it to
- <literal>&dollar;{MOTIFLIB} &dollar;{XTOOLLIB}
- &dollar;{XLIB}</literal>.</para>
- </listitem>
+ <sect2 xml:id="x11-fake-display">
+ <title xml:lang="en">Getting a Fake <envar>DISPLAY</envar> with Xvfb</title>
- </itemizedlist>
+ <para xml:lang="en">Some applications require a working X11 display for
+ compilation to succeed. This pose a problem for machines
+ that operate headless. When this variable is used,
+ the build infrastructure will start the virtual framebuffer
+ X server. The working <envar>DISPLAY</envar> is then passed
+ to the build. See <link linkend="uses-display"><literal>USES=display</literal></link>
+ for the possible arguments.</para>
- <para>Note that <varname>MOTIFLIB</varname> (usually) expands to
- <literal>-L/usr/X11R6/lib -lXm</literal> or
- <literal>/usr/X11R6/lib/libXm.a</literal>, so there is no need to
- add <literal>-L</literal> or <literal>-l</literal> in front.</para>
+ <programlisting>USES= display</programlisting>
+ </sect2>
- </sect2>
+ <sect2 xml:id="desktop-entries">
+ <title xml:lang="en">Desktop Entries</title>
+
+ <para xml:lang="en">Desktop entries (<link xlink:href="http://standards.freedesktop.org/desktop-entry-spec/latest/">a
+ Freedesktop standard</link>) provide a way to
+ automatically adjust desktop features when a new program is
+ installed, without requiring user intervention. For
+ example, newly-installed programs automatically appear in
+ the application menus of compatible desktop environments.
+ Desktop entries originated in the
+ <application>GNOME</application> desktop environment, but
+ are now a standard and also work with
+ <application>KDE</application> and
+ <application>Xfce</application>. This bit of automation
+ provides a real benefit to the user, and desktop entries are
+ encouraged for applications which can be used in a desktop
+ environment.</para>
+
+ <sect3 xml:id="desktop-entries-predefined">
+ <title xml:lang="en">Using Predefined <filename>.desktop</filename>
+ Files</title>
+
+ <para xml:lang="en">Ports that include predefined
+ <filename><replaceable>*</replaceable>.desktop</filename>
+ must include those files in <filename>pkg-plist</filename>
+ and install them in the
+ <filename>$LOCALBASE/share/applications</filename>
+ directory. The <link linkend="install-macros"><varname>INSTALL_DATA</varname>
+ macro</link> is useful for installing these
+ files.</para>
+ </sect3>
+
+ <sect3 xml:id="updating-desktop-database">
+ <title xml:lang="en">Updating Desktop Database</title>
+
+ <para xml:lang="en">If a port has a MimeType entry in its
+ <filename><replaceable>portname</replaceable>.desktop</filename>,
+ the desktop database must be updated after install and
+ deinstall. To do this, define <varname>USES</varname>=
+ desktop-file-utils.</para>
+ </sect3>
+
+ <sect3 xml:id="desktop-entries-macro">
+ <title xml:lang="en">Creating Desktop Entries with
+ <varname>DESKTOP_ENTRIES</varname></title>
+
+ <para xml:lang="en">Desktop entries can be easily created for applications
+ by using <varname>DESKTOP_ENTRIES</varname>. A
+ file named
+ <filename><replaceable>name</replaceable>.desktop</filename>
+ will be created, installed, and added to
+ <filename>pkg-plist</filename> automatically. Syntax
+ is:</para>
+
+ <programlisting xml:lang="en">DESKTOP_ENTRIES= "NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify</programlisting>
+
+ <para xml:lang="en">The list of possible categories is available on the
+ <link xlink:href="http://standards.freedesktop.org/menu-spec/latest/apa.html">Freedesktop
+ website</link>. <varname>StartupNotify</varname>
+ indicates whether the application is compatible with
+ <emphasis>startup notifications</emphasis>. These are
+ typically a graphic indicator like a clock that appear at
+ the mouse pointer, menu, or panel to give the user an
+ indication when a program is starting. A program that is
+ compatible with startup notifications clears the indicator
+ after it has started. Programs that are not compatible
+ with startup notifications would never clear the indicator
+ (potentially confusing and infuriating the user), and
+ must have <varname>StartupNotify</varname> set to
+ <literal>false</literal> so the indicator is not shown at
+ all.</para>
+
+ <para xml:lang="en">Example:</para>
+
+ <programlisting xml:lang="en">DESKTOP_ENTRIES= "ToME" "Roguelike game based on JRR Tolkien's work" \
+ "${DATADIR}/xtra/graf/tome-128.png" \
+ "tome -v -g" "Application;Game;RolePlaying;" \
+ false</programlisting>
+ </sect3>
+ </sect2>
+ </sect1>
- <sect2>
- <title>X11 fonts</title>
+ <sect1 xml:id="using-gnome">
+ <title>使用 GNOME</title>
- <para>If your port installs fonts for the X Window System, put them in
- <filename>LOCALBASE/lib/X11/fonts/local</filename>.</para>
+ <sect2>
+ <title>楔子</title>
- </sect2>
+ <para xml:lang="en">This chapter explains the <acronym>GNOME</acronym>
+ framework as used by ports. The framework can be loosely
+ divided into the base components, <acronym>GNOME</acronym>
+ desktop components, and a few special macros that simplify the
+ work of port maintainers.</para>
- <sect2>
- <title>Getting fake <envar>DISPLAY</envar> using Xvfb</title>
+ <para xml:lang="en">While developing a port or changing one, please set</para>
- <para>Some applications require a working X11 display for compilation to
- succeed. This pose a problem for machines which operates headless.
- When the following variable is used, the build infrastructure will
- start the virtual framebuffer
- X server. The working <envar>DISPLAY</envar> is then passed
- to the build.</para>
+ <programlisting>DEVELOPER=yes</programlisting>
- <programlisting>USE_DISPLAY= yes</programlisting>
+ <para xml:lang="en">
+ in the environment or in <filename>/etc/make.conf</filename>.
+ This causes the ports framework to enable additional
+ checks.</para>
+ </sect2>
- </sect2>
+ <sect2 xml:id="use-gnome">
+ <title xml:lang="en">Using <varname>USE_GNOME</varname></title>
+
+ <para xml:lang="en">Adding this variable to the port allows the use of
+ the macros and components defined in
+ <filename>bsd.gnome.mk</filename>. The code in
+ <filename>bsd.gnome.mk</filename> adds the needed
+ build-time, run-time or library dependencies
+ or the handling of special files.
+ <acronym>GNOME</acronym> applications under FreeBSD use the
+ <varname>USE_GNOME</varname> infrastructure. Include all the
+ needed components as a space-separated list. The
+ <varname>USE_GNOME</varname> components are divided into
+ these virtual lists: basic components, GNOME 3 components
+ and legacy components. If the port needs only GTK3 libraries,
+ this is the shortest way to define it:</para>
+
+ <programlisting>USE_GNOME= gtk30</programlisting>
+
+ <para xml:lang="en"><varname>USE_GNOME</varname> components automatically
+ add the dependencies they need. Please see
+ <xref linkend="gnome-components"/> for an exhaustive
+ list of all <varname>USE_GNOME</varname> components and which
+ other components they imply and their dependencies.</para>
+
+ <para xml:lang="en">Here is an example <filename>Makefile</filename> for a
+ GNOME port that uses many of the techniques outlined in this
+ document. Please use it as a guide for creating new
+ ports.</para>
+
+ <programlisting># $FreeBSD$
+
+PORTNAME= regexxer
+PORTVERSION= 0.10
+CATEGORIES= devel textproc gnome
+MASTER_SITES= GNOME
+
+MAINTAINER= kwm@FreeBSD.org
+COMMENT= Interactive tool for performing search and replace operations
+
+USES= gettext gmake pathfix pkgconfig tar:xz
+GNU_CONFIGURE= yes
+USE_GNOME= gnomeprefix intlhack gtksourceviewmm3
+CPPFLAGS+= -I${LOCALBASE}/include
+LDFLAGS+= -L${LOCALBASE}/lib
+INSTALLS_ICONS= yes
+
+GLIB_SCHEMAS= org.regexxer.gschema.xml
- <sect2 xml:id="desktop-entries">
- <title>Desktop entries</title>
+.include &lt;bsd.port.mk&gt;</programlisting>
- <para>可藉由設定
- <varname>DESKTOP_ENTRIES</varname> 變數,以輕鬆設定 port 的 X 選單項目
- (Desktop Entries,請參閱 <link xlink:href="http://standards.freedesktop.org/desktop-entry-spec/latest/">
- Freedesktop standard</link>)。 這些項目會在相應的桌面環境如 GNOME
- 或 KDE 的應用程式選單中出現。 <filename>.desktop</filename> 檔案
- 將會被建立、安裝以及自動加入 <filename>pkg-plist</filename>
- 中。語法為:</para>
+ <note>
+ <para xml:lang="en">The <varname>USE_GNOME</varname> macro without any
+ arguments does not add any dependencies to the port.
+ <varname>USE_GNOME</varname> cannot be set after
+ <filename>bsd.port.pre.mk</filename>.</para>
+ </note>
+ </sect2>
- <programlisting>DESKTOP_ENTRIES= "NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify</programlisting>
+ <sect2>
+ <title>變數</title>
- <para>可供使用的分類可參考 <link xlink:href="http://standards.freedesktop.org/menu-spec/latest/apa.html">
- Freedesktop 網站</link>。 而 <varname>StartupNotify</varname>
- 變數會決定程式,是否支援 startup noficication 的環境。
- </para>
+ <para xml:lang="en">This section explains which macros are available and how
+ they are used. Like they are used in the above example. The
+ <xref linkend="gnome-components"/> has a more in-depth
+ explanation. <varname>USE_GNOME</varname> has to be set for
+ these macros to be of use.</para>
- <para>範例:</para>
+ <variablelist>
+ <varlistentry>
+ <term xml:id="gnome-icons"><varname>INSTALLS_ICONS</varname></term>
- <programlisting>DESKTOP_ENTRIES= "ToME" "Roguelike game based on JRR Tolkien's work" \
- "${DATADIR}/xtra/graf/tome-128.png" \
- "tome -v -g" "Application;Game;RolePlaying" \
- false</programlisting>
+ <listitem>
+ <para xml:lang="en"><application>GTK+</application> ports which install
+ <application>Freedesktop</application>-style icons to
+ <filename>${LOCALBASE}/share/icons</filename> should use
+ this macro to ensure that the icons are cached and will
+ display correctly. The cache file is named
+ <filename>icon-theme.cache</filename>. Do not include
+ that file in <filename>pkg-plist</filename>. This macro
+ handles that automatically. This macro is not needed
+ for <application>Qt</application>, which use a
+ internal method.</para>
+ </listitem>
+ </varlistentry>
- </sect2>
+ <varlistentry>
+ <term xml:id="gnome-glibschema"><varname>GLIB_SCHEMAS</varname></term>
- </sect1>
+ <listitem>
+ <para xml:lang="en">List of all the glib schema files the port installs.
+ The macro will add the files to the port plist and
+ handle the registration of these files on install and
+ deinstall.</para>
+
+ <para xml:lang="en">The glib schema files are written in
+ <acronym>XML</acronym> and end with the
+ <filename>gschema.xml</filename> extension. They are
+ installed in the
+ <filename>share/glib-2.0/schemas/</filename> directory.
+ These schema files contain all application config values
+ with there default settings. The actual database used
+ by the applications is built by
+ <application>glib-compile-schema</application>, which is
+ run by the <varname>GLIB_SCHEMAS</varname> macro.</para>
+
+ <programlisting>GLIB_SCHEMAS=foo.gschema.xml</programlisting>
- <sect1 xml:id="using-gnome">
- <title>Using GNOME</title>
+ <note>
+ <para xml:lang="en">Do not add glib schemas to the
+ <filename>pkg-plist</filename>. If they are listed in
+ <filename>pkg-plist</filename>, they will not be
+ registered and the applications might not work
+ properly.</para>
+ </note>
+ </listitem>
+ </varlistentry>
- <para>The FreeBSD/GNOME project uses its own set of variables
- to define which GNOME components a
- particular port uses. A
- <link xlink:href="http://www.FreeBSD.org/gnome/docs/porting.html">comprehensive
- list of these variables</link> exists within the FreeBSD/GNOME
- project's homepage.</para>
+ <varlistentry>
+ <term xml:id="gnome-gconfschema"><varname>GCONF_SCHEMAS</varname></term>
- </sect1>
+ <listitem>
+ <para xml:lang="en">List all the gconf schema files. The macro will add
+ the schema files to the port plist and will handle their
+ registration on install and deinstall.</para>
+
+ <para xml:lang="en">GConf is the <acronym>XML</acronym>-based database
+ that virtually all GNOME applications use for storing
+ their settings. These files are installed into the
+ <filename>etc/gconf/schemas</filename> directory. This
+ database is defined by installed schema files that are
+ used to generate <filename>%gconf.xml</filename> key
+ files. For each schema file installed by the port,
+ there be an entry in the
+ <filename>Makefile</filename>:</para>
+
+ <programlisting xml:lang="en">GCONF_SCHEMAS=my_app.schemas my_app2.schemas my_app3.schemas</programlisting>
- <sect1 xml:id="using-kde">
- <title>Using KDE</title>
+ <note>
+ <para xml:lang="en">Gconf schemas are listed in the
+ <varname>GCONF_SCHEMAS</varname> macro rather than
+ <filename>pkg-plist</filename>. If they are listed in
+ <filename>pkg-plist</filename>, they will not be
+ registered and the applications might not work
+ properly.</para>
+ </note>
+ </listitem>
+ </varlistentry>
- <sect2 xml:id="kde-variables">
- <title>Variable definitions</title>
+ <varlistentry>
+ <term xml:id="gnome-omf"><varname>INSTALLS_OMF</varname></term>
- <table frame="none">
- <title>Variables for ports that use KDE</title>
+ <listitem>
+ <para xml:lang="en">Open Source Metadata Framework
+ (<acronym>OMF</acronym>) files are commonly used by
+ GNOME 2 applications. These files contain the
+ application help file information, and require special
+ processing by ScrollKeeper/rarian. To properly register
+ <acronym>OMF</acronym> files when installing GNOME
+ applications from packages, make sure that
+ <varname>omf</varname> files are listed in
+ <varname>pkg-plist</varname> and that the port
+ <filename>Makefile</filename> has
+ <varname>INSTALLS_OMF</varname> defined:</para>
+
+ <programlisting>INSTALLS_OMF=yes</programlisting>
+
+ <para xml:lang="en">When set, <filename>bsd.gnome.mk</filename>
+ automatically scans <filename>pkg-plist</filename> and
+ adds appropriate <literal>@exec</literal> and
+ <literal>@unexec</literal> directives for each
+ <filename>.omf</filename> to track in the
+ <acronym>OMF</acronym> registration database.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="gnome-components">
+ <title>GNOME 元件</title>
+
+ <para xml:lang="en">For further help with a GNOME port, look at some of the
+ <link xlink:href="@@URL_RELPREFIX@@/ports/gnome.html">existing
+ ports</link> for examples. The
+ <link xlink:href="@@URL_RELPREFIX@@/gnome/">FreeBSD GNOME
+ page</link> has contact information if more help is
+ needed. The components are divided into GNOME components
+ that are currently in use and legacy components. If the
+ component supports argument, they are listed between
+ parenthesis in the description. The first is the default.
+ "Both" is shown if the component defaults to adding to both
+ build and run dependencies.</para>
+
+ <table xml:id="gnome-components-list">
+ <title>GNOME 元件</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>元件</entry>
+ <entry>相關程式</entry>
+ <entry>描述</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>atk</literal></entry>
+ <entry>accessibility/atk</entry>
+ <entry xml:lang="en">Accessibility toolkit (ATK)</entry>
+ </row>
+
+ <row>
+ <entry><literal>atkmm</literal></entry>
+ <entry>accessibility/atkmm</entry>
+ <entry xml:lang="en">c++ bindings for atk</entry>
+ </row>
+
+ <row>
+ <entry><literal>cairo</literal></entry>
+ <entry>graphics/cairo</entry>
+ <entry xml:lang="en">Vector graphics library with cross-device output
+ support</entry>
+ </row>
+
+ <row>
+ <entry><literal>cairomm</literal></entry>
+ <entry>graphics/cairomm</entry>
+ <entry xml:lang="en">c++ bindings for cairo</entry>
+ </row>
+
+ <row>
+ <entry><literal>dconf</literal></entry>
+ <entry>devel/dconf</entry>
+ <entry xml:lang="en">Configuration database system
+ (both, build, run)</entry>
+ </row>
+
+ <row>
+ <entry><literal>evolutiondataserver3</literal></entry>
+ <entry xml:lang="en">databases/evolution-data-server</entry>
+ <entry xml:lang="en">Data backends for the Evolution integrated
+ mail/PIM suite</entry>
+ </row>
+
+ <row>
+ <entry><literal>gdkpixbuf2</literal></entry>
+ <entry>graphics/gdk-pixbuf2</entry>
+ <entry xml:lang="en">Graphics library for GTK+</entry>
+ </row>
+
+ <row>
+ <entry><literal>glib20</literal></entry>
+ <entry>devel/glib20</entry>
+ <entry xml:lang="en">GNOME core library
+ <literal>glib20</literal></entry>
+ </row>
+
+ <row>
+ <entry><literal>glibmm</literal></entry>
+ <entry>devel/glibmm</entry>
+ <entry xml:lang="en">c++ bindings for glib20</entry>
+ </row>
+
+ <row>
+ <entry><literal>gnomecontrolcenter3</literal></entry>
+ <entry>sysutils/gnome-control-center</entry>
+ <entry xml:lang="en">GNOME 3 Control Center</entry>
+ </row>
+
+ <row>
+ <entry><literal>gnomedesktop3</literal></entry>
+ <entry>x11/gnome-desktop</entry>
+ <entry>GNOME 3 桌面 UI 函式庫</entry>
+ </row>
+
+ <row>
+ <entry><literal>gsound</literal></entry>
+ <entry>audio/gsound</entry>
+ <entry xml:lang="en">GObject library for playing system sounds
+ (both, build, run)</entry>
+ </row>
+
+ <row>
+ <entry><literal>gtk-update-icon-cache</literal></entry>
+ <entry>graphics/gtk-update-icon-cache</entry>
+ <entry xml:lang="en">Gtk-update-icon-cache utility from the Gtk+
+ toolkit</entry>
+ </row>
+
+ <row>
+ <entry><literal>gtk20</literal></entry>
+ <entry>x11-toolkits/gtk20</entry>
+ <entry xml:lang="en">Gtk+ 2 toolkit</entry>
+ </row>
+
+ <row>
+ <entry><literal>gtk30</literal></entry>
+ <entry>x11-toolkits/gtk30</entry>
+ <entry xml:lang="en">Gtk+ 3 toolkit</entry>
+ </row>
+
+ <row>
+ <entry><literal>gtkmm20</literal></entry>
+ <entry>x11-toolkits/gtkmm20</entry>
+ <entry xml:lang="en">c++ bindings 2.0 for the gtk20 toolkit</entry>
+ </row>
+
+ <row>
+ <entry><literal>gtkmm24</literal></entry>
+ <entry>x11-toolkits/gtkmm24</entry>
+ <entry xml:lang="en">c++ bindings 2.4 for the gtk20 toolkit</entry>
+ </row>
+
+ <row>
+ <entry><literal>gtkmm30</literal></entry>
+ <entry xml:lang="en">x11-toolkits/gtkmm30</entry>
+ <entry xml:lang="en">c++ bindings 3.0 for the gtk30 toolkit</entry>
+ </row>
+
+ <row>
+ <entry><literal>gtksourceview2</literal></entry>
+ <entry>x11-toolkits/gtksourceview2</entry>
+ <entry xml:lang="en">Widget that adds syntax highlighting to
+ GtkTextView</entry>
+ </row>
+
+ <row>
+ <entry><literal>gtksourceview3</literal></entry>
+ <entry>x11-toolkits/gtksourceview3</entry>
+ <entry xml:lang="en">Text widget that adds syntax highlighting to
+ the GtkTextView widget</entry>
+ </row>
+
+ <row>
+ <entry><literal>gtksourceviewmm3</literal></entry>
+ <entry>x11-toolkits/gtksourceviewmm3</entry>
+ <entry xml:lang="en">c++ bindings for the gtksourceview3 library</entry>
+ </row>
+
+ <row>
+ <entry><literal>gvfs</literal></entry>
+ <entry>devel/gvfs</entry>
+ <entry>GNOME 虛擬檔案系統</entry>
+ </row>
+
+ <row>
+ <entry><literal>intltool</literal></entry>
+ <entry>textproc/intltool</entry>
+ <entry xml:lang="en">Tool for internationalization (also see
+ intlhack)</entry>
+ </row>
+
+ <row>
+ <entry><literal>introspection</literal></entry>
+ <entry>devel/gobject-introspection</entry>
+ <entry xml:lang="en">Basic introspection bindings and tools to
+ generate introspection bindings. Most of the time
+ :build is enough, :both/:run is only need for
+ applications that use introspection bindings.
+ (both, build, run)</entry>
+ </row>
+
+ <row>
+ <entry><literal>libgda5</literal></entry>
+ <entry>databases/libgda5</entry>
+ <entry xml:lang="en">Provides uniform access to different kinds of
+ data sources</entry>
+ </row>
+
+ <row>
+ <entry><literal>libgda5-ui</literal></entry>
+ <entry>databases/libgda5-ui</entry>
+ <entry xml:lang="en">UI library from the libgda5 library</entry>
+ </row>
+
+ <row>
+ <entry><literal>libgdamm5</literal></entry>
+ <entry>databases/libgdamm5</entry>
+ <entry xml:lang="en">c++ bindings for the libgda5 library</entry>
+ </row>
+
+ <row>
+ <entry><literal>libgsf</literal></entry>
+ <entry>devel/libgsf</entry>
+ <entry xml:lang="en">Extensible I/O abstraction for dealing with
+ structured file formats</entry>
+ </row>
+
+ <row>
+ <entry><literal>librsvg2</literal></entry>
+ <entry>graphics/librsvg2</entry>
+ <entry xml:lang="en">Library for parsing and rendering SVG
+ vector-graphic files</entry>
+ </row>
+
+ <row>
+ <entry><literal>libsigc++20</literal></entry>
+ <entry>devel/libsigc++20</entry>
+ <entry xml:lang="en">Callback Framework for C++</entry>
+ </row>
+
+ <row>
+ <entry><literal>libxml++26</literal></entry>
+ <entry>textproc/libxml++26</entry>
+ <entry xml:lang="en">c++ bindings for the libxml2 library</entry>
+ </row>
+
+ <row>
+ <entry><literal>libxml2</literal></entry>
+ <entry>textproc/libxml2</entry>
+ <entry xml:lang="en">XML parser library (both, build, run)</entry>
+ </row>
+
+ <row>
+ <entry><literal>libxslt</literal></entry>
+ <entry>textproc/libxslt</entry>
+ <entry xml:lang="en">XSLT C library (both, build, run)</entry>
+ </row>
+
+ <row>
+ <entry><literal>metacity</literal></entry>
+ <entry>x11-wm/metacity</entry>
+ <entry>GNOME 視窗管理員</entry>
+ </row>
+
+ <row>
+ <entry><literal>nautilus3</literal></entry>
+ <entry>x11-fm/nautilus</entry>
+ <entry>GNOME 檔案管理員</entry>
+ </row>
+
+ <row>
+ <entry><literal>pango</literal></entry>
+ <entry>x11-toolkits/pango</entry>
+ <entry xml:lang="en">Open-source framework for the layout and
+ rendering of i18n text</entry>
+ </row>
+
+ <row>
+ <entry><literal>pangomm</literal></entry>
+ <entry>x11-toolkits/pangomm</entry>
+ <entry xml:lang="en">c++ bindings for the pango library</entry>
+ </row>
+
+ <row>
+ <entry><literal>py3gobject3</literal></entry>
+ <entry>devel/py3-gobject3</entry>
+ <entry xml:lang="en">Python 3, GObject 3.0 bindings</entry>
+ </row>
+
+ <row>
+ <entry><literal>pygobject3</literal></entry>
+ <entry>devel/py-gobject3</entry>
+ <entry xml:lang="en">Python 2, GObject 3.0 bindings</entry>
+ </row>
+
+ <row>
+ <entry><literal>vte3</literal></entry>
+ <entry>x11-toolkits/vte3</entry>
+ <entry xml:lang="en">Terminal widget with improved accessibility and
+ I18N support</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table xml:id="gnome-components-macro">
+ <title xml:lang="en">GNOME Macro Components</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>元件</entry>
+ <entry>描述</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>gnomeprefix</literal></entry>
+ <entry xml:lang="en">Supply <buildtarget xml:lang="en">configure</buildtarget> with
+ some default locations.</entry>
+ </row>
+
+ <row>
+ <entry><literal>intlhack</literal></entry>
+ <entry xml:lang="en">Same as intltool, but patches to make sure
+ <filename>share/locale/</filename> is used. Please
+ only use when <literal>intltool</literal> alone is
+ not enough.</entry>
+ </row>
+
+ <row>
+ <entry><literal>referencehack</literal></entry>
+ <entry xml:lang="en">This macro is there to help splitting of the API or
+ reference documentation into its own port.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table xml:id="gnome-components-legacy">
+ <title xml:lang="en">GNOME Legacy Components</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>元件</entry>
+ <entry>相關程式</entry>
+ <entry>描述</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>atspi</literal></entry>
+ <entry>accessibility/at-spi</entry>
+ <entry xml:lang="en">Assistive Technology Service Provider
+ Interface</entry>
+ </row>
+
+ <row>
+ <entry><literal>esound</literal></entry>
+ <entry>audio/esound</entry>
+ <entry>Enlightenment 音效套件</entry>
+ </row>
+
+ <row>
+ <entry><literal>gal2</literal></entry>
+ <entry>x11-toolkits/gal2</entry>
+ <entry xml:lang="en">Collection of widgets taken from GNOME 2
+ gnumeric</entry>
+ </row>
+
+ <row>
+ <entry><literal>gconf2</literal></entry>
+ <entry>devel/gconf2</entry>
+ <entry xml:lang="en">Configuration database system for GNOME 2</entry>
+ </row>
+
+ <row>
+ <entry><literal>gconfmm26</literal></entry>
+ <entry>devel/gconfmm26</entry>
+ <entry xml:lang="en">c++ bindings for gconf2</entry>
+ </row>
+
+ <row>
+ <entry><literal>gdkpixbuf</literal></entry>
+ <entry>graphics/gdk-pixbuf</entry>
+ <entry xml:lang="en">Graphics library for GTK+</entry>
+ </row>
+
+ <row>
+ <entry><literal>glib12</literal></entry>
+ <entry>devel/glib12</entry>
+ <entry>glib 1.2 核心函式庫</entry>
+ </row>
+
+ <row>
+ <entry><literal>gnomedocutils</literal></entry>
+ <entry>textproc/gnome-doc-utils</entry>
+ <entry xml:lang="en">GNOME doc utils</entry>
+ </row>
+
+ <row>
+ <entry><literal>gnomemimedata</literal></entry>
+ <entry>misc/gnome-mime-data</entry>
+ <entry xml:lang="en">MIME and Application database for GNOME 2</entry>
+ </row>
+
+ <row>
+ <entry><literal>gnomesharp20</literal></entry>
+ <entry>x11-toolkits/gnome-sharp20</entry>
+ <entry xml:lang="en">GNOME 2 interfaces for the .NET runtime</entry>
+ </row>
+
+ <row>
+ <entry><literal>gnomespeech</literal></entry>
+ <entry>accessibility/gnome-speech</entry>
+ <entry xml:lang="en">GNOME 2 text-to-speech API</entry>
+ </row>
+
+ <row>
+ <entry><literal>gnomevfs2</literal></entry>
+ <entry>devel/gnome-vfs</entry>
+ <entry>GNOME 2 虛擬檔案系統</entry>
+ </row>
+
+ <row>
+ <entry><literal>gtk12</literal></entry>
+ <entry>x11-toolkits/gtk12</entry>
+ <entry xml:lang="en">Gtk+ 1.2 toolkit</entry>
+ </row>
+
+ <row>
+ <entry><literal>gtkhtml3</literal></entry>
+ <entry>www/gtkhtml3</entry>
+ <entry xml:lang="en">Lightweight HTML rendering/printing/editing
+ engine</entry>
+ </row>
+
+ <row>
+ <entry><literal>gtkhtml4</literal></entry>
+ <entry>www/gtkhtml4</entry>
+ <entry xml:lang="en">Lightweight HTML rendering/printing/editing
+ engine</entry>
+ </row>
+
+ <row>
+ <entry><literal>gtksharp20</literal></entry>
+ <entry>x11-toolkits/gtk-sharp20</entry>
+ <entry xml:lang="en">GTK+ and GNOME 2 interfaces for the .NET
+ runtime</entry>
+ </row>
+
+ <row>
+ <entry><literal>gtksourceview</literal></entry>
+ <entry>x11-toolkits/gtksourceview</entry>
+ <entry xml:lang="en">Widget that adds syntax highlighting to
+ GtkTextView</entry>
+ </row>
+
+ <row>
+ <entry><literal>libartgpl2</literal></entry>
+ <entry>graphics/libart_lgpl</entry>
+ <entry xml:lang="en">Library for high-performance 2D graphics</entry>
+ </row>
+
+ <row>
+ <entry><literal>libbonobo</literal></entry>
+ <entry>devel/libbonobo</entry>
+ <entry xml:lang="en">Component and compound document system for
+ GNOME 2</entry>
+ </row>
+
+ <row>
+ <entry><literal>libbonoboui</literal></entry>
+ <entry>x11-toolkits/libbonoboui</entry>
+ <entry xml:lang="en">GUI frontend to the libbonobo component of
+ GNOME 2</entry>
+ </row>
+
+ <row>
+ <entry><literal>libgda4</literal></entry>
+ <entry>databases/libgda4</entry>
+ <entry xml:lang="en">Provides uniform access to different kinds of
+ data sources</entry>
+ </row>
+
+ <row>
+ <entry><literal>libglade2</literal></entry>
+ <entry>devel/libglade2</entry>
+ <entry>GNOME 2 glade 函式庫</entry>
+ </row>
+
+ <row>
+ <entry><literal>libgnome</literal></entry>
+ <entry>x11/libgnome</entry>
+ <entry xml:lang="en">Libraries for GNOME 2, a GNU desktop
+ environment</entry>
+ </row>
+
+ <row>
+ <entry><literal>libgnomecanvas</literal></entry>
+ <entry>graphics/libgnomecanvas</entry>
+ <entry>GNOME 2 圖形函式庫</entry>
+ </row>
+
+ <row>
+ <entry><literal>libgnomekbd</literal></entry>
+ <entry>x11/libgnomekbd</entry>
+ <entry>GNOME 2 鍵盤共用函式庫</entry>
+ </row>
+
+ <row>
+ <entry><literal>libgnomeprint</literal></entry>
+ <entry>print/libgnomeprint</entry>
+ <entry xml:lang="en">Gnome 2 print support library</entry>
+ </row>
+
+ <row>
+ <entry><literal>libgnomeprintui</literal></entry>
+ <entry>x11-toolkits/libgnomeprintui</entry>
+ <entry xml:lang="en">Gnome 2 print support library</entry>
+ </row>
+
+ <row>
+ <entry><literal>libgnomeui</literal></entry>
+ <entry>x11-toolkits/libgnomeui</entry>
+ <entry xml:lang="en">Libraries for the GNOME 2 GUI, a GNU desktop
+ environment</entry>
+ </row>
+
+ <row>
+ <entry><literal>libgtkhtml</literal></entry>
+ <entry>www/libgtkhtml</entry>
+ <entry xml:lang="en">Lightweight HTML rendering/printing/editing
+ engine</entry>
+ </row>
+
+ <row>
+ <entry><literal>libgtksourceviewmm</literal></entry>
+ <entry>x11-toolkits/libgtksourceviewmm</entry>
+ <entry xml:lang="en">c++ binding of GtkSourceView</entry>
+ </row>
+
+ <row>
+ <entry><literal>libidl</literal></entry>
+ <entry>devel/libIDL</entry>
+ <entry xml:lang="en">Library for creating trees of CORBA IDL
+ file</entry>
+ </row>
+
+ <row>
+ <entry><literal>libsigc++12</literal></entry>
+ <entry>devel/libsigc++12</entry>
+ <entry xml:lang="en">Callback Framework for C++</entry>
+ </row>
+
+ <row>
+ <entry><literal>libwnck</literal></entry>
+ <entry>x11-toolkits/libwnck</entry>
+ <entry xml:lang="en">Library used for writing pagers and
+ taskslists</entry>
+ </row>
+
+ <row>
+ <entry><literal>libwnck3</literal></entry>
+ <entry>x11-toolkits/libwnck3</entry>
+ <entry xml:lang="en">Library used for writing pagers and
+ taskslists</entry>
+ </row>
+
+ <row>
+ <entry><literal>orbit2</literal></entry>
+ <entry>devel/ORBit2</entry>
+ <entry xml:lang="en">High-performance CORBA ORB with support for the
+ C language</entry>
+ </row>
+
+ <row>
+ <entry><literal>pygnome2</literal></entry>
+ <entry>x11-toolkits/py-gnome2</entry>
+ <entry xml:lang="en">Python bindings for GNOME 2</entry>
+ </row>
+
+ <row>
+ <entry><literal>pygobject</literal></entry>
+ <entry xml:lang="en">devel/py-gobject</entry>
+ <entry xml:lang="en">Python 2, GObject 2.0 bindings</entry>
+ </row>
+
+ <row>
+ <entry><literal>pygtk2</literal></entry>
+ <entry>x11-toolkits/py-gtk2</entry>
+ <entry xml:lang="en">Set of Python bindings for GTK+</entry>
+ </row>
+
+ <row>
+ <entry><literal>pygtksourceview</literal></entry>
+ <entry>x11-toolkits/py-gtksourceview</entry>
+ <entry xml:lang="en">Python bindings for GtkSourceView 2</entry>
+ </row>
+
+ <row>
+ <entry><literal>vte</literal></entry>
+ <entry>x11-toolkits/vte</entry>
+ <entry xml:lang="en">Terminal widget with improved accessibility and
+ I18N support</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table xml:id="gnome-components-deprecated">
+ <title xml:lang="en">Deprecated Components: Do Not Use</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>元件</entry>
+ <entry>描述</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>HAVE_GNOME</literal></entry>
+ <entry xml:lang="en">Deprecated, do not use. Was used to check if a
+ component was installed. This was used for ports
+ that did not have
+ <literal>--enable</literal>/<literal>--disable</literal>
+ switches for their configure script. But the building
+ of parts of a port without a implicit request is
+ discouraged.</entry>
+ </row>
+
+ <row>
+ <entry><literal>WANT_GNOME</literal></entry>
+ <entry xml:lang="en">Deprecated, do not use. Was used by ports that
+ needed <varname>USE_GNOME</varname> for optional
+ dependencies, which where defined after
+ <filename>bsd.port.pre.mk</filename>. Since
+ <varname>USE_GNOME</varname> can be used after the
+ inclusion of <filename>bsd.port.options.mk</filename>,
+ there is little need for this macro any more.</entry>
+ </row>
+
+ <row>
+ <entry><literal>pangox-compat</literal></entry>
+ <entry><application>pangox-compat</application> has been deprecated and split off from the <application>pango</application> package.</entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+ </sect1>
+
+ <sect1 xml:id="using-qt">
+ <title>使用 Qt</title>
+
+ <sect2 xml:id="qt-common">
+ <title>需要 Qt 的 Ports</title>
+
+ <para xml:lang="en">The Ports Collection provides support for Qt 4 and Qt 5
+ frameworks with
+ <varname>USE_QT<replaceable>x</replaceable></varname>,
+ where <replaceable>x</replaceable> is
+ <literal>4</literal> or <literal>5</literal>.
+ Set <varname>USE_QT<replaceable>x</replaceable></varname>
+ to the list of required Qt components (libraries,
+ tools, plugins). The Qt 4 and Qt 5 frameworks are quite
+ similar. The main difference is the set of supported
+ components.</para>
+
+ <para xml:lang="en">The Qt framework exports a number of variables which can
+ be used by ports, some of them listed below:</para>
+
+ <table frame="none" xml:id="using-qt-variables">
+ <title xml:lang="en">Variables Provided to Ports That Use Qt</title>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry><varname>USE_KDELIBS_VER</varname></entry>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry><varname>QT_PREFIX</varname></entry>
+ <entry xml:lang="en">Set to the path where Qt was installed
+ (<literal>${LOCALBASE}</literal>).</entry>
+ </row>
- <entry>The port uses KDE libraries. It specifies the
- major version of KDE to use and implies
- <varname>USE_QT_VER</varname> of the appropriate
- version. The only possible value is
- <literal>3</literal>.</entry>
- </row>
+ <row>
+ <entry><varname>QMAKE</varname></entry>
+ <entry xml:lang="en">Full path to <command>qmake</command>
+ binary.</entry>
+ </row>
- <row>
- <entry><varname>USE_KDEBASE_VER</varname></entry>
+ <row>
+ <entry><varname>LRELEASE</varname></entry>
+ <entry xml:lang="en">Full path to <command>lrelease</command>
+ utility.</entry>
+ </row>
- <entry>The port uses KDE base. It specifies the major
- version of KDE to use and implies
- <varname>USE_QT_VER</varname> of the appropriate version.
- The only possible value is <literal>3</literal>.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <row>
+ <entry><varname>MOC</varname></entry>
+ <entry xml:lang="en">Full path to <command>moc</command>.</entry>
+ </row>
- </sect2>
+ <row>
+ <entry><varname>RCC</varname></entry>
+ <entry xml:lang="en">Full path to <command>rcc</command>.</entry>
+ </row>
- <sect2 xml:id="kde-qt">
- <title>Ports that require Qt</title>
+ <row>
+ <entry><varname>UIC</varname></entry>
+ <entry xml:lang="en">Full path to <command>uic</command>.</entry>
+ </row>
- <table frame="none">
- <title>Variables for ports that use Qt</title>
+ <row>
+ <entry><varname>QT_INCDIR</varname></entry>
+ <entry xml:lang="en">Qt include directory.</entry>
+ </row>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry><varname>USE_QT_VER</varname></entry>
+ <row>
+ <entry><varname>QT_LIBDIR</varname></entry>
+ <entry xml:lang="en">Qt libraries path.</entry>
+ </row>
- <entry>The port uses the Qt toolkit. Possible values
- are <literal>3</literal> and <literal>4</literal>;
- each specify the major version of Qt to use. Appropriate
- parameters are passed to <command>configure</command>
- script and <command>make</command>.</entry>
- </row>
+ <row>
+ <entry><varname>QT_PLUGINDIR</varname></entry>
+ <entry xml:lang="en">Qt plugins path.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
- <row>
- <entry><varname>QT_PREFIX</varname></entry>
+ <para xml:lang="en">When using the Qt framework, these
+ settings are deployed:</para>
- <entry>Set to the path where Qt installed to (read-only
- variable).</entry>
- </row>
+ <programlisting xml:lang="en">CONFIGURE_ARGS+= --with-qt-includes=${QT_INCDIR} \
+ --with-qt-libraries=${QT_LIBDIR} \
+ --with-extra-libs=${LOCALBASE}/lib \
+ --with-extra-includes=${LOCALBASE}/include
- <row>
- <entry><varname>MOC</varname></entry>
+CONFIGURE_ENV+= QTDIR="${QT_PREFIX}" QMAKE="${QMAKE}" \
+ MOC="${MOC}" RCC="${RCC}" UIC="${UIC}" \
+ QMAKESPEC="${QMAKESPEC}"
- <entry>Set to the path of <command>moc</command>
- (read-only variable). Default set according to
- <varname>USE_QT_VER</varname> value.</entry>
- </row>
+PLIST_SUB+= QT_INCDIR=${QT_INCDIR_REL} \
+ QT_LIBDIR=${QT_LIBDIR_REL} \
+ QT_PLUGINDIR=${QT_PLUGINDIR_REL}</programlisting>
- <row>
- <entry><varname>QTCPPFLAGS</varname></entry>
+ <para xml:lang="en">Some configure scripts do not support the arguments above.
+ To suppress modification of<varname>CONFIGURE_ENV</varname>
+ and <varname>CONFIGURE_ARGS</varname>, set
+ <varname>QT_NONSTANDARD</varname>.</para>
+ </sect2>
- <entry>Additional compiler flags passed via
- <varname>CONFIGURE_ENV</varname> for Qt toolkit.
- Default set according to
- <varname>USE_QT_VER</varname>.</entry>
- </row>
+ <sect2 xml:id="qt-components">
+ <title xml:lang="en">Component Selection</title>
+
+ <para xml:lang="en">Individual Qt tool and library dependencies must be
+ specified in
+ <varname>USE_QT<replaceable>x</replaceable></varname>.
+ Every component can be suffixed with
+ <literal>_build</literal> or <literal>_run</literal>, the
+ suffix indicating whether the dependency on the component is
+ at buildtime or runtime. If unsuffixed, the component will be
+ depended on at both build- and runtime. Usually, library
+ components are specified unsuffixed, tool components
+ are mostly specified with the <literal>_build</literal> suffix
+ and plugin components are specified with the
+ <literal>_run</literal> suffix. The most commonly used
+ components are listed below (all available components are
+ listed in <varname>_USE_QT_ALL</varname>,
+ <varname>_USE_QT4_ONLY</varname>, and
+ <varname>_USE_QT5_ONLY</varname> in
+ <filename>/usr/ports/Mk/bsd.qt.mk</filename>):</para>
+
+ <table frame="none" xml:id="using-qt-library-list">
+ <title>可用的 Qt 函式庫元件</title>
- <row>
- <entry><varname>QTCFGLIBS</varname></entry>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>名字</entry>
+ <entry>描述</entry>
+ </row>
+ </thead>
- <entry>Additional libraries for linking passed via
- <varname>CONFIGURE_ENV</varname> for Qt toolkit.
- Default set according to
- <varname>USE_QT_VER</varname>.</entry>
- </row>
+ <tbody>
+ <row>
+ <entry><literal>core</literal></entry>
+ <entry>核心函式庫 (Qt 5 only)</entry>
+ </row>
- <row>
- <entry><varname>QTNONSTANDARD</varname></entry>
+ <row>
+ <entry><literal>corelib</literal></entry>
+ <entry>核心函式庫 (Qt 4 only)</entry>
+ </row>
- <entry>Suppress modification of
- <varname>CONFIGURE_ENV</varname>,
- <varname>CONFIGURE_ARGS</varname>, and
- <varname>MAKE_ENV</varname>.</entry>
- </row>
+ <row>
+ <entry><literal>dbus</literal></entry>
+ <entry>Qt DBus 函式庫</entry>
+ </row>
- </tbody>
- </tgroup>
- </table>
+ <row>
+ <entry><literal>gui</literal></entry>
+ <entry>圖形使用者介面函式庫</entry>
+ </row>
- <table frame="none">
- <title>Additional variables for ports that use Qt 4.x</title>
+ <row>
+ <entry><literal>network</literal></entry>
+ <entry>網路函式庫</entry>
+ </row>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry><varname>QT_COMPONENTS</varname></entry>
+ <row>
+ <entry><literal>opengl</literal></entry>
+ <entry>Qt OpenGL 函式庫</entry>
+ </row>
- <entry>Specify tool and library dependencies for Qt4.
- See below for details.</entry>
- </row>
+ <row>
+ <entry><literal>script</literal></entry>
+ <entry xml:lang="en">script library</entry>
+ </row>
- <row>
- <entry><varname>UIC</varname></entry>
+ <row>
+ <entry><literal>sql</literal></entry>
+ <entry>SQL 函式庫</entry>
+ </row>
- <entry>Set to the path of <command>uic</command> (read-only
- variable). Default set according to
- <varname>USE_QT_VER</varname> value.</entry>
- </row>
+ <row>
+ <entry><literal>testlib</literal></entry>
+ <entry xml:lang="en">unit testing library</entry>
+ </row>
- <row>
- <entry><varname>QMAKE</varname></entry>
+ <row>
+ <entry><literal>webkit</literal></entry>
+ <entry>Qt WebKit 函式庫</entry>
+ </row>
- <entry>Set to the path of <command>qmake</command>
- (read-only variable). Default set according to
- <varname>USE_QT_VER</varname> value.</entry>
- </row>
+ <row>
+ <entry><literal>xml</literal></entry>
+ <entry>Qt XML 函式庫</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
- <row>
- <entry><varname>QMAKESPEC</varname></entry>
+ <para xml:lang="en">To determine the libraries an application
+ depends on, run <command>ldd</command> on the main
+ executable after a successful compilation.</para>
- <entry>Set to the path of configuration file for
- <command>qmake</command> (read-only variable). Default
- set according to <varname>USE_QT_VER</varname>
- value.</entry>
- </row>
+ <table frame="none" xml:id="using-qt-tools-list">
+ <title xml:lang="en">Available Qt Tool Components</title>
- </tbody>
- </tgroup>
- </table>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>名字</entry>
+ <entry>描述</entry>
+ </row>
+ </thead>
- <para>When <varname>USE_QT_VER</varname> is set, some useful
- settings are passed to <command>configure</command> script:</para>
+ <tbody>
+ <row>
+ <entry><literal>qmake</literal></entry>
+ <entry xml:lang="en">Makefile generator/build utility</entry>
+ </row>
- <programlisting>CONFIGURE_ARGS+= --with-qt-includes=${QT_PREFIX}/include \
- --with-qt-libraries=${QT_PREFIX}/lib \
- --with-extra-libs=${LOCALBASE}/lib \
- --with-extra-includes=${LOCALBASE}/include
-CONFIGURE_ENV+= MOC="${MOC}" CPPFLAGS="${CPPFLAGS} ${QTCPPFLAGS}" LIBS="${QTCFGLIBS}" \
- QTDIR="${QT_PREFIX}" KDEDIR="${KDE_PREFIX}"</programlisting>
+ <row>
+ <entry xml:lang="en"><literal>buildtools</literal></entry>
+ <entry xml:lang="en">build tools (<command>moc</command>,
+ <command>rcc</command>), needed for almost
+ every Qt application (Qt 5 only)</entry>
+ </row>
- <para>If <varname>USE_QT_VER</varname> is set to <literal>4</literal>,
- the following settings are also deployed:</para>
+ <row>
+ <entry><literal>linguisttools</literal></entry>
+ <entry xml:lang="en">localization tools: <command>lrelease</command>,
+ <command>lupdate</command> (Qt 5 only)</entry>
+ </row>
- <programlisting>CONFIGURE_ENV+= UIC="${UIC}" QMAKE="${QMAKE}" QMAKESPEC="${QMAKESPEC}"
-MAKE_ENV+= QMAKESPEC="${QMAKESPEC}"</programlisting>
+ <row>
+ <entry><literal>linguist</literal></entry>
+ <entry xml:lang="en">localization tools: <command>lrelease</command>,
+ <command>lupdate</command> (Qt 4 only)</entry>
+ </row>
- </sect2>
+ <row>
+ <entry><literal>moc</literal></entry>
+ <entry xml:lang="en">meta object compiler, needed for almost
+ every Qt application at buildtime (Qt 4 only)</entry>
+ </row>
- <sect2 xml:id="qt4-components">
- <title>Component selection (Qt 4.x only)</title>
+ <row>
+ <entry><literal>rcc</literal></entry>
+ <entry xml:lang="en">resource compiler, needed if the application
+ comes with <filename>*.rc</filename> or
+ <filename>*.qrc</filename> files (Qt 4 only)</entry>
+ </row>
- <para>When <varname>USE_QT_VER</varname> is set to 4, individual
- Qt4 tool and library dependencies can be specified in the
- <varname>QT_COMPONENTS</varname> variable. Every component
- can be suffixed by either <literal>_build</literal> or <literal>_run</literal>,
- the suffix indicating whether the component should be depended on at
- buildtime or runtime, respectively. If unsuffixed, the component will be
- depended on at both build- and runtime. Usually, library components
- should be specified unsuffixed, tool components should be
- specified with the <literal>_build</literal> suffix and plugin components
- should be specified with the <literal>_run</literal> suffix. The most commonly
- used components are listed below (all available components are
- listed in <varname>_QT_COMPONENTS_ALL</varname> in
- <filename>/usr/ports/Mk/bsd.qt.mk</filename>):</para>
+ <row>
+ <entry><literal>uic</literal></entry>
+ <entry xml:lang="en">user interface compiler, needed if the
+ application comes with <filename>*.ui</filename>
+ files, in practice, every Qt
+ application with a GUI (Qt 4 only)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
- <table frame="none">
- <title>Available Qt4 library components</title>
+ <table frame="none" xml:id="using-qt-plugins-list">
+ <title xml:lang="en">Available Qt Plugin Components</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Name</entry>
- <entry>Description</entry>
- </row>
- </thead>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>名字</entry>
+ <entry>描述</entry>
+ </row>
+ </thead>
- <tbody>
- <row>
- <entry><literal>corelib</literal></entry>
- <entry>core library (can be omitted unless the port
- uses nothing but <literal>corelib</literal>)</entry>
- </row>
+ <tbody>
+ <row>
+ <entry><literal>iconengines</literal></entry>
+ <entry xml:lang="en">SVG icon engine plugin, needed if the application
+ ships SVG icons (Qt 4 only)</entry>
+ </row>
- <row>
- <entry><literal>gui</literal></entry>
- <entry>graphical user interface library</entry>
- </row>
+ <row>
+ <entry><literal>imageformats</literal></entry>
+ <entry xml:lang="en">plugins for TGA, TIFF, and MNG
+ image formats</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
- <row>
- <entry><literal>network</literal></entry>
- <entry>network library</entry>
- </row>
+ <example xml:id="qt4-components-example">
+ <title xml:lang="en">Selecting Qt 4 Components</title>
+
+ <para xml:lang="en">In this example, the ported application uses the Qt 4
+ graphical user interface library, the Qt 4 core library,
+ all of the Qt 4 code generation tools and Qt 4's Makefile
+ generator. Since the <literal>gui</literal> library
+ implies a dependency on the core library,
+ <literal>corelib</literal> does not need to be specified.
+ The Qt 4 code generation tools <literal>moc</literal>,
+ <literal>uic</literal> and <literal>rcc</literal>, as well
+ as the Makefile generator <literal>qmake</literal> are
+ only needed at buildtime, thus they are specified with the
+ <literal>_build</literal> suffix:</para>
+
+ <programlisting xml:lang="en">USE_QT4= gui moc_build qmake_build rcc_build uic_build</programlisting>
+ </example>
+ </sect2>
- <row>
- <entry><literal>opengl</literal></entry>
- <entry>OpenGL library</entry>
- </row>
+ <sect2 xml:id="using-qmake">
+ <title>使用 <command>qmake</command></title>
+
+
+ <para xml:lang="en">If the application provides a
+ <application>qmake</application> project file
+ (<filename>*.pro</filename>), define
+ <literal>USES= qmake</literal> along with
+ <literal>USE_QT<replaceable>x</replaceable></literal>. Note
+ that <literal>USES= qmake</literal> already implies a build
+ dependency on qmake, therefore the qmake component can be
+ omitted from
+ <literal>USE_QT<replaceable>x</replaceable></literal>.
+ Similar to <link linkend="using-cmake"><application>CMake</application></link>,
+ <application>qmake</application> supports out-of-source
+ builds, which can be enabled by specifying the
+ <literal>outsource</literal> argument (see <link linkend="using-qmake-example"><literal>USES= qmake</literal>
+ example</link>).</para>
+
+ <table frame="none" xml:id="using-qmake-variables">
+ <title xml:lang="en">Variables for Ports That Use
+ <command>qmake</command></title>
- <row>
- <entry><literal>qt3support</literal></entry>
- <entry>Qt3 compatibility library</entry>
- </row>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry xml:lang="en">Variable</entry>
+ <entry xml:lang="en">Means</entry>
+ </row>
+ </thead>
- <row>
- <entry><literal>qtestlib</literal></entry>
- <entry>unit testing library</entry>
- </row>
+ <tbody>
+ <row>
+ <entry><varname>QMAKE_ARGS</varname></entry>
+ <entry xml:lang="en">Port specific <application>qmake</application>
+ flags to be passed to the <command>qmake</command>
+ binary.</entry>
+ </row>
- <row>
- <entry><literal>script</literal></entry>
- <entry>script library</entry>
- </row>
+ <row>
+ <entry><varname>QMAKE_ENV</varname></entry>
+ <entry xml:lang="en">Environment variables to be set for the
+ <command>qmake</command> binary. The default is
+ <literal>${CONFIGURE_ENV}</literal>.</entry>
+ </row>
- <row>
- <entry><literal>sql</literal></entry>
- <entry>SQL library</entry>
- </row>
+ <row>
+ <entry><varname>QMAKE_SOURCE_PATH</varname></entry>
- <row>
- <entry><literal>xml</literal></entry>
- <entry>XML library</entry>
- </row>
+ <entry xml:lang="en">Path to qmake project files
+ (<filename>.pro</filename>). The default is
+ <literal>${WRKSRC}</literal> if an
+ out-of-source build is requested, empty
+ otherwise.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
- </tbody>
- </tgroup>
- </table>
+ <example xml:id="using-qmake-example">
+ <title><literal>USES= qmake</literal> 範例</title>
- <para>You can determine which libraries the application depends
- on, by running <command>ldd</command> on the main executable
- after a successful compilation.</para>
+ <para xml:lang="en">This snippet demonstrates the use of
+ <application>qmake</application> for a Qt 4 port:</para>
- <table frame="none">
- <title>Available Qt4 tool components</title>
+ <programlisting xml:lang="en">USES= qmake:outsource
+USE_QT4= moc_build</programlisting>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Name</entry>
- <entry>Description</entry>
- </row>
- </thead>
+ <para xml:lang="en">For a Qt 5 port:</para>
+ <programlisting xml:lang="en">USES= qmake:outsource
+USE_QT5= buildtools_build</programlisting>
+ </example>
- <tbody>
- <row>
- <entry><literal>moc</literal></entry>
- <entry>meta object compiler (needed for almost
- every Qt application at buildtime)</entry>
- </row>
+ <para xml:lang="en">Qt applications are often written to be cross-platform
+ and often X11/Unix is not the platform they are developed
+ on, which in turn leads to certain loose ends,
+ like:</para>
- <row>
- <entry><literal>qmake</literal></entry>
- <entry>Makefile generator / build utility</entry>
- </row>
+ <itemizedlist>
+ <listitem>
+ <para xml:lang="en"><emphasis>Missing additional include
+ paths.</emphasis> Many applications come with
+ system tray icon support, but neglect to look for
+ includes and/or libraries in the X11 directories. To add
+ directories to <command>qmake</command>'s
+ include and library search paths via the command
+ line, use:</para>
+
+ <programlisting xml:lang="en">QMAKE_ARGS+= INCLUDEPATH+=${LOCALBASE}/include \
+ LIBS+=-L${LOCALBASE}/lib</programlisting>
+ </listitem>
- <row>
- <entry><literal>rcc</literal></entry>
- <entry>resource compiler (need if the application comes
- with <filename>*.rc</filename> or <filename>*.qrc</filename>
- files)</entry>
- </row>
+ <listitem>
+ <para xml:lang="en"><emphasis>Bogus installation paths.</emphasis>
+ Sometimes data such as icons or .desktop files are by
+ default installed into directories which are not scanned
+ by XDG-compatible applications.
+ <package role="port">editors/texmaker</package> is
+ an example for this - look at
+ <filename>patch-texmaker.pro</filename> in the
+ <filename>files</filename> directory of that port for a
+ template on how to remedy this directly in the
+ <command>qmake</command> project file.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="using-kde">
+ <title>使用 KDE</title>
+
+ <sect2 xml:id="kde4-variables">
+ <title xml:lang="en">KDE 4 Variable Definitions</title>
+
+ <para xml:lang="en">If the application depends on KDE 4, set
+ <varname>USE_KDE4</varname> to the list of required
+ components. <literal>_build</literal> and
+ <literal>_run</literal> suffixes can be used to force
+ components dependency type (for example,
+ <literal>baseapps_run</literal>). If no suffix is set, a
+ default dependency type will be used. To force both types,
+ add the component twice with both suffixes (for example,
+ <literal>automoc4_build automoc4_run</literal>). The most
+ commonly used components are listed below (up-to-date
+ components are documented at the top of
+ <filename>/usr/ports/Mk/bsd.kde4.mk</filename>):</para>
+
+ <table frame="none" xml:id="using-kde-components">
+ <title>可用的 KDE 4 元件</title>
- <row>
- <entry><literal>uic</literal></entry>
- <entry>user interface compiler (needed if the application
- comes with <filename>*.ui</filename> files created by Qt Designer
- - in practice, every Qt application with a GUI)</entry>
- </row>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>名字</entry>
+ <entry>描述</entry>
+ </row>
+ </thead>
- </tbody>
- </tgroup>
- </table>
+ <tbody>
+ <row>
+ <entry><literal>kdehier</literal></entry>
+ <entry xml:lang="en">Hierarchy of common KDE directories</entry>
+ </row>
- <table frame="none">
- <title>Available Qt4 plugin components</title>
+ <row>
+ <entry><literal>kdelibs</literal></entry>
+ <entry>KDE 核心函式庫</entry>
+ </row>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Name</entry>
- <entry>Description</entry>
- </row>
- </thead>
+ <row>
+ <entry><literal>kdeprefix</literal></entry>
+ <entry xml:lang="en">If set, port will be installed into
+ <literal>${KDE4_PREFIX}</literal></entry>
+ </row>
- <tbody>
- <row>
- <entry><literal>iconengines</literal></entry>
- <entry>SVG icon engine plugin (if the application
- ships SVG icons)</entry>
- </row>
+ <row>
+ <entry><literal>automoc4</literal></entry>
+ <entry xml:lang="en">Build tool to automatically generate moc
+ files</entry>
+ </row>
- <row>
- <entry><literal>imageformats</literal></entry>
- <entry>imageformat plugins for GIF, JPEG, MNG and
- SVG (if the application ships image files)</entry>
- </row>
+ <row>
+ <entry><literal>akonadi</literal></entry>
+ <entry xml:lang="en">Storage server for KDE PIM data</entry>
+ </row>
- </tbody>
- </tgroup>
- </table>
+ <row>
+ <entry><literal>soprano</literal></entry>
+ <entry xml:lang="en">Library for Resource Description Framework
+ (RDF)</entry>
+ </row>
- <example xml:id="qt4-components-example">
- <title>Selecting Qt4 components</title>
-
- <para>In this example, the ported application uses the
- Qt4 graphical user interface library, the Qt4 core
- library, all of the Qt4 code generation tools and Qt4's
- Makefile generator. Since the gui library implies a
- dependency on the core library, corelib does
- not need to be specified. The Qt4 code generation
- tools moc, uic and rcc, as well as the Makefile generator
- qmake are only needed at buildtime, thus they are specified
- with the <literal>_build</literal> suffix:</para>
-
- <programlisting>USE_QT_VER= 4
-QT_COMPONENTS= gui moc_build qmake_build rcc_build uic_build</programlisting>
- </example>
- </sect2>
+ <row>
+ <entry><literal>strigi</literal></entry>
+ <entry>Strigi 桌面搜尋函式庫</entry>
+ </row>
- <sect2 xml:id="qt-additional">
- <title>Additional considerations</title>
+ <row>
+ <entry><literal>libkcddb</literal></entry>
+ <entry xml:lang="en">KDE CDDB (compact disc database) library</entry>
+ </row>
- <para>If the application does not provide a
- <filename>configure</filename> file but a <filename>.pro</filename>
- file, you can use the following:</para>
+ <row>
+ <entry><literal>libkcompactdisc</literal></entry>
+ <entry xml:lang="en">KDE library for interfacing with audio
+ CDs</entry>
+ </row>
- <programlisting>HAS_CONFIGURE= yes
+ <row>
+ <entry><literal>libkdeedu</literal></entry>
+ <entry xml:lang="en">Libraries used by educational
+ applications</entry>
+ </row>
-do-configure:
- @cd ${WRKSRC} &amp;&amp; ${SETENV} ${CONFIGURE_ENV} \
- ${QMAKE} -unix PREFIX=${PREFIX} texmaker.pro</programlisting>
+ <row>
+ <entry><literal>libkdcraw</literal></entry>
+ <entry>KDE LibRaw 函式庫</entry>
+ </row>
- <para>Note the similarity to the <command>qmake</command> line
- from the provided <filename>BUILD.sh</filename> script. Passing
- <varname>CONFIGURE_ENV</varname> ensures <command>qmake</command>
- will see the <varname>QMAKESPEC</varname> variable, without which
- it cannot work. <command>qmake</command> generates standard
- Makefiles, so it is not necessary to write our own
- <buildtarget>build</buildtarget> target.</para>
+ <row>
+ <entry><literal>libkexiv2</literal></entry>
+ <entry>KDE Exiv2 函式庫</entry>
+ </row>
- <para>Qt applications often are written to be cross-platform
- and often X11/Unix isn't the platform they are developed on,
- which in turn often leads to certain loose ends, like:</para>
+ <row>
+ <entry><literal>libkipi</literal></entry>
+ <entry xml:lang="en">KDE Image Plugin Interface</entry>
+ </row>
- <itemizedlist>
- <listitem>
- <para><emphasis>Missing additional includepaths.</emphasis>
- Many applications come with system tray icon support, but
- neglect to look for includes and/or libraries in the X11
- directories. You can tell <command>qmake</command> to
- add directories to the include and library searchpaths
- via the commandline, for example:</para>
+ <row>
+ <entry><literal>libkonq</literal></entry>
+ <entry>Konqueror 核心函式庫</entry>
+ </row>
- <programlisting>${QMAKE} -unix PREFIX=${PREFIX} INCLUDEPATH+=${LOCALBASE}/include \
- LIBS+=-L${LOCALBASE}/lib sillyapp.pro</programlisting>
+ <row>
+ <entry><literal>libksane</literal></entry>
+ <entry xml:lang="en">KDE SANE ("Scanner Access Now Easy")
+ library</entry>
+ </row>
- </listitem>
+ <row>
+ <entry><literal>pimlibs</literal></entry>
+ <entry xml:lang="en">Personal information management libraries</entry>
+ </row>
- <listitem>
- <para><emphasis>Bogus installation paths.</emphasis>
- Sometimes data such as icons or .desktop files are by
- default installed into directories which aren't scanned by
- XDG-compatible applications. <package>editors/texmaker</package>
- is an example for this - look at <filename>patch-texmaker.pro</filename>
- in the <filename>files</filename> directory of that port
- for a template on how to remedy this directly in the Qmake
- project file.</para>
- </listitem>
- </itemizedlist>
+ <row>
+ <entry><literal>kate</literal></entry>
+ <entry xml:lang="en">Advanced text editor framework</entry>
+ </row>
- </sect2>
+ <row>
+ <entry><literal>marble</literal></entry>
+ <entry xml:lang="en">Virtual globe and world atlas</entry>
+ </row>
- </sect1>
+ <row>
+ <entry><literal>okular</literal></entry>
+ <entry xml:lang="en">Universal document viewer</entry>
+ </row>
- <sect1 xml:id="using-java">
- <title>Using Java</title>
+ <row>
+ <entry><literal>korundum</literal></entry>
+ <entry xml:lang="en">KDE Ruby bindings</entry>
+ </row>
- <sect2 xml:id="java-variables">
- <title>Variable definitions</title>
+ <row>
+ <entry><literal>perlkde</literal></entry>
+ <entry xml:lang="en">KDE Perl bindings</entry>
+ </row>
- <para>If your port needs a Java&trade; Development Kit (JDK) to
- either build, run or even extract the distfile, then it should
- define <varname>USE_JAVA</varname>.</para>
+ <row>
+ <entry><literal>pykde4</literal></entry>
+ <entry xml:lang="en">KDE Python bindings</entry>
+ </row>
- <para>There are several JDKs in the ports collection, from various
- vendors, and in several versions. If your port must use one of
- these versions, you can define which one. The most current
- version is <package>java/jdk15</package>.</para>
+ <row>
+ <entry><literal>pykdeuic4</literal></entry>
+ <entry xml:lang="en">PyKDE user interface compiler</entry>
+ </row>
- <table frame="none">
- <title>Variables that may be set by ports that use Java</title>
+ <row>
+ <entry><literal>smokekde</literal></entry>
+ <entry>KDE SMOKE 函式庫</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para xml:lang="en">KDE 4 ports are installed into
+ <varname>KDE4_PREFIX</varname>. This is
+ achieved by specifying the <literal>kdeprefix</literal>
+ component, which overrides the default
+ <varname>PREFIX</varname>. The ports, however, respect any
+ <varname>PREFIX</varname> set via the <envar>MAKEFLAGS</envar>
+ environment variable and/or <command>make</command>
+ arguments. Currently <varname>KDE4_PREFIX</varname>
+ is identical to the default <varname>PREFIX</varname>,
+ <literal>${LOCALBASE}</literal>.</para>
+
+ <example xml:id="kde4-components-example">
+ <title><varname>USE_KDE4</varname> 範例</title>
+
+ <para xml:lang="en">This is a simple example for a KDE 4 port.
+ <literal>USES= cmake:outsource</literal> instructs the
+ port to utilize <application>CMake</application>, a
+ configuration tool widely used by KDE 4 projects (see
+ <xref linkend="using-cmake"/> for detailed usage).
+ <varname>USE_KDE4</varname> brings dependency on KDE
+ libraries and makes port using
+ <command>automoc4</command> at build stage.
+ Required KDE components and other dependencies can be
+ determined through configure log.
+ <varname>USE_KDE4</varname> does not imply
+ <varname>USE_QT4</varname>. If a port requires some
+ Qt 4 components, specify them in
+ <varname>USE_QT4</varname>.</para>
+
+ <programlisting>USES= cmake:outsource
+USE_KDE4= kdelibs kdeprefix automoc4
+USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting>
+ </example>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="using-java">
+ <title>使用 Java</title>
+
+ <sect2 xml:id="java-variables">
+ <title>變數定義</title>
+
+ <para xml:lang="en">If the port needs a Java™ Development Kit
+ (<acronym>JDK</acronym>™) to either build, run or even
+ extract the distfile, then define
+ <varname>USE_JAVA</varname>.</para>
+
+ <para xml:lang="en">There are several <acronym>JDK</acronym>s in the ports
+ collection, from various vendors, and in several versions. If
+ the port must use one of these versions, define which one.
+ The most current version, and FreeBSD default is
+ <package role="port">java/openjdk6</package>.</para>
+
+ <table frame="none" xml:id="using-java-variables">
+ <title xml:lang="en">Variables Which May be Set by Ports That Use
+ Java</title>
<tgroup cols="2">
<thead>
<row>
- <entry>Variable</entry>
- <entry>Means</entry>
+ <entry xml:lang="en">Variable</entry>
+ <entry xml:lang="en">Means</entry>
</row>
</thead>
+
<tbody>
<row>
<entry><varname>USE_JAVA</varname></entry>
- <entry>Should be defined for the remaining variables to have any
- effect.</entry>
+ <entry xml:lang="en">Define for the remaining variables
+ to have any effect.</entry>
</row>
<row>
<entry><varname>JAVA_VERSION</varname></entry>
- <entry>List of space-separated suitable Java versions for
- the port. An optional <literal>"+"</literal> allows you to
- specify a range of versions (allowed values:
- <literal>1.1[+] 1.2[+] 1.3[+] 1.4[+]</literal>).</entry>
+ <entry xml:lang="en">List of space-separated suitable Java versions
+ for the port. An optional <literal>"+"</literal>
+ allows specifying a range of versions (allowed
+ values:
+ <literal>1.5[+] 1.6[+] 1.7[+]</literal>).</entry>
</row>
<row>
<entry><varname>JAVA_OS</varname></entry>
- <entry>List of space-separated suitable JDK port operating
- systems for the port (allowed values: <literal>native
- linux</literal>).</entry>
+ <entry xml:lang="en">List of space-separated suitable
+ <acronym>JDK</acronym> port operating systems for the
+ port (allowed values:
+ <literal>native linux</literal>).</entry>
</row>
<row>
<entry><varname>JAVA_VENDOR</varname></entry>
- <entry>List of space-separated suitable JDK port vendors for
- the port (allowed values: <literal>freebsd bsdjava sun ibm
- blackdown</literal>).</entry>
+ <entry xml:lang="en">List of space-separated suitable
+ <acronym>JDK</acronym> port vendors for the port
+ (allowed values:
+ <literal>freebsd bsdjava sun
+ openjdk</literal>).</entry>
</row>
<row>
<entry><varname>JAVA_BUILD</varname></entry>
- <entry>When set, it means that the selected JDK port should
- be added to the build dependencies of the port.</entry>
+ <entry xml:lang="en">When set, add the selected <acronym>JDK</acronym>
+ port to the build dependencies.</entry>
</row>
<row>
<entry><varname>JAVA_RUN</varname></entry>
- <entry>When set, it means that the selected JDK port should
- be added to the run dependencies of the port.</entry>
+ <entry xml:lang="en">When set, add the selected <acronym>JDK</acronym>
+ port to the run dependencies.</entry>
</row>
<row>
<entry><varname>JAVA_EXTRACT</varname></entry>
- <entry>When set, it means that the selected JDK port should
- be added to the extract dependencies of the port.</entry>
- </row>
-
- <row>
- <entry><varname>USE_JIKES</varname></entry>
- <entry>Whether the port should or should not use the
- <command>jikes</command> bytecode compiler to build. When
- no value is set for this variable, the port will use
- <command>jikes</command> to build if available. You may
- also explicitly forbid or enforce the use of
- <command>jikes</command> (by setting <literal>'no'</literal>
- or <literal>'yes'</literal>). In the later case, <package>devel/jikes</package> will be added to build
- dependencies of the port. In any case that <command>jikes</command>
- is actually used in place of <command>javac</command>, then the
- <varname>HAVE_JIKES</varname> variable is defined by
- <filename>bsd.java.mk</filename>.</entry>
+ <entry xml:lang="en">When set, add the selected <acronym>JDK</acronym>
+ port to the extract dependencies.</entry>
</row>
</tbody>
</tgroup>
</table>
- <para>Below is the list of all settings a port will receive after
- setting <varname>USE_JAVA</varname>:</para>
+ <para xml:lang="en">Below is the list of all settings a port will receive
+ after setting <varname>USE_JAVA</varname>:</para>
- <table frame="none">
- <title>Variables provided to ports that use Java</title>
+ <table frame="none" xml:id="using-java-variables2">
+ <title xml:lang="en">Variables Provided to Ports That Use Java</title>
<tgroup cols="2">
<thead>
<row>
- <entry>Variable</entry>
- <entry>Value</entry>
+ <entry xml:lang="en">Variable</entry>
+ <entry xml:lang="en">Value</entry>
</row>
</thead>
+
<tbody>
<row>
<entry><varname>JAVA_PORT</varname></entry>
- <entry>The name of the JDK port (e.g.
- <literal>'java/jdk14'</literal>).</entry>
+ <entry xml:lang="en">The name of the <acronym>JDK</acronym> port (for
+ example, <literal>java/openjdk6</literal>).</entry>
</row>
<row>
<entry><varname>JAVA_PORT_VERSION</varname></entry>
- <entry>The full version of the JDK port (e.g.
- <literal>'1.4.2'</literal>). If you only need the first
- two digits of this version number, use
+ <entry xml:lang="en">The full version of the <acronym>JDK</acronym>
+ port (for example, <literal>1.6.0</literal>). Only
+ the first two digits of this version number are
+ needed, use
<varname>${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}</varname>.</entry>
</row>
<row>
<entry><varname>JAVA_PORT_OS</varname></entry>
- <entry>The operating system used by the JDK port (e.g.
- <literal>'linux'</literal>).</entry>
+ <entry xml:lang="en">The operating system used by the
+ <acronym>JDK</acronym> port (for example,
+ <literal>'native'</literal>).</entry>
</row>
<row>
<entry><varname>JAVA_PORT_VENDOR</varname></entry>
- <entry>The vendor of the JDK port (e.g.
- <literal>'sun'</literal>).</entry>
+ <entry xml:lang="en">The vendor of the <acronym>JDK</acronym> port
+ (for example, <literal>'openjdk'</literal>).</entry>
</row>
<row>
<entry><varname>JAVA_PORT_OS_DESCRIPTION</varname></entry>
- <entry>Description of the operating system used by the JDK port
- (e.g. <literal>'Linux'</literal>).</entry>
+ <entry xml:lang="en">Description of the operating system used by the
+ <acronym>JDK</acronym> port (for example,
+ <literal>'Native'</literal>).</entry>
</row>
<row>
<entry><varname>JAVA_PORT_VENDOR_DESCRIPTION</varname></entry>
- <entry>Description of the vendor of the JDK port (e.g.
- <literal>'FreeBSD Foundation'</literal>).</entry>
+ <entry xml:lang="en">Description of the vendor of the
+ <acronym>JDK</acronym> port (for example,
+ <literal>'OpenJDK BSD Porting
+ Team'</literal>).</entry>
</row>
<row>
<entry><varname>JAVA_HOME</varname></entry>
- <entry>Path to the installation directory of the JDK (e.g.
- <filename>'/usr/local/jdk1.3.1'</filename>).</entry>
+ <entry xml:lang="en">Path to the installation directory of the
+ <acronym>JDK</acronym> (for example,
+ <filename>'/usr/local/openjdk6'</filename>).</entry>
</row>
<row>
<entry><varname>JAVAC</varname></entry>
- <entry>Path to the Java compiler to use (e.g.
- <filename>'/usr/local/jdk1.1.8/bin/javac'</filename> or
- <filename>'/usr/local/bin/jikes'</filename>).</entry>
+ <entry xml:lang="en">Path to the Java compiler to use (for example,
+ <filename>'/usr/local/openjdk6/bin/javac'</filename>).</entry>
</row>
<row>
<entry><varname>JAR</varname></entry>
- <entry>Path to the <command>jar</command> tool to use (e.g.
- <filename>'/usr/local/jdk1.2.2/bin/jar'</filename> or
+ <entry xml:lang="en">Path to the <command>jar</command> tool to use
+ (for example,
+ <filename>'/usr/local/openjdk6/bin/jar'</filename>
+ or
<filename>'/usr/local/bin/fastjar'</filename>).</entry>
</row>
<row>
<entry><varname>APPLETVIEWER</varname></entry>
- <entry>Path to the <command>appletviewer</command> utility (e.g.
- <filename>'/usr/local/linux-jdk1.2.2/bin/appletviewer'</filename>).</entry>
+ <entry xml:lang="en">Path to the <command>appletviewer</command>
+ utility (for example,
+ <filename>'/usr/local/openjdk6/bin/appletviewer'</filename>).</entry>
</row>
<row>
<entry><varname>JAVA</varname></entry>
- <entry>Path to the <command>java</command> executable. Use
- this for executing Java programs (e.g.
- <filename>'/usr/local/jdk1.3.1/bin/java'</filename>).</entry>
+ <entry xml:lang="en">Path to the <command>java</command> executable.
+ Use this for executing Java programs (for example,
+ <filename>'/usr/local/openjdk6/bin/java'</filename>).</entry>
</row>
<row>
<entry><varname>JAVADOC</varname></entry>
- <entry>Path to the <command>javadoc</command> utility
+ <entry xml:lang="en">Path to the <command>javadoc</command> utility
program.</entry>
</row>
<row>
<entry><varname>JAVAH</varname></entry>
- <entry>Path to the <command>javah</command> program.</entry>
+ <entry xml:lang="en">Path to the <command>javah</command>
+ program.</entry>
</row>
<row>
<entry><varname>JAVAP</varname></entry>
- <entry>Path to the <command>javap</command> program.</entry>
+ <entry xml:lang="en">Path to the <command>javap</command>
+ program.</entry>
</row>
<row>
<entry><varname>JAVA_KEYTOOL</varname></entry>
- <entry>Path to the <command>keytool</command> utility program.
- This variable is available only if the JDK is Java 1.2 or
- higher.</entry>
+ <entry xml:lang="en">Path to the <command>keytool</command> utility
+ program.</entry>
</row>
<row>
<entry><varname>JAVA_N2A</varname></entry>
- <entry>Path to the <command>native2ascii</command> tool.</entry>
+ <entry xml:lang="en">Path to the <command>native2ascii</command>
+ tool.</entry>
</row>
<row>
<entry><varname>JAVA_POLICYTOOL</varname></entry>
- <entry>Path to the <command>policytool</command> program.
- This variable is available only if the JDK is Java 1.2 or
- higher.</entry>
+ <entry xml:lang="en">Path to the <command>policytool</command>
+ program.</entry>
</row>
<row>
<entry><varname>JAVA_SERIALVER</varname></entry>
- <entry>Path to the <command>serialver</command> utility
- program.</entry>
+ <entry xml:lang="en">Path to the <command>serialver</command>
+ utility program.</entry>
</row>
<row>
<entry><varname>RMIC</varname></entry>
- <entry>Path to the RMI stub/skeleton generator,
+ <entry xml:lang="en">Path to the RMI stub/skeleton generator,
<command>rmic</command>.</entry>
</row>
<row>
<entry><varname>RMIREGISTRY</varname></entry>
- <entry>Path to the RMI registry program,
+ <entry xml:lang="en">Path to the RMI registry program,
<command>rmiregistry</command>.</entry>
</row>
<row>
<entry><varname>RMID</varname></entry>
- <entry>Path to the RMI daemon program <command>rmid</command>.
- This variable is only available if the JDK is Java 1.2
- or higher.</entry>
+ <entry xml:lang="en">Path to the RMI daemon program
+ <command>rmid</command>.</entry>
</row>
<row>
<entry><varname>JAVA_CLASSES</varname></entry>
- <entry>Path to the archive that contains the JDK class
- files. On JDK 1.2 or later, this is
- <filename>${JAVA_HOME}/jre/lib/rt.jar</filename>. Earlier
- JDKs used
- <filename>${JAVA_HOME}/lib/classes.zip</filename>.</entry>
- </row>
-
- <row>
- <entry><varname>HAVE_JIKES</varname></entry>
- <entry>Defined whenever <command>jikes</command> is used by
- the port (see <varname>USE_JIKES</varname> above).</entry>
+ <entry xml:lang="en">Path to the archive that contains the
+ <acronym>JDK</acronym> class files,
+ <filename>${JAVA_HOME}/jre/lib/rt.jar</filename>.</entry>
</row>
</tbody>
</tgroup>
</table>
- <para>You may use the <literal>java-debug</literal> make target
- to get information for debugging your port. It will display the
- value of many of the forecited variables.</para>
+ <para xml:lang="en">Use the <buildtarget xml:lang="en">java-debug</buildtarget> make
+ target to get information for debugging the port. It will
+ display the value of many of the previously listed
+ variables.</para>
- <para>Additionally, the following constants are defined so all
+ <para xml:lang="en">Additionally, these constants are defined so all
Java ports may be installed in a consistent way:</para>
- <table frame="none">
- <title>Constants defined for ports that use Java</title>
+ <table frame="none" xml:id="using-java-constants">
+ <title xml:lang="en">Constants Defined for Ports That Use Java</title>
<tgroup cols="2">
<thead>
<row>
- <entry>Constant</entry>
- <entry>Value</entry>
+ <entry>常數</entry>
+ <entry xml:lang="en">Value</entry>
</row>
</thead>
+
<tbody>
<row>
<entry><varname>JAVASHAREDIR</varname></entry>
- <entry>The base directory for everything related to Java.
- Default: <filename>${PREFIX}/share/java</filename>.
- </entry>
+ <entry xml:lang="en">The base directory for everything related to
+ Java. Default:
+ <filename>${PREFIX}/share/java</filename>.</entry>
</row>
<row>
<entry><varname>JAVAJARDIR</varname></entry>
- <entry>The directory where JAR files should be installed.
- Default:
+ <entry xml:lang="en">The directory where JAR files is
+ installed. Default:
<filename>${JAVASHAREDIR}/classes</filename>.</entry>
</row>
<row>
<entry><varname>JAVALIBDIR</varname></entry>
- <entry>The directory where JAR files installed by other
- ports are located. Default:
+ <entry xml:lang="en">The directory where JAR files installed by
+ other ports are located. Default:
<filename>${LOCALBASE}/share/java/classes</filename>.</entry>
</row>
</tbody>
</tgroup>
</table>
- <para>The related entries are defined in both
+ <para xml:lang="en">The related entries are defined in both
<varname>PLIST_SUB</varname> (documented in
<xref linkend="plist-sub"/>) and
<varname>SUB_LIST</varname>.</para>
+ </sect2>
- </sect2>
-
- <sect2 xml:id="java-building-with-ant">
- <title>Building with Ant</title>
-
- <para>When the port is to be built using Apache Ant, it has to
- define <varname>USE_ANT</varname>. Ant is thus considered to be
- the sub-make command. When no <literal>do-build</literal> target
- is defined by the port, a default one will be set that simply
- runs Ant according to <varname>MAKE_ENV</varname>,
- <varname>MAKE_ARGS</varname> and <varname>ALL_TARGETS</varname>.
- This is similar to the <varname>USE_GMAKE</varname> mechanism,
- which is documented in <xref linkend="building"/>.</para>
-
- <para>If <command>jikes</command> is used in place of
- <command>javac</command> (see <varname>USE_JIKES</varname> in
- <xref linkend="java-variables"/>), then Ant will automatically
- use it to build the port.</para>
-
- </sect2>
-
- <sect2 xml:id="java-best-practices">
- <title>Best practices</title>
-
- <para>When porting a Java library, your port should install the
- JAR file(s) in <filename>${JAVAJARDIR}</filename>, and everything
- else under <filename>${JAVASHAREDIR}/${PORTNAME}</filename>
- (except for the documentation, see below). In order to reduce
- the packing file size, you may reference the JAR file(s) directly
- in the <filename>Makefile</filename>. Just use the following
- statement (where <filename>myport.jar</filename> is the name
- of the JAR file installed as part of the port):</para>
-
- <programlisting>PLIST_FILES+= %%JAVAJARDIR%%/myport.jar</programlisting>
-
- <para>When porting a Java application, the port usually installs
- everything under a single directory (including its JAR
- dependencies). The use of
- <filename>${JAVASHAREDIR}/${PORTNAME}</filename> is strongly
- encouraged in this regard. It is up the porter to decide
- whether the port should install the additional JAR dependencies
- under this directory or directly use the already installed ones
- (from <filename>${JAVAJARDIR}</filename>).</para>
-
- <para>Regardless of the type of your port (library or application),
- the additional documentation should be installed in the
- <link linkend="install-documentation">same location</link> as for
- any other port. The JavaDoc tool is known to produce a
- different set of files depending on the version of the JDK that
- is used. For ports that do not enforce the use of a particular
- JDK, it is therefore a complex task to specify the packing list
- (<filename>pkg-plist</filename>). This is one reason why
- porters are strongly encouraged to use the
- <varname>PORTDOCS</varname> macro. Moreover, even if you can
- predict the set of files that will be generated by
- <command>javadoc</command>, the size of the resulting
- <filename>pkg-plist</filename> advocates for the use of
- <varname>PORTDOCS</varname>.</para>
-
- <para>The default value for <varname>DATADIR</varname> is
- <filename>${PREFIX}/share/${PORTNAME}</filename>. It is a good
- idea to override <varname>DATADIR</varname> to
- <filename>${JAVASHAREDIR}/${PORTNAME}</filename> for Java ports.
- Indeed, <varname>DATADIR</varname> is automatically added to
- <varname>PLIST_SUB</varname> (documented in <xref linkend="plist-sub"/>) so you may use
- <literal>%%DATADIR%%</literal> directly in
- <filename>pkg-plist</filename>.</para>
-
- <para>As for the choice of building Java ports from source or
- directly installing them from a binary distribution, there is
- no defined policy at the time of writing. However, people from
- the <link xlink:href="http://www.freebsd.org/java/">&os; Java Project</link>
- encourage porters to have their ports built from source whenever
- it is a trivial task.</para>
-
- <para>All the features that have been presented in this section
- are implemented in <filename>bsd.java.mk</filename>. If you
- ever think that your port needs more sophisticated Java support,
- please first have a look at the <link xlink:href="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.java.mk">
- bsd.java.mk CVS log</link> as it usually takes some time to
- document the latest features. Then, if you think the support
- you are lacking would be beneficial to many other Java ports,
- feel free to discuss it on the &a.java;.</para>
-
- <para>Although there is a <literal>java</literal> category for
- PRs, it refers to the JDK porting effort from the &os; Java
- project. Therefore, you should submit your Java port in the
- <literal>ports</literal> category as for any other port, unless
- the issue you are trying to resolve is related to either a JDK
- implementation or <filename>bsd.java.mk</filename>.</para>
-
- <para>Similarly, there is a defined policy regarding the
- <varname>CATEGORIES</varname> of a Java port, which is detailed
- in <xref linkend="makefile-categories"/>.</para>
-
- </sect2>
-
- </sect1>
-
- <sect1 xml:id="using-php">
- <title>Web applications, Apache and PHP</title>
-
- <sect2 xml:id="using-apache">
- <title>Apache</title>
-
- <table frame="none">
- <title>Variables for ports that use Apache</title>
-
- <tgroup cols="2">
- <tbody>
-
- <row>
- <entry><varname>USE_APACHE</varname></entry>
-
- <entry>The port requires Apache. Possible values:
- <literal>yes</literal> (gets any version),
- <literal>1.3</literal>, <literal>2.0</literal>,
- <literal>2.2</literal>, <literal>2.0+</literal>,
- etc. Default dependency is on version
- <literal>1.3</literal>.</entry>
- </row>
-
- <row>
- <entry><varname>WITH_APACHE2</varname></entry>
-
- <entry>The port requires Apache 2.0. Without this variable,
- the port will depend on Apache 1.3. This variable is
- deprecated and should not be used anymore.</entry>
- </row>
-
- <row>
- <entry><varname>APXS</varname></entry>
-
- <entry>Full path to the <command>apxs</command> binary.
- Can be overriden in your port.</entry>
- </row>
-
- <row>
- <entry><varname>HTTPD</varname></entry>
-
- <entry>Full path to the <command>httpd</command> binary.
- Can be overriden in your port.</entry>
- </row>
-
- <row>
- <entry><varname>APACHE_VERSION</varname></entry>
-
- <entry>The version of present Apache installation (read-only
- variable). This variable is only available after inclusion
- of <filename>bsd.port.pre.mk</filename>. Possible values:
- <literal>13</literal>, <literal>20</literal>,
- <literal>22</literal>.</entry>
- </row>
+ <sect2 xml:id="java-building-with-ant">
+ <title xml:lang="en">Building with Ant</title>
+
+ <para xml:lang="en">When the port is to be built using Apache Ant, it has to
+ define <varname>USE_ANT</varname>. Ant is thus considered to
+ be the sub-make command. When no
+ <buildtarget xml:lang="en">do-build</buildtarget> target is defined by the
+ port, a default one will be set that runs Ant according to
+ <varname>MAKE_ENV</varname>, <varname>MAKE_ARGS</varname> and
+ <varname>ALL_TARGET</varname>. This is similar to the
+ <literal>USES= gmake</literal> mechanism, which is documented
+ in <xref linkend="building"/>.</para>
+ </sect2>
- <row>
- <entry><varname>APACHEMODDIR</varname></entry>
+ <sect2 xml:id="java-best-practices">
+ <title xml:lang="en">Best Practices</title>
+
+ <para xml:lang="en">When porting a Java library, the port has to install
+ the JAR file(s) in <filename>${JAVAJARDIR}</filename>, and
+ everything else under
+ <filename>${JAVASHAREDIR}/${PORTNAME}</filename> (except for
+ the documentation, see below). To reduce the packing file
+ size, reference the JAR file(s) directly in the
+ <filename>Makefile</filename>. Use this statement (where
+ <filename><replaceable>myport</replaceable>.jar</filename> is
+ the name of the JAR file installed as part of the
+ port):</para>
+
+ <programlisting xml:lang="en">PLIST_FILES+= ${JAVAJARDIR}/<replaceable>myport</replaceable>.jar</programlisting>
+
+ <para xml:lang="en">When porting a Java application, the port usually
+ installs everything under a single directory (including its
+ JAR dependencies). The use of
+ <filename>${JAVASHAREDIR}/${PORTNAME}</filename> is strongly
+ encouraged in this regard. It is up the porter to decide
+ whether the port installs the additional JAR
+ dependencies under this directory or uses the
+ already installed ones (from
+ <filename>${JAVAJARDIR}</filename>).</para>
+
+ <para xml:lang="en">When porting a <trademark>Java</trademark> application that requires an
+ application server such as
+ <package role="port">www/tomcat7</package> to run the
+ service, it is quite common for a vendor to distribute a
+ <filename>.war</filename>. A <filename>.war</filename>
+ is a Web application ARchive and is extracted when
+ called by the application. Avoid adding a
+ <filename>.war</filename>
+ to <filename>pkg-plist</filename>.
+ It is not considered best practice. An application server
+ will expand <application>war</application> archive, but not
+ clean it up properly if the port is removed. A more
+ desirable way of working with this file is to extract the
+ archive, then install the files, and lastly add these files
+ to <filename>pkg-plist</filename>.</para>
+
+ <programlisting xml:lang="en">TOMCATDIR= ${LOCALBASE}/apache-tomcat-7.0
+WEBAPPDIR= myapplication
+
+post-extract:
+ @${MKDIR} ${WRKDIR}/${PORTDIRNAME}
+ @${TAR} xf ${WRKDIR}/myapplication.war -C ${WRKDIR}/${PORTDIRNAME}
+
+do-install:
+ cd ${WRKDIR} &amp;&amp; \
+ ${INSTALL} -d -o ${WWWOWN} -g ${WWWGRP} ${TOMCATDIR}/webapps/${PORTDIRNAME}
+ @cd ${WRKDIR}/${PORTDIRNAME} &amp;&amp; ${COPYTREE_SHARE} \* ${WEBAPPDIR}/${PORTDIRNAME}</programlisting>
+
+ <para xml:lang="en">Regardless of the type of port (library or
+ application), the additional documentation is installed in the
+ <link linkend="install-documentation">same location</link> as
+ for any other port. The JavaDoc tool is known to produce a
+ different set of files depending on the version of the
+ <acronym>JDK</acronym> that is used. For ports that do not
+ enforce the use of a particular <acronym>JDK</acronym>, it is
+ therefore a complex task to specify the packing list
+ (<filename>pkg-plist</filename>). This is one reason why
+ porters are strongly encouraged to use
+ <varname>PORTDOCS</varname>. Moreover, even if the set of
+ files that will be generated by <command>javadoc</command> can
+ be predicted, the size of the resulting
+ <filename>pkg-plist</filename> advocates for the use of
+ <varname>PORTDOCS</varname>.</para>
+
+ <para xml:lang="en">The default value for <varname>DATADIR</varname> is
+ <filename>${PREFIX}/share/${PORTNAME}</filename>. It is a
+ good idea to override <varname>DATADIR</varname> to
+ <filename>${JAVASHAREDIR}/${PORTNAME}</filename> for Java
+ ports. Indeed, <varname>DATADIR</varname> is automatically
+ added to <varname>PLIST_SUB</varname> (documented in
+ <xref linkend="plist-sub"/>) so use
+ <literal>%%DATADIR%%</literal> directly in
+ <filename>pkg-plist</filename>.</para>
- <entry>Directory for Apache modules. This variable is
- automatically expanded in pkg-plist.</entry>
- </row>
+ <para xml:lang="en">As for the choice of building Java ports from source or
+ directly installing them from a binary distribution, there
+ is no defined policy at the time of writing. However,
+ people from the
+ <link xlink:href="http://www.freebsd.org/java/">FreeBSD Java
+ Project</link> encourage porters to have their ports
+ built from source whenever it is a trivial task.</para>
+
+ <para xml:lang="en">All the features that have been presented in this
+ section are implemented in <filename>bsd.java.mk</filename>.
+ If the port needs more sophisticated
+ Java support, please first have a look at the <link xlink:href="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.java.mk?view=log">bsd.java.mk
+ <application>Subversion</application> log</link> as it
+ usually takes some time to document the latest features.
+ Then, if the needed support that is lacking would be
+ beneficial to many other Java ports, feel free to discuss it
+ on the <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-java">FreeBSD Java Language mailing list</link>.</para>
+
+ <para xml:lang="en">Although there is a <literal>java</literal> category for
+ PRs, it refers to the <acronym>JDK</acronym> porting effort
+ from the FreeBSD Java project. Therefore, submit the Java port
+ in the <literal>ports</literal> category as for any other
+ port, unless the issue is related to either a
+ <acronym>JDK</acronym> implementation or
+ <filename>bsd.java.mk</filename>.</para>
+
+ <para xml:lang="en">Similarly, there is a defined policy regarding the
+ <varname>CATEGORIES</varname> of a Java port, which is
+ detailed in <xref linkend="makefile-categories"/>.</para>
+ </sect2>
+ </sect1>
- <row>
- <entry><varname>APACHEINCLUDEDIR</varname></entry>
+ <sect1 xml:id="using-php">
+ <title>網路應用程式, Apache 和 PHP</title>
- <entry>Directory for Apache headers. This variable is
- automatically expanded in pkg-plist.</entry>
- </row>
+ <sect2 xml:id="using-apache">
+ <title>Apache</title>
- <row>
- <entry><varname>APACHEETCDIR</varname></entry>
+ <table frame="none" xml:id="using-apache-variables">
+ <title xml:lang="en">Variables for Ports That Use Apache</title>
- <entry>Directory for Apache configuration files. This
- variable is automatically expanded in pkg-plist.</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
+ <tgroup cols="2">
+ <tbody>
- <table frame="none">
- <title>port Apache 模組時好用的變數</title>
+ <row>
+ <entry><varname>USE_APACHE</varname></entry>
+ <entry xml:lang="en">The port requires Apache. Possible values:
+ <literal>yes</literal> (gets any version),
+ <literal>22</literal>, <literal>24</literal>,
+ <literal>22-24</literal>, <literal>22+</literal>,
+ etc. The default APACHE version is
+ <literal>22</literal>. More details are available
+ in <filename>ports/Mk/bsd.apache.mk</filename> and
+ at <link xlink:href="http://wiki.freebsd.org/Apache/">wiki.freebsd.org/Apache/</link>.</entry>
+ </row>
- <tgroup cols="2">
- <tbody>
+ <row>
+ <entry><varname>APXS</varname></entry>
+ <entry xml:lang="en">Full path to the <command>apxs</command>
+ binary. Can be overridden in the port.</entry>
+ </row>
- <row>
- <entry><varname>MODULENAME</varname></entry>
+ <row>
+ <entry><varname>HTTPD</varname></entry>
+ <entry xml:lang="en">Full path to the <command>httpd</command>
+ binary. Can be overridden in the port.</entry>
+ </row>
- <entry>模組名稱。 預設值為
- <varname>PORTNAME</varname>. 範例:
- <literal>mod_hello</literal></entry>
- </row>
+ <row>
+ <entry><varname>APACHE_VERSION</varname></entry>
+ <entry xml:lang="en">The version of present Apache installation
+ (read-only variable). This variable is only
+ available after inclusion of
+ <filename>bsd.port.pre.mk</filename>. Possible
+ values: <literal>22</literal>,
+ <literal>24</literal>.</entry>
+ </row>
- <row>
- <entry><varname>SHORTMODNAME</varname></entry>
+ <row>
+ <entry><varname>APACHEMODDIR</varname></entry>
+ <entry xml:lang="en">Directory for Apache modules. This variable is
+ automatically expanded in
+ <filename>pkg-plist</filename>.</entry>
+ </row>
- <entry>簡化的模組名稱。 自動地由變數
- <varname>MODULENAME</varname> 產生,不過可以覆蓋它。
- 範例: <literal>hello</literal></entry>
- </row>
+ <row>
+ <entry><varname>APACHEINCLUDEDIR</varname></entry>
+ <entry xml:lang="en">Directory for Apache headers. This variable is
+ automatically expanded in
+ <filename>pkg-plist</filename>.</entry>
+ </row>
- <row>
- <entry><varname>AP_FAST_BUILD</varname></entry>
+ <row>
+ <entry><varname>APACHEETCDIR</varname></entry>
+ <entry xml:lang="en">Directory for Apache configuration files. This
+ variable is automatically expanded in
+ <filename>pkg-plist</filename>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
- <entry>使用 <command>apxs</command>
- 來編譯及安裝這個模組。</entry>
- </row>
+ <table frame="none" xml:id="using-apache-modules">
+ <title xml:lang="en">Useful Variables for Porting Apache Modules</title>
- <row>
- <entry><varname>AP_GENPLIST</varname></entry>
+ <tgroup cols="2">
+ <tbody>
- <entry>同樣地,也是自動產生
- <filename>pkg-plist</filename>。</entry>
- </row>
+ <row>
+ <entry><varname>MODULENAME</varname></entry>
+ <entry xml:lang="en">Name of the module. Default value is
+ <varname>PORTNAME</varname>. Example:
+ <literal>mod_hello</literal></entry>
+ </row>
- <row>
- <entry><varname>AP_INC</varname></entry>
+ <row>
+ <entry><varname>SHORTMODNAME</varname></entry>
+ <entry xml:lang="en">Short name of the module. Automatically
+ derived from <varname>MODULENAME</varname>, but can
+ be overridden. Example:
+ <literal>hello</literal></entry>
+ </row>
- <entry>在編譯時間加入一個目錄到標頭檔搜尋路徑。</entry>
- </row>
+ <row>
+ <entry><varname>AP_FAST_BUILD</varname></entry>
+ <entry xml:lang="en">Use <command>apxs</command> to compile and
+ install the module.</entry>
+ </row>
- <row>
- <entry><varname>AP_LIB</varname></entry>
+ <row>
+ <entry><varname>AP_GENPLIST</varname></entry>
+ <entry xml:lang="en">Also automatically creates a
+ <filename>pkg-plist</filename>.</entry>
+ </row>
- <entry>在編譯時間加入一個目錄到函式庫搜尋路徑。</entry>
- </row>
+ <row>
+ <entry><varname>AP_INC</varname></entry>
+ <entry xml:lang="en">Adds a directory to a header search path during
+ compilation.</entry>
+ </row>
- <row>
- <entry><varname>AP_EXTRAS</varname></entry>
+ <row>
+ <entry><varname>AP_LIB</varname></entry>
+ <entry xml:lang="en">Adds a directory to a library search path
+ during compilation.</entry>
+ </row>
- <entry>傳給
- <command>apxs</command> 額外的 flags。</entry>
- </row>
+ <row>
+ <entry><varname>AP_EXTRAS</varname></entry>
+ <entry xml:lang="en">Additional flags to pass to
+ <command>apxs</command>.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect2>
- </tbody>
- </tgroup>
- </table>
- </sect2>
+ <sect2 xml:id="web-apps">
+ <title>網路應用程式</title>
+
+ <para xml:lang="en">Web applications must be installed into
+ <filename>PREFIX/www/<replaceable>appname</replaceable></filename>.
+ This path is available both in
+ <filename>Makefile</filename> and in
+ <filename>pkg-plist</filename> as <varname>WWWDIR</varname>,
+ and the path relative to <varname>PREFIX</varname> is
+ available in <filename>Makefile</filename> as
+ <varname>WWWDIR_REL</varname>.</para>
+
+ <para xml:lang="en">The user and group of web server process are available
+ as <varname>WWWOWN</varname> and <varname>WWWGRP</varname>,
+ in case the ownership of some files needs to be changed. The
+ default values of both are <literal>www</literal>. Use
+ <literal>WWWOWN?= myuser</literal> and <literal>WWWGRP?=
+ mygroup</literal> if the port needs different values. This
+ allows the user to override them easily.</para>
+
+ <para xml:lang="en">Do not depend on Apache unless the web app explicitly
+ needs Apache. Respect that users may wish to run a web
+ app on different web server than Apache.</para>
+ </sect2>
- <sect2 xml:id="web-apps">
- <title>Web 應用程式</title>
+ <sect2 xml:id="php-variables">
+ <title>PHP</title>
- <para>Web 應用程式應該安裝到
- <filename>PREFIX/www/appname</filename>
- 。 For your convenience, this path is available both in
- <filename>Makefile</filename> and in <filename>pkg-plist</filename>
- as <varname>WWWDIR</varname>, and the path relative to
- <varname>PREFIX</varname> is available in
- <filename>Makefile</filename> as
- <varname>WWWDIR_REL</varname>.</para>
+ <table frame="none" xml:id="using-php-variables">
+ <title xml:lang="en">Variables for Ports That Use PHP</title>
- <para>The user and group of web server process are available as
- <varname>WWWOWN</varname> and <varname>WWWGRP</varname>, in case you
- need to change the ownership of some files. The default values of
- both are <literal>www</literal>. If you want different values for
- your port, use <literal>WWWOWN?= myuser</literal> notation, to allow
- user to override it easily.</para>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry><varname>USE_PHP</varname></entry>
+ <entry xml:lang="en">The port requires PHP. The value
+ <literal>yes</literal> adds a dependency on PHP.
+ The list of required PHP extensions can be specified
+ instead. Example:
+ <literal>pcre xml gettext</literal></entry>
+ </row>
- <para>請別過於相依 Apache,除非這些程式有明確需要,而得相依 Apache
- 。也許有些使用者,會想在其他非 Apache 的 Web 伺服器上執行這些網頁程式。</para>
+ <row>
+ <entry><varname>DEFAULT_PHP_VER</varname></entry>
+ <entry xml:lang="en">Selects which major version of PHP will be
+ installed as a dependency when no PHP is installed
+ yet. Default is <literal>5</literal>. Possible
+ values: <literal>4</literal>,
+ <literal>5</literal></entry>
+ </row>
- </sect2>
+ <row>
+ <entry><varname>IGNORE_WITH_PHP</varname></entry>
+ <entry xml:lang="en">The port does not work with PHP of the given
+ version. Possible values: <literal>4</literal>,
+ <literal>5</literal></entry>
+ </row>
- <sect2 xml:id="php-variables">
- <title>PHP</title>
+ <row>
+ <entry><varname>USE_PHPIZE</varname></entry>
+ <entry xml:lang="en">The port will be built as a PHP
+ extension.</entry>
+ </row>
- <table frame="none">
- <title>Variables for ports that use PHP</title>
+ <row>
+ <entry><varname>USE_PH