diff options
| author | Xin LI <delphij@FreeBSD.org> | 2005-07-18 15:47:52 +0000 |
|---|---|---|
| committer | Xin LI <delphij@FreeBSD.org> | 2005-07-18 15:47:52 +0000 |
| commit | 5758471c401cec804c8ddffc1d353f8acbd891b2 (patch) | |
| tree | d05553f00406bf40e0059a28ff5775368415abf5 /zh_CN.GB2312/books | |
| parent | 0c7caf3db271f468b39df88904f9c8181a515ea1 (diff) | |
Notes
Diffstat (limited to 'zh_CN.GB2312/books')
| -rw-r--r-- | zh_CN.GB2312/books/porters-handbook/Makefile | 46 | ||||
| -rw-r--r-- | zh_CN.GB2312/books/porters-handbook/book.sgml | 8995 | ||||
| -rw-r--r-- | zh_CN.GB2312/books/porters-handbook/freebsd.dsl | 45 |
3 files changed, 9086 insertions, 0 deletions
diff --git a/zh_CN.GB2312/books/porters-handbook/Makefile b/zh_CN.GB2312/books/porters-handbook/Makefile new file mode 100644 index 0000000000..33ac3f1306 --- /dev/null +++ b/zh_CN.GB2312/books/porters-handbook/Makefile @@ -0,0 +1,46 @@ +# +# The FreeBSD Simplified Chinese Project +# +# Original Revision: 1.7 +# $FreeBSD$ +# +# Build the FreeBSD Porter's Handbook. +# + +MAINTAINER=doc@FreeBSD.org + +DOC?= book + +FORMATS?= html-split + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +# +# SRCS lists the individual SGML files that make up the document. Changes +# to any of these files will force a rebuild +# + +# SGML content +SRCS= book.sgml + +# Use the local DSSSL file +DSLHTML?= ${.CURDIR}/freebsd.dsl +DSLPRINT?= ${.CURDIR}/freebsd.dsl + +# Images from the cross-document image library +IMAGES_LIB+= callouts/1.png +IMAGES_LIB+= callouts/2.png +IMAGES_LIB+= callouts/3.png +IMAGES_LIB+= callouts/4.png +IMAGES_LIB+= callouts/5.png +IMAGES_LIB+= callouts/6.png +IMAGES_LIB+= callouts/7.png +IMAGES_LIB+= callouts/8.png +IMAGES_LIB+= callouts/9.png +IMAGES_LIB+= callouts/10.png + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/zh_CN.GB2312/books/porters-handbook/book.sgml b/zh_CN.GB2312/books/porters-handbook/book.sgml new file mode 100644 index 0000000000..f893d19ee6 --- /dev/null +++ b/zh_CN.GB2312/books/porters-handbook/book.sgml @@ -0,0 +1,8995 @@ +<!-- + The FreeBSD Documentation Project + The FreeBSD Simplified Chinese Project + + Original Revision: 1.589 + $FreeBSD$ +--> + +<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ +<!ENTITY % books.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Books Entity Set//EN"> +%books.ent; +]> + +<book> + <bookinfo> + <title>FreeBSD Porter 手册</title> + + <authorgroup> + <corpauthor>The FreeBSD Documentation Project</corpauthor> + </authorgroup> + + <pubdate>2000 年 4 月</pubdate> + + <copyright> + <year>2000</year> + <year>2001</year> + <year>2002</year> + <year>2003</year> + <year>2004</year> + <year>2005</year> + <holder role="mailto:doc@FreeBSD.org">The FreeBSD Documentation + Project</holder> + </copyright> + + &bookinfo.trademarks; + + &bookinfo.legalnotice; + </bookinfo> + + <chapter id="why-port"> + <title>介绍</title> + + <para>几乎每个人都是通过 FreeBSD Ports Collection + 在 FreeBSD 上面装应用程序 (“ports”)的。 + 就像FreeBSD的其他部分一样， 它主要来自于志愿者的努力。 + 所以在阅读这份文档的时候请务必记住这些。</para> + + <para>在 FreeBSD 的世界里， 任何人都能提交新的 port， + 或志愿地维护一个已有的 port， 如果那个 port 没人维护的话 — + 不需要任何特殊的权限来做这件事情。</para> + + </chapter> + + <chapter id="own-port"> + <title>自行制作 port</title> + + <para>那么， 您有兴趣创建自己的 port 或升级现有的 port？ + 太好了。</para> + + <para>下面的内容将会提供一些创建FreeBSD port的指导。 + 如果想升级一个现有的 port， 那么您应该在看完这些内容并阅读 + <xref linkend="port-upgrading">。</para> + + <para>因为这份文档不是十分详细， 您还应该再参考一下 + <filename>/usr/ports/Mk/bsd.port.mk</filename>， 所有 port + 的 Makefile 文件都会包含它。 即使不是每天都去摆弄 Makefile， + 您也会从那个文件里面获得很多知识， 里面的注释非常详细。 + 还有要补充一下，如果您有其他的问题， 可以给&a.ports; + 这个 mailing list 发信。</para> + + <note> + <para>在这份文档里提到的大部分的变量 + (<makevar><replaceable>VAR</replaceable></makevar>) + 是不能修改的。 大多 (但不是全部) 都在 + <filename>/usr/ports/Mk/bsd.port.mk</filename> + 的开始部分进行了介绍； 其他一些也应该可以在那里找到。 + 注意这些文件使用了非标准的制表符： + <application>Emacs</application> 和 + <application>Vim</application> 应该能在打开文件的时候自动识别它， + 而 &man.vi.1; 和 &man.ex.1 则需要在打开文件的时候通过 + <command>:set tabstop=4</command> 来修正默认的设置。</para> + </note> + </chapter> + + <chapter id="quick-porting"> + <title>简单的 port</title> + + <para>这一章主要介绍如何快速创建一个简单的 port。 + 很多时候， 这点内容是不够的， 您需要阅读这份文档中更深入的内容。</para> + + <para>首先， 需要取得包含源代码的 tar包， 并把它放到 + <makevar>DISTDIR</makevar>变量所指的地方。 默认的情况下， 这应该是 + <filename>/usr/ports/distfiles</filename>。</para> + + <note> + <para>下面的内容假定您不需要修改软件的源代码就能在 FreeBSD + 上编译通过。 如果需要修改代码， 就需要参考下一章的内容了。</para> + </note> + + <sect1 id="porting-makefile"> + <title>编写 <filename>Makefile</filename></title> + + <para>最简单的 <filename>Makefile</filename> + 应该是这个样子的：</para> + + <programlisting># New ports collection makefile for: oneko +# Date created: 5 December 1994 +# Whom: asami +# +# $FreeBSD$ +# + +PORTNAME= oneko +PORTVERSION= 1.1b +CATEGORIES= games +MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ + +MAINTAINER= asami@FreeBSD.org +COMMENT= A cat chasing a mouse all over the screen + +MAN1= oneko.1 +MANCOMPRESSED= yes +USE_IMAKE= yes + +.include <bsd.port.mk></programlisting> + + <para>看看您是否能够看懂。 不必担心 + <literal>$FreeBSD$</literal> + 那一行， 当这个 port 被导入到 ports 树里的时候， + CVS 会自动填写它。 您可以在 <link linkend="porting-samplem"> + 示范的 Makefile</link>那章找到更多的细节。</para> + </sect1> + + + <sect1 id="porting-desc"> + <title>创建描述文件</title> + + <para>有 2 个描述文件对于任何一个 port 来说是必须的， + 不论它是不是打算成为 package。 它们是 + <filename>pkg-descr</filename> 和 + <filename>pkg-plist</filename>。 这两个文件使用 <filename>pkg-</filename> + 前缀以区别于其他文件。</para><!-- NOT GOOD --> + + <sect2> + <title><filename>pkg-descr</filename> (关于 port 的冗长描述文件)</title> + + <para>这是 port 里一个较长的描述文件。 + 使用一段或几段文件文字来简明的描述这个 ports 是用来做什么的。</para> + + <note> + <para>这 <emphasis> 不是</emphasis> 手册或者对如何 + 深入使用/编译这个port的说明！ <emphasis>要是您从 + <filename>README</filename> 或者联机手册里面中复制文字的话， + 请务必小心</emphasis>； 通常， 它们不是对这个 port + 简明扼要的描述， 或者用了难以使用的格式 (比如， + 联机手册里有迫使两端对齐的空格)。 + 如果要移植的软件有官方的WWW网页， 您应该在这里列出来。 + 使用 <literal>WWW:</literal> 作为前缀来表示 + <emphasis>一个</emphasis>网站， + 这样其他的自动工具就能正常工作了。</para> + </note> + + <para>建议您在文件的最后留下您的名字， + 就像这样:</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/ + +- Satoshi +asami@cs.berkeley.edu</programlisting> + </sect2> + + <sect2> + <title><filename>pkg-plist</filename> (port 的装箱单)</title> + + <para>这份文件列出了 port 安装的所有文件。 + 之所以也被称为 装箱单 (“packing list”) 是因为 package + 的制作就是将这份列表里的文件打包。 + 这个文件中， 路径是相对于安装的路径的 (通常是 + <filename>/usr/local</filename> 或 + <filename>/usr/X11R6</filename>)。 如果您使用 + <makevar>MAN<replaceable>n</replaceable></makevar> + 变量的话， 请不要在这里列出任何联机手册。</para> + + <para>下面是一个简单的例子：</para> + + <programlisting>bin/oneko +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> + + <para>参考 &man.pkg.create.1; 的联机手册以获得更多有关装箱单的细节</para> + + <note> + <para>您应该在列表里列出所有的文件而不仅仅是目录名。 + 如果这个 port 在安装的过程中给自己创建了目录， + 则一定要加入 <literal>@dirrm</literal> 以便在删除这个 + port 时能将这些目录也一并删除。</para> + + <para>建议您将这个文件里的所有的文件名按字母排序。 + 这样， 在升级这个port的时候就能够更方便地核实所做的修改。</para> + + <para>手工创建一份这样的文件列表将会是一件非常枯燥的事情。 + 如果 port 要安装非常多的文件的话， 请参考 <link + linkend="porting-autoplist">自动创建这个文件列表</link> + 一节， 会帮您省下不少时间。</para> + </note> + + <para>只有一种情况可以不用 <filename>pkg-plist</filename>文件。 + 如果这个 port 只安装很少量的一些文件或目录的话， + 这些文件和目录就可以分别列在 <filename>Makefile</filename> 的 + <makevar>PLIST_FILES</makevar>和<makevar>PLIST_DIRS</makevar> + 变量里。 举个例子来说， 我们可以在上面那个 + <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 不需要给它自己创建目录的话， + 就不用设置 <makevar>PLIST_DIRS</makevar> 变量了。</para> + + <para>这样列出 port 要安装的文件很目录的代价就是， + 将无法使用在 &man.pkg.create.1; 里面介绍的命令来建立 package。 + 因此， 这种方法仅仅适合一些简单的 port， + 因为它会让这些 port 变得更为简单。 此外， + 这样做也有助于减少 port collection 中的文件数量。 + 请在打算采用 <filename>pkg-plist</filename> 前考虑一下这个方法。</para> + + <para>稍后我们将看到 <filename>pkg-plist</filename> 和 + <makevar>PLIST_FILES</makevar> 如何处理 + <link linkend="porting-plist">更复杂的任务</link>。</para> + </sect2> + </sect1> + + <sect1 id="porting-checksum"> + <title>创建校验和文件</title> + + <para>只要键入 <command>make makesum</command>， + port 便会自动创建 <filename>distinfo</filename>文件。</para> + + <para>如果下载的文件的校验和经常变化， + 而您又能确保它们的来源可靠 (比如， 来自于CD制造商， + 或每天构建生成的文档文件)， 就应该在 <makevar>IGNOREFILES</makevar> + 里面标明这些文件。 这样， 再运行 + <command>make makesum</command> 的时候便不会把这些标记 + <literal>IGNORE</literal> 的文件计算在内了。 + </sect1> + + <sect1 id="porting-testing"> + <title>测试 port</title> + + <para>应当确定您的 port 确实做了您希望它们做的事情， + 包括打包。下面是需要重点检查的一些重要的工作。</para> + + + <itemizedlist> + <listitem> + <para><filename>pkg-plist</filename> 中没有包括任何不想安装的文件</para> + </listitem> + + <listitem> + <para><filename>pkg-plist</filename> 包含了所有应该安装的文件</para> + </listitem> + + <listitem> + <para>您的 port 能够使用 <maketarget>reinstall</maketarget> + 多次安装。</para> + </listitem> + + <listitem> + <para>您的 port 能在 deinstall 以后自动完成 + <link linkend="porting-cleaning">清理</link></para> + </listitem> + </itemizedlist> + + <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 <replaceable>package-name</replaceable> + </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>确信在 <maketarget>package</maketarget> 和 + <maketarget>deinstall</maketarget> 阶段没有任何警告。 + 第三步以后， 检查是否所有新建的目录都被正确删除了。 + 在第四步以后， 试着运行一下所装的软件， + 确保当它以 package 方式安装的时候也能正常工作。</para> + </sect1> + + <sect1 id="porting-portlint"> + <title>用 <command>portlint</command> 来检查 port</title> + + <para>请使用 <command>portlint</command> 命令来检查您的 + port 是否符合我们的规范。 <command>portlint</command> + 程序是 ports collection 的一部分。 另外， 您也许要检查 + <link linkend="porting-samplem">Makefile</link> + 是否符合规范， 以及 + <link linkend="porting-pkgname">package</link> + 是否被恰当地命名。</para> + </sect1> + + <sect1 id="porting-submitting"> + <title>提交 port</title> + + <para>首先， 确信您已经阅读了 + <link linkend="porting-dads">该做什么和不该做什么</link> 一节。</para> + + <para>既然您很满意您的 port， 剩下的工作便是把它放进 + FreeBSD 的 ports树， 使得其他的人也喜欢它。 我们不需要您的 + <filename>work</filename> 目录或者 + <filename>pkgname.tgz</filename> 包， 所以现在可以删除它们了。 + 下一步，只要把 + <command>shar `find port_dir`</command>命令的输出 + 放在一份 bug 报告中， 用 &man.send-pr.1; 程序提交 (请参阅 + <ulink url="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL"> + Bug Reports and General Commentary</ulink> 以获得更多关于 + &man.send-pr.1;的详情。) 如果未压缩的 + port 大于 20KB， 您可能希望把它压缩成 tar 包， 并在把它加进 + bug报告前使用 &man.uuencode.1; (虽然小于 20KB + 的 bug 报告也可以使用采用 uuencode 编码的 tar包， + 但是我们并不鼓励这样做。) 确保您的 bug 报告按照 <literal>ports</literal> + 和 <literal>change-request</literal> 分类， (注意不要把 + Bug 报告标记成 机密， 即 <literal>confidential</literal> 的！) + 在 PR 的 <quote>Description</quote> 一栏里填写一下您的 + port 的简单描述， 同时将 shar 或 uuencode 编码的 tar 文件填在 + <quote>Fix</quote> 那一栏。</para> + + <note> + <para>在问题报告里面使用了一段好的描述， + 能使我们的工作变得更容易。 我们更倾向于这样的描述： + 用 <quote>New port: <category>/<portname> + <short description of the port></quote> + 来说明这是一个新的 port， 而用 + <quote>Update port: <category>/<portname> + <short description of the update></quote> + 来说明这是对一个已有的 port 的升级。 如果您坚持使用这样的方案， + 那么我们将更容易更方便地阅读您的 PR。<para> + </note> + + <para>再次声明， <emphasis>不要包含原始的distfile， + <filename>work</filename>目录， 或者您用 + <command>make package</command> 制作的包</emphasis>。</para> + + <para>在您提交的您的 port 以后请耐心等待。 + 有时在一个 port 正式加入 FreeBSD 之前需要花费好几个月， + 尽管也有可能是几天。 您可以查看 + <ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports"> + 正等待被 commit 到 FreeBSD 的 port</ulink>。</para> + + <para>一旦我们看过了您的报告， 有必要的话我们会联系您， + 并把它放到 ports 树里。 您的名字也会出现在 + <ulink url="&url.articles.contributors;/contrib-additional.html">Additional FreeBSD Contributors</ulink> + 和其他的文件。 不是很棒吗!? <!-- smiley --> + :-)</para> + </sect1> + </chapter> + + <chapter id="slow"> + <title>复杂的 Porting</title> + + <para>好了， 也许工作没那么简单， port 需要做些修改才能够在 + FreeBSD 上跑起来。 在这一章里， + 我们将会一步步举例来介绍应该如何修改来使您的 + port 能在 FreeBSD 上面运行。</para> + + <sect1 id="slow-work"> + <title>整个系统是如何运转的?</title> + + <para>首先， 这一系列的动作是由用户在您的 + port 目录里敲入 <command>make</command> 后发生的。 + 您也许会发现在另外的一个窗口里阅读一下 + <filename>bsd.port.mk</filename> 将会有助于您的理解。</para> + + <para>要是您不是非常明白 <filename>bsd.port.mk</filename> + 是做什么的话， 也不用太担心， 很多人都不知道的... + <!-- smiley --><emphasis>:-></emphasis></para> + + <procedure> + + <step> + <para><maketarget>fetch</maketarget> 会首先被执行。 + <maketarget>fetch</maketarget> 将检查在本地的 + <makevar>DISTDIR</makevar> 目录里是否存在 + tar 包。 如果 <maketarget>fetch</maketarget> + 没有找到就会查找 Makefile 中定义的 + <makevar>MASTER_SITES</makevar> URL， 还有我们的主 + FTP 站点 <ulink + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/"></ulink>， + 在那里我们备份了所有被认可的 distfile。 假设那个 + <makevar>MASTER_SITES</makevar> 站点是直接连在 Internet 上的， + 就会试着用 <makevar>FETCH</makevar> 指定的程序取回 + distfile。 如果成功的话， 文件会被保存在<makevar>DISTDIR</makevar> + 所指定的目录以备稍后使用。</para> + </step> + + <step> + <para>接下来会执行 <maketarget>extract</maketarget>。 + 它会在 <makevar>DISTDIR</makevar> 中寻找您的 + tar 包 (通常是用 gzip 压缩的 tar 包)，然后解压缩到由 + <makevar>WRKDIR</makevar> 所指定的临时目录里 + (默认为<filename>work</filename>目录)。</para> + </step> + + <step> + <para>下一步是执行 <maketarget>patch</maketarget>。 + 首先任何在 <makevar>PATCHFILES</makevar> 中定义的补丁都会被打上。 + 然后， 在由 <makevar>PATCHDIR</makevar> 指定的目录 + (默认为 <filename>files</filename>目录) + 中发现的<filename>patch-<replaceable>*</replaceable></filename>， + 它们将会以文件名的字母顺序被先后打上。</para> + </step> + + <step> + <para><maketarget>configure</maketarget>会被执行。 + 这一步骤可能会有以下几种情形。</para> + + <orderedlist> + <listitem> + <para>如果存在 <filename>scripts/configure</filename>， + 就会执行它</para> + </listitem> + + <listitem> + <para>如果定义了 <makevar>HAS_CONFIGURe</makevar> + 或者 <makevar>GNU_CONFIGURE</makevar>， 就会执行 + <filename><makevar>WRKSRC</makevar>/configure</filename>。</para> + </listitem> + + <listitem> + <para>如果定义了<makevar>USE_IMAGE</makevar>， 就会执行 + <makevar>XMKMF</makevar> (默认为: <command>xmkmf + -a</command>)。</para> + </listitem> + </orderedlist> + </step> + + <step> + <para><maketarget>build</maketarget>会被执行。 + 这一步将会进入ports的工作目录 + (<makevar>WRKSRC</makevar>) + 然后进行编译。如果定义了<makevar>USE_GMAKE</makevar>， + 就会使用 GNU <command>make</command>， 反之， + 则会使用系统默认的 <command>make</command>。</para> + </step> + </procedure> + + <para>以上都是系统默认的步骤。 您也可以定义 + <maketarget>pre-<replaceable>something</replaceable></maketarget> 或者 + <maketarget>post-<replaceable>something</replaceable></maketarget>， + 或者把以此命名的脚本放到 + <filename>scripts</filename> 目录， + 它们会在默认的动作之前或之后被执行。</para> + + <para>举个例子， 如果您在您的 <filename>Makefile</filename> + 里定义了<maketarget>post-extract</maketarget>， 并在 + <filename>script</filename> 目录里放了一个 + <filename>pre-build</filename> 脚本， + 那么在 tar 包解开之后 + <maketarget>post-extract</maketarget> 将被调用， + <filename>pre-build</filename> 脚本会在默认的编译之前被执行。 + 我们推荐您在 <filename>Makefile</filename> + 定义所有的动作， 如果不是十分复杂的话， + 这样， 别人能更容易明白您的 port + 需要执行哪些非默认的动作。</para> + + <para>默认的行为都是由 <filename>bsd.port.mk</filename> 定义的 + <maketarget>do-<replaceable>something</replaceable></maketarget> + 来表示的。 例如， port 中用来解压缩的命令是由 + <maketarget>do-extract</maketarget> 来定义的。 + 如果您对默认的设置不满意， 可以通过在 + <filename>Makefile</filename> 重新定义 + <maketarget>do-<replaceable>someting</replaceable></maketarget> + 来做些改变。</para> + + <note> + <para><quote>主</quote> 动作 (例如 + <maketarget>extract</maketarget>、 + <maketarget>configure</maketarget>， 等等) + 仅仅是用来确定所有相应的阶段都完成了， + 以及调用真实的动作或脚本， 它们不应被修改。 + 如果您想要修改解压缩这个动作， + 可以修改 <maketarget>do-extract</maketarget>， + 但永远都不要改变 <maketarget>extract</maketarget> + 的操作！</para> + </note> + + <para>我们已经介绍了在用户敲入 <command>make</command> + 之后会发生哪些事情了。 接下来我们将进行进一步的学习， + 来看一看如何创建一个理想的 port。</para> + </sect1> + + <sect1 id="slow-sources"> + <title>获取源代码</title> + + <para>获取源代码的 tar 包 (通常是 + <filename><replaceable>foo</replaceable>.tar.gz</filename> 或者 + <filename><replaceable>foo</replaceable>.tar.Z</filename>) 并把它们放进 + <makevar>DISTDIR</makevar>。 最好使用 <emphasis>主流</emphasis> 的版本。</para> + + <para>您需要设置变量 <makevar>MASTER_SITES</makevar> + 来指向原始 tar 包的获取位置。 您可以在 + <filename>bsd.sites.mk</filename> + 里找到一些速度较快的主流站点。 请使用这些站点 — + 和相关的定义 — 如果可能的话， + 应尽量避免在同一个源代码树里出现大量重复的信息。 + 这些站点会随着时间而变化， + 如果每个人都随意加入的话会使维护变得非常困难。</para> + + <para>如果您找不到一个有很好网络连接的 + FTP/HTTP 站点， 或者它们使用了非标准的格式， + 您也许就会想在您自己的 FTP 或 HTTP + 服务器上放上一份副本。</para> + + <para>如果您找不到可靠的地方放置 distfiles， + 我们也可以提供给您一些空间来保存它。 + 我们自己的 <hostid>ftp.FreeBSD.org</hostid>； + 然而这只是一个折衷的办法。 distfile 必须放进某人在 + <hostid>freefall</hostid> 上的 + <filename>~/public_distfiles/</filename> + 目录中。 可以要求帮助您 commit port 的人来放这个 + distfile， 而这个人也需要把 <makevar>MASTER_SITES</makevar>、 + <makevar>MASTER_SITE_LOCAL</makevar> 以及 + <makevar>MASTER_SITE_SUBDIR</makevar> 的设置， + 改为在 <hostid>freefall</hostid> 上的用户名。</para> + + <para>如果您的 port 的 distfile 一直在变化， + 而作者拒绝改变其版本号， 您可以考虑把 distfiles + 放在自己的主页， 并在 <makevar>MASTER_SITES</makevar> + 里把原作者的列为首选位置。 如果可能， 试着与 port + 的作者沟通一下让他不要这么做， 这将有助于建立对源代码的控制。 + 在您的主页上放置您自己的 distfile 会避免用户得到 + <errorname>checksum mismatch</errorname> + 的错误， 而且能减轻我们 FTP 站点维护人员的工作量。 + 如果您的port只有一个主站点的话， 我们建议您在自己的网站上做一份备份， + 并他列为 <makevar>MASTER_SITES</makevar>的第2项。</para> + + <para>如果您的 port 需要来自网络上的一些补丁， 请把它们放到 + <makevar>DISTDIR</makevar>里。 不用担心它们跟源代码不是来自同一站点。 + 我们有办法处理 (参阅下面的 + <link linkend="porting-patchfiles">补丁文件</link>)。</para> + </sect1> + + <sect1 id="slow-modifying"> + <title>修改 port</title> + + <para>解开 tar 包， 对源代码做出合理的修改使得这个 port + 能在最新版本的 FreeBSD 上面运行。 + 一定要 <emphasis>仔细记录</emphasis> 您所做的每处改动， + 包括删除、添加、修改的文件等等， 这些修改以后会在您的 port + 中以脚本或补丁的方式出现， 并且能通过运行它们来自动完成您对 + port 的改动要求。</para> + + <para>如果您的 port 要求用与用户交互/配置来完成编译或安装的话， + 您可以看一下 Larry Wall 的经典的 <application>Configure</application> + 脚本， 适当地模仿一下。 Port collection 的目的， + 就是使每个 port 占用最少的空间， + 并做到软件的 <quote>即插即用</quote>。</para> + + <note> + <para>除非明确地声明， 否则您提交给 + FreeBSD ports collection 的补丁， + 脚本和其他的文件都将被假定以标准的 BSD 版权发布。</para> + </note> + </sect1> + + <sect1 id="slow-patch"> + <title>打补丁</title> + + <para>在您制作 port 的过程中， 文件的添加或修改都可以用 + &man.diff.1; 做成补丁， 使得今后的能够使用 &man.patch.1; + 在安装过程中自动对 port 做出相应的修改。 + 每一个您想要打的补丁应该以 + <filename>patch-<replaceable>*</replaceable></filename> + 这样形式的文件名保存， <replaceable>*</replaceable> + 表示将要被打补丁的文件名， + 例如 <filename>patch-Imakefile</filename> + 或 <filename>patch-src-config.h</filename> 这样。 + 这些文件应该被放在 <makevar>PATCHDIR</makevar> 里， + 这样这些补丁都会被自动打上。 + 所有的补丁必须相对于 <makevar>WRKSRC</makevar> 的 + (port 会把 tarball 解压缩在那里， 并完成余下的其他动作)。 + 为了使修改和升级变得更容易， 应避免使用多个 + patch 去修改同一个文件 (比如， + <filename>patch-file</filename> 和 <filename>patch-file2</filename> + 都修改 <filename><makevar>WRKSRC</makevar>/foobar.c</filename> + 就应被避免)。<para> + + <para>只有 <literal>[-+._a-zA-Z0-9]</literal> 这些字符， + 可以出现在补丁的文件名中， 请务必不要使用除这些字符以外的其他字符。 + 不要把您的补丁命名成 <filename>patch-aa</filename> + 或 <filename>patch-ab</filename> 等这样的名字， + 最好能在补丁名中提到路径和文件名。</para> + + <para>不要把 RCS 字符串放进补丁。 我们把文件放进 ports + 树的时候， CVS 会损坏它们， 当我们再 check out 出来的时候， + 它们就会和原来的不一样， 从而导致打补丁失败。 RCS 字符串 + 是由美元符号 (<literal>$</literal>) 围绕的， + 通常由 <literal>$Id</literal> 或 + <literal>$RCS</literal> 开头。</para> + + <para>使用 &man.diff.1; 的递归选项(<option>-r</option>) + 很好， 但是请检查一下最后输出的 patch， + 确保没有任何的垃圾信息。 特别地， 有 2 种文件不需要 diff， + 并且应该删除： 一种是 <filename>Makefile</filename>， + 当您的port使用了<command>Imake</command>， + 或者 GNU <command>configure</command> 等等的话。 + 如果您不得不编辑<filename>configure.in</filename> + 以使 <command>autoconf</command> 去生成 + <command>configure</command>， 不要使用 + <command>configure</command> 来做 diff + (这常常会有好几千行长!)； 请定义 + <literal>USE_AUTOCONF_VER=213</literal> 并对应 + <filename>configure.in</filename> 来制作 diff。</para> + + <para>往往在移植某个软件的时候会遇到这样一种情况， + 特别是这个软件是在 &windows; 上开发的时候， + 大多数的源代码都需要进行CR/LF的转换。 + 这也许会给以后打补丁， 编译警告、 脚本执行造成问题 ( + <command>/bin/sh^M</command> not found) 等等。 + 您能加入以下这行代码来快速地把那些文件从 + CR/LF 转换到 LF：</para> + + <programlisting>USE_REINPLACE= yes + +post-extract: + @${FIND} -E ${WRKDIR} -type f -iregex ".*\.(c|cpp|h|txt)" -print0 | \ + ${XARGS} -0 ${REINPLACE_CMD} -e 's/[[:cntrl:]]*$$//'</programlisting> + + <para>当然， 如果您想要处理所有文件的话， + 就可以省略上面的 <option>-iregex</option> 选项。 + 请注意这段代码会从被处理文件的每一行里面剔除所有的控制字符。 + (但不包括 <literal>\n</literal>)。</para> + + <para>假如需要删除文件， 您可以在 + <maketarget>post-extract</maketarget> 里面做这件事， + 而不是在把它作为一个补丁。 一旦您对您所做修改的感觉比较满意， + 那么请把diff输出分成一个补丁对应一个源文件。</para> + </sect1> + + <sect1 id="slow-configure"> + <title>配置</title> + + <para>把任何附加的配置命令加进您的 + <filename>configure</filename> 脚本并把它保存到 + <filename>scripts</filename> 子目录。 如前面提到的那样， + 您也能在 <filename>Makefile</filename> 和/或 + 使用 <filename>pre-configure</filename> 或 + <filename>post-configure</filename> 的脚本来做同样的事情。</para> + </sect1> + + <sect1 id="slow-user-input"> + <title>处理用户输入</title> + + <para>如果您的 port 要求用户的输入以便配置编译、 或安装配置过程， + 就必须在 <filename>Makefile</filename> 里设置 + <makevar>IS_INTERACTIVE</makevar> 变量。 + 如果用户设置了 <envar>BATCH</envar> 的话， + 这将让用户能跳过您的 port 来完成 + <quote>通宵编译</quote> (如果用户设置了 + <envar>INTERACTIVE</envar>的话， 那么 <emphasis>只有</emphasis> + 那些要求互动的 port 才会被编译) + 这将给那些不停编译 ports 的机器省下很多时间。</para> + + <para>通常我们还建议， + 如果对于那些问题能有合理的缺省答案的话， 应检查一下 + <makevar>PACKAGE_BUILDING</makevar> 变量， + 并根据其设置决定是否执行关闭交互脚本。 + 这将允许我们为 CDROM 和 FTP 来编译 package。</para> + </sect1> + </chapter> + + <chapter id="makefile"> + <title>配置 Makefile</title> + + <para>配置 <filename>Makefile</filename> 是相当简单的， + 我们在此建议您在开始之前看一下现有的例子。 + 在这份手册里也有一个 + <link linkend="porting-samplem">Makefile例子</link>， + 照着里面变量的顺序来写能使得您的 port + 更容易地被其他人看懂。</para> + + <para>现在， 当您开始编写您新的<filename>Makefile</filename> + 的时候， 可以依次思考一下以下的问题：</para> + + <sect1 id="makefile-source"> + <title>作者发布的代码</title> + + <para>放在 <makevar>DISTDIR</makevar> 中的是不是标准的用 gzip 压缩的 + tar 包， 例如 <filename>foozolix-1.2.tar.gz</filename>？ + 如果是， 可以先略过这一节。 如果不是， + 您应当看看是不是要覆盖这些变量： <makevar>DISTVERSION</makevar>、 + <makevar>DISTNAME</makevar>、 + <makevar>EXTRACT_CMD</makevar>、 + <makevar>EXTRACT_BEFORE_ARGS</makevar>、 + <makevar>EXTRACT_AFTER_ARGS</makevar>、 + <makevar>EXTRACT_SUFX</makevar>， + <makevar>DISTFILES</makevar>，取决于您 port 的 distfile + 格式有多么怪异。 (最常见的一个例子便是 + <literal>EXTRACT_SUFX=.tar.Z</literal>， 一般这是因为 tar + 包是用 <command>compress</command> 而不是 + <command>gzip</command> 压缩的时候。)</para> + + <para>最糟的情况是， 您需要自己编写 + <maketarget>do-extract</maketarget> + 来覆盖默认的定义， 尽管这不常见， + 但如果遇到了， 还是需要这么做。</para> + </sect1> + + <sect1 id="makefile-naming"> + <title>命名</title> + + <para>Makefile 的第一部分便是 port + 的名字、 版本号， 以及它所属的分类。</para> + + <sect2> + <title><makevar>PORTNAME</makevar> 和 <makevar>PORTVERSION</makevar></title> + + <para>您应该把 <makevar>PORTNAME</makevar> 设置为您 + port 的名字， <makevar>PORTVERSION</makevar> + 则是 port 的版本号。</para> + </sect2> + + <sect2 id="makefile-naming-revepoch"> + <title><makevar>PORTREVISION</makevar> 和 + <makevar>PORTEPOCH</makevar></title> + + <sect3> + <title><makevar>PORTREVISION</makevar> (port 的修订版本号)</title> + + <para><makevar>PORTERVISION</makevar> + 变量是一个单调递增的值， 如果不为 + 0， 就会被加到包名的后面， + 当 <makevar>PORTVERSION</makevar> 增加 + 的时候应被置 0 (也就是当官方有新版本发布的时候)。 + <makevar>PORTREVISION</makevar> + 会被自动化工具 (比如 &man.pkg.version.1;) + 用来检测是否存在可用的新版本。</para> + + <para>每当 port 发生变化并对生成的 + package 的内容或结构有显著影响时， + 都应增加 <makevar>PORTREVISION</makevar> + 值。</para> + + <para>下面是一些应当修改 <makevar>PORTREVISION</makevar> + 的情况：</para> + + <itemizedlist> + <listitem> + <para>有新的补丁用来修正安全漏洞、 + 错误， 或给 port 添加了新的功能。</para> + </listitem> + + <listitem> + <para>修改了 <filename>Makefile</filename> + 里编译时开启或禁用的选项。</para> + </listitem> + + <listitem> + <para>修改了要安装文件的列表或安装时的行为 + (例如， 修改了一个用来给 package + 初始化数据的脚本， 如 ssh host keys)。<para> + </listitem> + + <listitem> + <para>一个port依赖的共享库版本改变 + (在这种情况下， 当安装了新版本的共享库， + 后再去安装较早的软件就会出错， + 因为它们要依赖老的 libfoo.x + 而不是libfoo.(x+1))。</para> + </listitem> + + <listitem> + <para>原作者修改了 port distfile， 并且 distfile + 的新老版本之间用 + <command>diff -ru</command> 只能发现一些细微的变化， + 这时我们只需要对 + <filename>distinfo</filename> 做相应的修正， + 而不需要修改 + <makevar>PORTVERSION</makevar>。</para> + </listitem> + </itemizedlist> + + <para>不需要修改 + <makevar>PORTREVISION</makevar> 的例子：</para> + + <itemizedlist> + <listitem> + <para>port 结构风格的改变， + 但对于打成的包没有功能的上的变化。</para> + </listitem> + + <listitem> + <para><makevar>MASTER_SITES</makevar> + 发生变化， 或进行了对 port 功能的修改， + 但不致影响最后打成的包。</para> + </listitem> + + <listitem> + <para>对 distfiles 诸如修正拼写错误之类的补丁， + 对用户而言没有升级上的麻烦。<para> + </listitem> + + <listitem> + <para>对一个原本编译失败的包的修改， + 使其可编译， 而没有加入新功能。 因为 + <makevar>PORTREVISION</makevar> + 表示包的内容发生了变化， + 如果先前没有可编译的包， 也就不需要修改 + <makevar>PORTREVISION</makevar> + 来表示变化。</para> + </listitem> + </itemizedlist> + + <para>一个修改并提交 port 的原则是： + 使得别人能从中受益 (改进、 修改已有错误， + 或使新的 package 能够运行)， + 您还要权衡一下这是否应让那些经常更新 + ports 树的人升级， + 如果回答是 <quote>是</quote> 的话， + <makevar>PORTREVISION</makevar> + 就应该修改了。</para> + </sect3> + + <sect3> + <title><makevar>PORTEPOCH</makevar> (port 的加权版本号)</title> + + <para>有时软件商或 FreeBSD 的 + porter 会使用比旧版的版本号小的数字做为新版本号的情况。 + 举例来说， 从 + foo-20000801 到 foo-1.0 (从形式上来说这是不对的， + 因为 20000801 在数值上比1大很多)。</para> + + <para>在这种情况下， <makevar>PORTEPOCH</makevar> + 应当增加。 如果 + <makevar>PORTEPOCH</makevar> 非 0， + 就应当加到包名字的后面。 + <makevar>PORTEPOCH</makevar> + 永远不能被减少或清零， + 因为那样会导致与前一时期的 package + 比较版本时产生不正确的结果。 + (就是说， 那个 package 就不会被检测到已经过时了。) + 新的版本号 (比如前面在前面那个例子中的 + <literal>1.0,1</literal>) 在数值上比前一个版本 + (20000801) 小， 但多数自动化的工具会认为 + <literal>,1</literal> + 后缀意味着比前一个包的后缀 <literal>,0</literal> 大。</para> + + <para>错误的去除或重置 + <makevar>PORTEPOCH</makevar> + 会导致很多不幸发生； 如果您还不明白前面的讨论， + 请多阅读几次直至明白为止， + 或到邮件列表上来提问。</para> + + <para>大多数 port 都不会用到 + <makevar>PORTEPOCH</makevar>， + 并且如果某个软件的下一个版本改变了版本号结构的话， + 用巧妙的方法来设定 <makevar>PORTVERSION</makevar> + 也能避免使用 <makevar>PORTEPOCH</makevar>。 然而， + FreeBSD porter 也需要注意， 当有新版本的软件发布， + 但并非正式版本时 — 比如 + <quote>snapshot</quote> 版本， + 原作者可能会使用当时的日期来命名， + 这在新的 <quote>官方</quote> 版本发布的时候， + 就很容易引起前面提到的问题。</para> + + <para>举个例子， 如果 snapshot 版本的发布日期是 + 20000917， 这个软件的上一个版本是1.2， + 那么这个版本的 <makevar>PORTVERSIN</makevar> 应该设为 + 1.2.20000917 或类似的样子， 而不是20000917， + 这样在 1.3 发布以后， + 新版本就可以在数值上大于旧的版本了。</para> + </sect3> + + <sect3> + <title>关于 <makevar>PORTREVISION</makevar> 和 + <makevar>PORTEPOCH</makevar> 的用例</title> + + <para><literal>gtkmumble</literal> port，版本号 + <literal>0.10</literal>， 被提交到 + ports collection:</para> + + <programlisting>PORTNAME= gtkmumble +PORTVERSION= 0.10</programlisting> + + <para><makevar>PKGNAME</makevar> 变成 + <literal>gtkmumble-0.10</literal>。</para> + + <para>然后有人发现了一个安全漏洞， + 需要用一个FreeBSD的补丁。 <makevar>PORTREVISION</makevar> + 就要相应的增加。</para> + + <programlisting>PORTNAME= gtkmumble +PORTVERSION= 0.10 +PORTREVISION= 1</programlisting> + + <para><makevar>PKGNAME</makevar>变成了 + <literal>gtkmumble-0.10_1</literal</para> + + <para>软件的作者发布了新的版本， 版本为 + <literal>0.2</literal> (作者本来的意思是， + 用 <literal>0.10</literal> 表示 + <literal>0.1.0</literal>，<quote>而不是指 + 0.9 之后的那个版本</quote> - 但是现在太迟了)。 + 因为现在的次版本号 <literal>2</literal> + 在数值上比上一个版本 <literal>10</literal> 小， + <makevar>PORTEPOCH</makevar> 必须增加， + 以使新的 package 被认为是 <quote>更新的</quote>。 + 由于那是作者发布的一个新版本， 因此 + <makevar>PORTREVISION</makevar> 应被置0 (或者从 + <filename>Makefile</filename> 里面删除它)。</para> + + <programlisting>PORTNAME= gtkmumble +PORTVERSION= 0.2 +PORTEPOCH= 1</programlisting> + + <para><makevar>PKGNAME</makevar> 变成了 + <literal>gtkmumble-0.2,1</literal></para> + + <para>下一个版本将会是 0.3。 + 由于 <makevar>PORTEPOCH</makevar> 从不减少， + 那么就无须改动：</para> + + <programlisting>PORTNAME= gtkmumble +PORTVERSION= 0.3 +PORTEPOCH= 1</programlisting> + + <para><makevar>PKGNAME</makevar> 变成 + <literal>gtkmumble-0.3,1</literal></para> + + <note> + <para>如果在这次升级中 <makevar>PORTEPOCH</makevar> + 被置为了<literal>0</literal>， 那么在装了 + <literal>gtkmumble-0.10_1</literal> 包的机器上就无法检测到 + <literal>gtkmumble-0.3</literal> 包的更新， + 因为 <literal>3</literal> 在数值上比 + <literal>10</literal> 小。 记住， 这是 + <makevar>PORTEPOCH</makevar> 最重要的地方。</para> + </note> + </sect3> + </sect2> + + <sect2> + <title><makevar>PKGNAMEPREFIX</makevar> 和 <makevar>PKGNAMESUFFIX</makevar></title> + + <para>2 个可选的变量， <makevar>PKGNAMEPREFIX</makevar> 和 + <makevar>PKGNAMESUFFIX</makevar> 可以和 + <makevar>PORTNAME</makevar> 还有 + <makevar>PORTVERSION</makevar> 配合使用， + 形成像这样的 <makevar>PKGNAME</makevar>： + <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>。 + 请确定符合我们的 + <link linkend="porting-pkgname">包命名规则</link>。 + 当然， <emphasis>不</emphasis> 允许在 + <makevar>PORTVERSION</makevar> + 中使用连字符 (<literal>-</literal>)。 如果包名有 + <replaceable>language-</replaceable> 或 + <replaceable>-compiled.specifics</replaceable> 部分 (见下文)， + 请分别用 <makevar>PKGNAMEPREFIX</makevar> 和 + <makevar>PKGNAMESUFFIX</makevar>， 不要直接加到 + <makevar>PORTNAME</makevar> 中。</para> + </sect2> + + <sect2 id="porting-pkgname"> + <title>包命名规则</title> + + <para>以下是您在命名您的包时应当遵守的规则。 + 这将使得我们放包的目录更利于浏览， + 因为我们已经有数以万计的包了， + 如果用户觉得查看包名很困难的话， + 他们会很快走开的。</para> + + <para>一个包的名字应该看起来像这样： + <filename><replaceable><optional>language<optional>_region</optional></optional>-name<optional><optional>-</optional>compiled.specifics</optional>-version.numbers</replaceable></filename>。</para> + + <para>要像这样来定义包的名字： + <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>。 + 确保所有的变量符合上面的格式。</para> + + <orderedlist> + <listitem> + <para>FreeBSD 会尽力去支持用户当地的语言。 + 如果这个 port 是某种语言专用的， 那么 + <replaceable>language-</replaceable> 部分应该是 + 由 ISO-639 定义的自然语言的 2 个字母缩写。 比如， + <literal>ja</literal>是表示日本， <literal>ru</literal> + 是表示俄罗斯， <literal>vi</literal> 表示越南， + <literal>zh</literal> 表示中国， <literal>ko</literal> + 表示韩国， <literal>de</literal> 表示德国。</para> + + <para>如果是针对某种语言的某一地区的话， + 再要加上2个字母的国家代码。 例如， + <literal>en_US</literal> 表示美国英语， + <literal>fr_CH</literal> 表示瑞士法语。</para> + + <para><replaceable>language-</replaceable> 部分应该在 + <makevar>PKGNAMEPREFIX</makevar> 变量里设置。</para> + </listitem> + + <listitem> + <para><filename>name</filename> 部分的首字母应该 + 小写。 (余下的部分能包含大写字母， 所以当您 + 要转换一个包含大写字母软件的名字时， 您需要 + 自己做出判断。) 对于<literal>perl 5</literal> + 模块的命名， 有个传统的规则是， 在前面 + 加上 <literal>p5-</literal> + 并把两个冒号的部分改为连字号， 如： + <literal>Data::Dumper</literal> 模块变成 + <literal>p5-Data-Dumper</literal>。 + 如果软件的名字里还有数字、 连字号、 下划线， + 您也可以把这些包括进来 (例如 <literal>kinput2</literal>)。</para> + </listitem> + + <listitem> + <para>如果这个 port 能将不同的默认设置 + <link linkend="porting-masterdir">硬编码</link> + 进程序 (通常是部分的目录名)， 那么 + <replaceable>-compiled.specifics</replaceable> + 应该声明被编译进去的默认设置 (连字号是可选的)。 + 这样的用例包括纸张大小和不同的字体。</para> + + <para><replaceable>-compiled.specifics</replaceable> + 部分应该在 <makevar>PKGNAMESUFFIX</makevar> + 变量里设置。</para> + </listitem> + + <listitem> + <para>版本号应该紧随在连字号 + (<literal>-</literal>) 后面并由数字和字母组成。 + 特别指出， 另外的连字号是不允许出现在版本号里的。 + 唯一例外的是字符串 <literal>pl</literal> + (表示 <quote>patchlevel</quote>)， + <emphasis>只能</emphasis> + 用在软件没有主版本号和次版本号的情况下。 + 如果软件的版本号里出现了像 + <quote>alpha</quote>， <quote>beta</quote>， + <quote>rc</quote>， <quote>pre</quote>， + 取第一个字母把它放在小数点的后面。 + 如果在版本号里一直出现那些名字， + 那么在数字和字母之间不应有多余的小数点。</para> + + <para>这个方法是为了更容易得凭版本号来排序 port。 + 特别注意的是， 确保版本号之间的每部分都由小数点来分隔， + 如果日期也是版本号的一部分， 就用这样的格式， + <literal><replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal> + 或者 + <literal><replaceable>dd</replaceable>.<replaceable>mm</replaceable>.<replaceable>yyyy</replaceable></literal> + 这样的格式， 而非 + <literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable>， + 因为后者不适合表示千年的格式。</literal> + </para> + </listitem> + </orderedlist> + + <para>这里是一些真实的例子， + 我们藉此说明如何把软件作者对软件的命名， + 转换为适合我们包的命名方式：</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="6"> + <thead> + <row> + <entry>发行版的名字</entry> + <entry><makevar>PKGNAMEPREFIX</makevar></entry> + <entry><makevar>PORTNAME</makevar></entry> + <entry><makevar>PKGNAMESUFFIX</makevar></entry> + <entry><makevar>PORTVERSION</makevar></entry> + <entry>说明</entry> + </row> + </thead> + + <tbody> + <row> + <entry>mule-2.2.2</entry> + <entry>(空)</entry> + <entry>mule</entry> + <entry>(空)</entry> + <entry>2.2.2</entry> + <entry>没什么需要修改的</entry> + </row> + + <row> + <entry>XFree86-3.3.6</entry> + <entry>(空)</entry> + <entry>XFree86</entry> + <entry>(空)</entry> + <entry>3.3.6</entry> + <entry>没什么需要修改的</entry> + </row> + + <row> + <entry>EmiClock-1.0.2</entry> + <entry>(空)</entry> + <entry>emiclock</entry> + <entry>(空)</entry> + <entry>1.0.2</entry> + <entry>程序的名字不能使用大写字母</entry> + </row> + + <row> + <entry>rdist-1.3alpha</entry> + <entry>(空)</entry> + <entry>rdist</entry> + <entry>(空)</entry> + <entry>1.3.a</entry> + <entry>像 <literal>alpha</literal> + 这样的字符串是不允许出现的</entry> + </row> + + <row> + <entry>es-0.9-beta1</entry> + <entry>(空)</entry> + <entry>es</entry> + <entry>(空)</entry> + <entry>0.9.b1</entry> + <entry>像 <literal>beta</literal> + 这样的字符串是不允许出现的</entry> + </row> + + <row> + <entry>mailman-2.0rc3</entry> + <entry>(空)</entry> + <entry>mailman</entry> + <entry>(空)</entry> + <entry>2.0.r3</entry> + <entry>像 <literal>rc</literal> + 这样的字符串是不允许出现的</entry> + </row> + + <row> + <entry>v3.3beta021.src</entry> + <entry>(空)</entry> + <entry>tiff</entry> + <entry>(空)</entry> + <entry>3.3</entry> + <entry>那个是啥鬼东西？</entry> + </row> + + <row> + <entry>tvtwm</entry> + <entry>(空)</entry> + <entry>tvtwm</entry> + <entry>(空)</entry> + <entry>pl11</entry> + <entry>总需要有个版本号吧</entry> + </row> + + <row> + <entry>piewm</entry> + <entry>(空)</entry> + <entry>piewm</entry> + <entry>(空)</entry> + <entry>1.0</entry> + <entry>总需要有个版本号吧</entry> + </row> + + <row> + <entry>xvgr-2.10pl1</entry> + <entry>(空)</entry> + <entry>xvgr</entry> + <entry>(空)</entry> + <entry>2.10.1</entry> + <entry><literal>pl</literal> 只允许在没有 + 主/次 版本号的情况下才能出现</entry> + </row> + + <row> + <entry>gawk-2.15.6</entry> + <entry>ja-</entry> + <entry>gawk</entry> + <entry>(空)</entry> + <entry>2.15.6</entry> + <entry>日文版</entry> + </row> + + <row> + <entry>psutils-1.13</entry> + <entry>(空)</entry> + <entry>psutils</entry> + <entry>-letter</entry> + <entry>1.13</entry> + <entry>纸张大小已经在编译的时候被硬编码到程序里了</entry> + </row> + + <row> + <entry>pkfonts</entry> + <entry>(空)</entry> + <entry>pkfonts</entry> + <entry>300</entry> + <entry>1.0</entry> + <entry>300dpi 字体的包</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>如果在原始的代码里没有版本号， + 或者原作者并不打算开发另外的版本， + 就应把版本号设成 <literal>1.0</literal> (就像前面 + <literal>piewm</literal> 的例子那样)。 否则， + 要求原始的作者加上版本号或使用日期 + (<literal><replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>) + 来作为版本号。</para> + </sect2> + </sect1> + + <sect1 id="makefile-categories"> + <title>分类</title> + + <sect2> + <title><makevar>CATEGORIES</makevar> (所属分类)</title> + + <para>在包制作完成之后， + 它会被放在 <filename>/usr/ports/packages/All</filename>， + 并建立一系列来自 + <filename>/usr/ports/packages</filename> + 下子目录的符号连接。 这些子目录的名称是由 + <makevar>CATEGORIES</makevar> + 指定的。 这将方便于那些用户在 FTP 站点或 CDROM + 的一大堆包里面寻找自己想要的包。 请查看一下 + <link linkend="porting-categories">目前的分类表</link>， + 并找出一个适合您 port 的分类。</para> + + <para>此列表也会决定您的 port 在 port + 目录中的位置。 如果您在这里设定了 1 个以上的分类， + 则认为您 port 文件应放到以第一个分类命名的子目录中。 请参阅 + <link linkend="choosing-categories">后面</link> + 关于如何选择正确分类的更多讨论。</para> + </sect2> + + <sect2 id="porting-categories"> + <title>目前的分类表</title> + + <para>这是目前 port 中的分类。 那些用星号 + (<literal>*</literal>) 标记的是 + <emphasis>虚拟</emphasis>分类 — + 它们在ports树里没有相应的子目录， + 因而只用来做为次要的分类， 用以方便搜索。</para> + + <note> + <para>对于非虚拟的分类来说， + 您会看到在相对应子目录中的 <filename>Makefile</filename> + 里有写在 <makevar>COMMENT</makevar> 里的单行描述。</para> + </note> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="3"> + <thead> + <row> + <entry>分类</entry> + <entry>描述</entry> + <entry>注意事项</entry> + </row> + </thead> + + <tbody> + <row> + <entry><filename>accessibility</filename></entry> + <entry>帮助残障人士的 port。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>afterstep*</filename></entry> + <entry>对于 + <ulink url="http://www.afterstep.org">AfterStep</ulink> + 窗口管理器的支持。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>arabic</filename></entry> + <entry>阿拉伯语言支持。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>archivers</filename></entry> + <entry>压缩与备份工具。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>astro</filename></entry> + <entry>有关天文学的 port。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>audio</filename></entry> + <entry>声音支持。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>benchmarks</filename></entry> + <entry>测评程序。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>biology</filename></entry> + <entry>生物学相关的软件。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>cad</filename></entry> + <entry>计算机辅助设计工具。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>chinese</filename></entry> + <entry>中文语言支持。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>comms</filename></entry> + <entry>通讯软件。</entry> + <entry>大部分是用于串口通讯的。</entry> + </row> + + <row> + <entry><filename>converters</filename></entry> + <entry>字符编码转换。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>databases</filename></entry> + <entry>数据库。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>deskutils</filename></entry> + <entry>在发明计算机以前就已经在桌面上使用的东西。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>devel</filename></entry> + <entry>程序开发工具。</entry> + <entry>不要把开发库放在这里 — + 除非您再也找不到更合适的分类， + 否则就不该放在这个分类里。</entry> + </row> + + <row> + <entry><filename>dns</filename></entry> + <entry>DNS 相关的软件。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>editors</filename></entry> + <entry>通用编辑器。</entry> + <entry>有特殊用途的编辑器应该被置于相应的分类中 + (比如， 数学-方程式 + 编辑器应该放在 <filename>math</filename> 分类里。</entry> + </row> + + <row> + <entry><filename>elisp*</filename></entry> + <entry>Emacs-lisp相关的port。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>emulators</filename></entry> + <entry>其他操作系统的模拟器。</entry> + <entry>终端模拟器 <emphasis>不应该</emphasis> + 属于这个分类 — 基于 X 的应该放在 + <filename>x11</filename> 而基于文本模式的应该放到 + <filename>comms</filename> 或 <filename>misc</filename> + 中去， 取决于具体的功能。</entry> + </row> + + <row> + <entry><filename>finance</filename></entry> + <entry>货币、 金融以及相关的应用程序。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>french</filename></entry> + <entry>法语语言支持。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>ftp</filename></entry> + <entry>FTP 客户端和服务器端的程序。</entry> + <entry>如果您的 port 同时支持 FTP 和 HTTP 的话， + 把它放进 <filename>ftp</filename> 并把 + <filename>www</filename> 做为第二分类。</entry> + </row> + + <row> + <entry><filename>games</filename></entry> + <entry>游戏。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>german</filename></entry> + <entry>德语语言支持。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>gnome*</filename></entry> + <entry>关于 + <ulink url="http://www.gnome.org">GNOME</ulink> + 项目的支持。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>graphics</filename></entry> + <entry>图形图象程序。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>haskell*</filename></entry> + <entry>有关 Haskell 编程语言的软件。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>hebrew</filename></entry> + <entry>希伯来语语言支持。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>hungarian</filename></entry> + <entry>匈牙利语语言支持。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>ipv6*</filename></entry> + <entry>IPv6 相关软件。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>irc</filename></entry> + <entry>IRC 相关程序</entry> + <entry></entry> + </row> + + <row> + <entry><filename>japanese</filename></entry> + <entry>日语语言支持。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>java</filename></entry> + <entry>有关 Java 编程语言的软件。</entry> + <entry><filename>java</filename> 分类对于一个 + port 来说并不是唯一的分类。 + 最好用来放和 Java 语言相关的 port， + 而且我们鼓励不要把 <filename>java</filename> + 做为一个 port 的主分类。</entry> + </row> + + <row> + <entry><filename>kde*</filename></entry> + <entry><ulink url="http://www.kde.org">K 桌面环境 (KDE)</ulink> + 相关的软件。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>korean</filename></entry> + <entry>韩语语言支持。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>lang</filename></entry> + <entry>编程语言。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>linux*</filename></entry> + <entry>Linux 相关的应用程序。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>lisp*</filename></entry> + <entry>和 Lisp 编程语言有关的软件。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>mail</filename></entry> + <entry>电子邮件软件。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>math</filename></entry> + <entry>数值计算和其他数学相关的软件。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>mbone</filename></entry> + <entry>MBone 应用程序。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>misc</filename></entry> + <entry>各式各样的实用程序。</entry> + <entry>通常不属于其他的任何分类， + 如果可能的话， 尽量为您的 port 选择 + <literal>misc</literal> + 以外的分类， 因为在这里的 + port 比较容易被人忽略。</entry> + </row> + + <row> + <entry><filename>multimedia</filename></entry> + <entry>多媒体软件。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>net</filename></entry> + <entry>各种网络相关的软件。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>net-mgmt</filename></entry> + <entry>网络管理软件。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>news</filename></entry> + <entry>USENET新闻组相关软件。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>offix*</filename></entry> + <entry><ulink url="http://leb.net/OffiX/">OffiX</ulink> 相关套件。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>palm</filename></entry> + <entry><ulink url="http://www.palm.com/">Palm™</ulink> 系列相关软件。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>parallel*</filename></entry> + <entry>并行计算相关软件。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>pear*</filename></entry> + <entry>Pear PHP 架构相关软件。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>perl5*</filename></entry> + <entry><application>Perl</application>5 相关的软件。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>plan9*</filename></entry> + <entry><ulink url="http://www.cs.bell-labs.com/plan9dist/">Plan9</ulink> 相关程序。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>polish</filename></entry> + <entry>波兰语语言语言支持。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>portuguese</filename></entry> + <entry>葡萄牙语语言支持。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>print</filename></entry> + <entry>打印相关的软件。</entry> + <entry>桌面出版工具 (打印预览工具等等) + 也可以放在此分类里。</entry> + </row> + + <row> + <entry><filename>python*</filename></entry> + <entry><ulink url="http://www.pythong.org/">Python</ulink> 编程语言相关的软件。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>ruby*</filename></entry> + <entry><ulink url="http://www.ruby-lang.org/">Ruby</ulink> 编程语言相关的软件。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>russian</filename></entry> + <entry>俄语语言支持。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>science</filename></entry> + <entry>科学相关但不适合放在 + <filename>astro</filename>、 + <filename>biology</filename>， 以及 + <filename>math</filename> 分类的 port。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>security</filename></entry> + <entry>安全相关的实用程序。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>shells</filename></entry> + <entry>命令行 shell。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>sysutils</filename></entry> + <entry>系统相关的实用程序。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>tcl76*</filename></entry> + <entry>依赖于 Tcl 7.6 版运行的 port。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>tcl80*</filename></entry> + <entry>依赖于 Tcl 8.0 版运行的 port。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>tcl81*</filename></entry> + <entry>依赖于 Tcl 8.1 版运行的 port。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>tcl82*</filename></entry> + <entry>依赖于 Tcl 8.2 版运行的 port。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>tcl83*</filename></entry> + <entry>依赖于 Tcl 8.3 版运行的 port。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>textproc</filename></entry> + <entry>文本处理的实用程序。</entry> + <entry>这个分类并不适合于那些应该放到 + <filename>print</filename> 的桌面出版工具。</entry> + </row> + + <row> + <entry><filename>tk42*</filename></entry> + <entry>依赖于 Tk 4.2 版运行的 port。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>tk80*</filename></entry> + <entry>依赖于 Tk 8.0 版运行的 port。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>tk81*</filename></entry> + <entry>依赖于 Tk 8.1 版运行的 port。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>tk82*</filename></entry> + <entry>依赖于 Tk 8.2 版运行的 port。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>tk83*</filename></entry> + <entry>依赖于 Tk 8.3 版运行的 port。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>tkstep80*</filename></entry> + <entry>需要 TkSTEP 8.0 来运行的 port。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>ukrainian</filename></entry> + <entry>乌克兰语语言支持。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>vietnamese</filename></entry> + <entry>越南语语言支持。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>windowmaker*</filename></entry> + <entry>WindowMaker 窗口管理器的相关支持。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>www</filename></entry> + <entry>Word Wide Web的相关软件。</entry> + <entry>HTML语言相关的支持也可以放在这个分类里。</entry> + </row> + + <row> + <entry><filename>x11</filename></entry> + <entry>X Window System以及相关软件。</entry> + <entry>这个分类是给那些直接支持X Window System + 的软件的。 不要把常规的 X 应用程序也放进这里； + 它们中的大多数都应被归类到 + <filename>x11-*</filename> (参见下文)。 + 如果您的 port <emphasis>是</emphasis> + X 应用程序， 应定义 <makevar>USE_XLIB</makevar> + (使用 <makevar>USER_IMAKE</makevar> 隐含包括它)， + 然后把它放到合适的分类里。</entry> + <entry> + </row> + + <row> + <entry><filename>x11-clocks</filename></entry> + <entry>X11 下的时钟程序。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>x11-fm</filename></entry> + <entry>X11 下的文件管理器。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>x11-fonts</filename></entry> + <entry>X11 下的字体以及相关工具。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>x11-servers</filename></entry> + <entry>X11 服务器。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>x11-toolkits</filename></entry> + <entry>X11 工具包。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>x11-wm</filename></entry> + <entry>X11 窗口管理器。</entry> + <entry></entry> + </row> + + <row> + <entry><filename>zope*</filename></entry> + <entry><ulink url="http://www.zope.org/">Zope</ulink> 相关的支持。</entry> + <entry></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect2> + + <sect2 id="choosing-categories"> + <title>选择正确的分类</title> + + <para>由于不少分类是重复的， 您通常在用哪个分类作为您 + port 的主分类上做出选择。 下面有几条规则能帮您解决这个问题。 + 这是一个带优先级的表， 按优先级降序罗列：</para> + + <itemizedlist> + <listitem> + <para>第一个分类必须是个物理的分类 (参阅 + <link linkend="porting-categories">前面</link>)。 + 这对于制作包是必要的。 + 虚拟分类和物理分类可能在包制作完成后混合在一起。</para> + </listitem> + + <listitem> + <para>对于特定语言的分类通常放在第一位。 + 例如， 如果您的 port 会安装一些 X11 的日文字体， + 那么 <makevar>CATEGORIES</makevar>那行 + 就应该是 <filename>japanese x11-fonts</filename>。</para> + </listitem> + + <listitem> + <para>有特定意义的分类应当被列在无特定意义的前面。 + 例如， HTML 编辑器应该是这样的 <filename>www + editors</filename>， 而不是其他的什么。 同样地， + 您不应该列出 <filename>net</filename>， 如果 port 属于 + <filename>irc</filename>、 <filename>mail</filename>、 + <filename>mbone</filename>、 <filename>news</filename>、 + <filename>security</filename>， 或是 <filename>www</filename>， + 因为 <filename>net</filename> 可以表示它们的超集。</para> + </listitem> + + <listitem> + <para>只有当主要的分类是一门自然语言的时候， + <filename>x11</filename> 能被做为第二分类。 + 需要特别指出的是， 您不应把 X 的应用程序也归类为 + <filename>x11</filename>。</para> + </listitem> + + <listitem> + <para><application>Emacs</application> + 模式应当于相应的应用程序放在同一个分类里， 而不是 + <filename>editors</filename> 分类。 举例来说， + 一个用于编辑某种编程语言源代码的 + <application>Emacs</application> + 模式应该被归为 + <filename>lang</filename> 一类。 + </para> + </listitem> + + <listitem> + <para><filename>misc</filename> + 分类的 port 不能有其他非虚拟的分类。 + 如果您在您的 <makevar>CATEGORIES</makevar> + 里设了 <literal>misc</literal> 和另外的分类， + 那意味着可以安全地删除 <literal>misc</literal> + 并把 port 放到其他的子目录中了！</para> + </listitem> + + <listitem> + <para>如果您的 port 确实不属于现有的分类， + 才把它放到 <filename>misc</filename>。</para> + </listitem> + </itemizedlist> + + <para>如果您不能确定使用哪个分类， 请在您提交的 + &man.send-pr.1; 里加上一行注释， + 这样我们就能在导入进 port 树之前讨论一下。 + 如果您是 committer， 发一份备忘到 &a.ports; + 先讨论一下。 很多情况是新的 port 被加到错误的分类里， + 然后又立即被移走。这会造成源代码库不必要和不良的膨胀。</para> + </sect2> + + <sect2 id="proposing-categories"> + <title>提议建立新的分类</title> + + <para>由于 Ports Collection 在持续增长， 已经引入了许多新的分类。 + 新的分类既可以是 <emphasis>虚拟的</emphasis> 分类 — + 这些分类在整个 ports 目录中没有属于自己的子目录 — + 或 <emphasis>物理的</emphasis> 分类 — 它们有自己的子目录。 + 接下来我们将讨论与建立新的物理分类有关的事项， + 以便帮助您理解如何提议建立新的分类。</para> + + <para>我们目前的做法是避免建立新的物理分类， 除非有非常多的 port + 应被归入这一分类， 或者 port 属于某一特定的小团体 (例如， + 与某种人类语言相关)， 或两者皆是。</para> + + <para>这样做的原因是这类修改会让 committer 和用户都不得不进行 <ulink + url="&url.articles.committers-guide;/#ports">许多工作</ulink> + 来在 Ports Collection 进行或追踪修改。 此外， + 提议新的分类通常都会引起争论。 (可能这是因为关于某个分类是否 + <quote>太大</quote> 一直没有非常一致的意见的缘故， + 另一方面， 分类是否能够能够有助于浏览 (以及多少个分类是合适的)， + 等等， 也都是问题。)</para> + + <para>下面是具体的步骤：</para> + + <procedure> + <step> + <para>在 &a.ports; 提议新的分类。 您应提供建立新分类的详细依据， + 包括为什么认为现有的分类不够， 以及希望移动位置的一系列 port + 的名字。 (如果有尚在 + <application>GNATS</application> 而未 commit 的 port， + 也应一一列出。) 如果您是相关 port 的监护人或提交者， + 说明这一情况可能有助于您的提议得到通过。</para> + </step> + + <step> + <para>参与讨论。</para> + </step> + + <step> + <para>如果有人支持您的建议， 应及时提交一个 PR， + 其中包括提议 PR 的理由， 以及需要移动的 port 的列表。 + 理想情况下， 这个 PR 也应包含针对下列文件的补丁：</para> + + <itemizedlist> + <listitem> + <para>进行 repocopy 之后对 <filename>Makefile</filename> + 进行的修改</para> + </listitem> + + <listitem> + <para>新分类的 <filename>Makefile</filename></para> + </listitem> + + <listitem> + <para>旧分类的 <filename>Makefile</filename></para> + </listitem> + + <listitem> + <para>依赖于旧 port 的 port 的 + <filename>Makefile</filename></para> + </listitem> + + <listitem> + <para>(此外， 作为一项加分因素， + 您还可以提供一些其它需要修改的文件， + 按照 Committer 指南所介绍的流程。)</para> + </listitem> + </itemizedlist> + </step> + + <step> + <para>由于这是一项影响 ports 基础设施的变动， + 它不仅涉及 repo-copy 的使用， + 而且也可能会影响构建集群的衰退测试操作， + 因此这类 PR 应分派给 &a.portmgr;。</para> + </step> + + <step> + <para>如果这一 PR 得到批准， 某个 committer 将按照在 + <ulink url="&url.articles.committers-guide;/#ports"> + Committer 指南</ulink> 中所介绍的步骤来完成余下的工作。</para> + </step> + </procedure> + + <para>提议新的虚拟分类和上述过程类似， 但会容易许多， + 因为不需要实际地移动任何 port。 这种情况下， PR 应附带的补丁， + 就只需要修改影响到的 port 的 Makefile， 以便在其中的 + <makevar>CATEGORIES</makevar> 中加入新的分类了。</para> + </sect2> + + <sect2 id="proposing-reorg"> + <title>提议对分类进行重新组织</title> + + <para>有些时候会有一些人提议重新将分类组织为 2-层 或某种基于关键字的结构。 + 目前为止， 还没有进行任何相关的改变， 因为尽管这些修改比较容易完成， + 但修改整个 Ports Collection 所需要进行的工作， 至少也是令人生畏的。 + 在发表您的观点之前， 请阅读在邮件列表存档中历史上所进行过的提议； + 此外， 您也会被要求提供一个可用的原形。</para> + </sect2> + </sect1> + + <sect1 id="makefile-distfiles"> + <title>源码包文件</title> + + <para>在 <filename>Makefile</filename> 中的第二部分是描述用于构建 port + 所必需下载的文件， 以及到什么地方去下载它们。</para> + + <sect2> + <title><makevar>DISTVERSION/DISTNAME</makevar> (源码包版本号/名称)</title> + + <para><makevar>DISTNAME</makevar> 是作者称呼您所 port 软件的名字。 + <makevar>DISTNAME</makevar> 的默认值是 + <literal>${PORTNAME}-${PORTVERSION}</literal>， + 因此只有在需要时才应手工指定。 + <makevar>DISTNAME</makevar> 只在两个地方用到。 第一处是源码包文件列表 + (<makevar>DISTFILES</makevar>)， 其默认值是 + <makevar>${DISTNAME}</makevar><makevar>${EXTRACT_SUFX}</makevar>。 + 第二处是源码包应被展开到的目录名， + 即 <makevar>WRKSRC</makevar> 所指定的目录， + 其默认值是 <filename>work/<makevar>${DISTNAME}</makevar></filename>。</para> + + <para>某些软件作者发布源码包的时候并不采取 + <literal>${PORTNAME}-${PORTVERSION}</literal> 这样的模式， + 这可以通过设置 <makevar>DISTVERSION</makevar> 来自动处理。 + <makevar>PORTVERSION</makevar> 和 <makevar>DISTNAME</makevar> + 会自动地展开， 当然， 也可以改掉它。 下表给出了一些例子：</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry><makevar>DISTVERSION</makevar></entry> + <entry><makevar>PORTVERSION</makevar></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> + </informaltable> + + <note> + <para><makevar>PKGNAMEPREFIX</makevar> 和 + <makevar>PKGNAMESUFFIX</makevar> 并不影响 + <makevar>DISTNAME</makevar>。 此外还应注意 + <makevar>WRKSRC</makevar> 等于 + <filename>work/<makevar>${PORTNAME}-${PORTVERSION}</makevar></filename>， + 而源代码的压缩包则可能是 + <makevar>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</makevar> + 以外的其它名字。 一般情况下应该保持 <makevar>DISTNAME</makevar> + 不变 — 更好的方法是定义 + <makevar>DISTFILES</makevar> 而不是同时设置 + <makevar>DISTNAME</makevar> 和 <makevar>WRKSRC</makevar> + (可能还有 <makevar>EXTRACT_SUFX</makevar>)。</para> + </note> + </sect2> + + <sect2> + <title><makevar>MASTER_SITES</makevar> (主流下载站点)</title> + + <para>记录 FTP/HTTP-URL 指向 <makevar>MASTER_SITES</makevar> + 中原始压缩档的目录部分。 不要忘了结尾的斜线 + (<filename>/</filename>)！</para> + + <para><command>make</command> 宏将尝试使用 + <makevar>FETCH</makevar> 来抓取所指定的源码包文件， + 如果无法在本地系统中找到这些文件的话。</para> + + <para>建议您指定多个镜像站点， 最好是在不同的大洲上的。 + 这样将有效地防止由于大范围网络问题所导致无法下载的问题。 + 我们甚至打算增加自动检测距离最近的站点并从那里下载的功能； + 使用多个站点是这样做的重要一步。</para> + + <para>如果原始的源码包是流行的软件， + 例如 X-contrib、 GNU， 或 Perl CPAN 等等之一， + 您可能会希望使用 + <makevar>MASTER_SITE_<replaceable>*</replaceable></makevar> + (例如 <makevar>MASTER_SITE_XCONTRIB</makevar> 和 + <makevar>MASTER_SITE_PERL_GNU</makevar>) 来简化撰写。 简单地将 + <makevar>MASTER_SITES</makevar> 设置为这些变量之一， 并使用 + <makevar>MASTER_SITE_SUBDIR</makevar> 来指定路径就可以达到目的。 + 下面是一个例子：</para> + + <programlisting>MASTER_SITES= ${MASTER_SITE_XCONTRIB} +MASTER_SITE_SUBDIR= applications</programlisting> + + <para>这些变量是在 + <filename>/usr/ports/Mk/bsd.sites.mk</filename> 中定义的。 + 新项目会随时增加， 因此在您提交 port 之前， + 应先看一看这个文件的最新版本。</para> + + <para>用户也可以在他们的 <filename>/etc/make.conf</filename> + 文件中自行设置 <makevar>MASTER_SITE_*</makevar> 变量， + 以便让系统使用他们的选择， 从他们喜欢的镜像站点进行下载。</para> + </sect2> + + <sect2> + <title><makevar>EXTRACT_SUFX</makevar> (压缩包所用的扩展名)</title> + + <para>如果您有一个源码包文件， + 而它使用了某种怪异的扩展名来表达压缩方法， 应设置 + <makevar>EXTRACT_SUFX</makevar>。</para> + + <para>例如， 如果源码包文件的名字是 + <filename>foo.tgz</filename> 而非更为一般的 + <filename>foo.tar.gz</filename>， 您应写上：</para> + + <programlisting>DISTNAME= foo +EXTRACT_SUFX= .tgz</programlisting> + + <para><makevar>USE_BZIP2</makevar> 和 <makevar>USE_ZIP</makevar> + 变量会自动根据需要将 <makevar>EXTRACT_SUFX</makevar> 设置为 + <literal>.tar.bz2</literal> 或 <literal>.zip</literal>。 + 如果这两个都没设置， 则 <makevar>EXTRACT_SUFX</makevar> 的 + 默认值将是 <literal>.tar.gz</literal>。</para> + + <note> + <para>任何时候都不需要同时设置 <makevar>EXTRACT_SUFX</makevar> 和 + <makevar>DISTFILES</makevar>.</para> + </note> + </sect2> + + <sect2> + <title><makevar>DISTFILES</makevar> (全部源代码包)</title> + + <para>有些时候所下载的文件名字和 port 的名字没有任何联系。 + 例如， 可能是 <filename>source.tar.gz</filename>， + 或者与此类似的其它名字。 也有一些其它的应用软件， + 它们的源代码可能被存放到了不同的压缩包中， 而且全都需要下载。</para> + + <para>如果遇到这种情况， 可以将 <makevar>DISTFILES</makevar> + 设置为以空格分隔的一组需要下载的文件列表。</para> + + <programlisting>DISTFILES= source1.tar.gz source2.tar.gz</programlisting> + + <para>如果没有予以明确的设置， <makevar>DISTFILES</makevar> 的默认值将是 + <literal>${DISTNAME}${EXTRACT_SUFX}</literal>。</para> + </sect2> + + <sect2> + <title><makevar>EXTRACT_ONLY</makevar> (只解压缩部分源文件)</title> + + <para>如果只有一部分 <makevar>DISTFILES</makevar> 需要解压缩 + — 例如， 其中的一个是源代码， 而其它则是未压缩的文档 — + 此时应把那些需要解压缩的文件加到 + <makevar>EXTRACT_ONLY</makevar> 中。</para> + + <programlisting>DISTFILES= source.tar.gz manual.html +EXTRACT_ONLY= source.tar.gz</programlisting> + + <para>如果 <makevar>DISTFILES</makevar> 中 <emphasis>没有</emphasis> + 需要解压缩的文件， 则应将 <makevar>EXTRACT_ONLY</makevar> 设为空串。</para> + + <programlisting>EXTRACT_ONLY=</programlisting> + </sect2> + + <sect2 id="porting-patchfiles"> + <title><makevar>PATCHFILES</makevar> (通过下载得到的补丁文件)</title> + + <para>如果您的 port 需要来自 FTP 或 HTTP 的一些额外的补丁， + 应将 <makevar>PATCHFILES</makevar> 设置为这些文件的名字， + 并将 <makevar>PATCH_SITES</makevar> 指向包含这些文件的目录的 URL + (格式与 <makevar>MASTER_SITES</makevar> 相同)。</para> + + <para>如果这些补丁， 由于包含了其它的目录名， + 而导致它们不是相对于源代码目录的顶级目录 + (也就是 <makevar>WRKSRC</makevar>) 的话， + 就需要相应地设置 <makevar>PATCH_DIST_STRIP</makevar> 了。 + 例如， 如果补丁中所有的目录名前面都有一个多余的 + <literal>foozolix-1.0/</literal>， 就应设置 + <literal>PATCH_DIST_STRIP=-p1</literal>。</para> + + <para>不需要担心补丁文件本身是否是压缩的； 如果文件名以 + <filename>.gz</filename> or <filename>.Z</filename> + 结尾， 系统会自动解压缩。</para> + + <para>如果补丁是同某些其它文件， 例如文档， 一同以 gzip 压缩的 tar + 格式发布的， 就不能简单地使用 + <makevar>PATCHFILES</makevar> 了。 这种情况下， + 您应将这些补丁包的文件和位置加入到 + <makevar>DISTFILES</makevar> 和 <makevar>MASTER_SITES</makevar> + 中。 然后， 用 <makevar>EXTRA_PATCHES</makevar> 变量来指出这些文件， + 这样 <filename>bsd.port.mk</filename> 就会自动地为您应用这些补丁了。 + 需要特别注意的是， <emphasis>不要</emphasis> 将补丁文件复制到 + <makevar>PATCHDIR</makevar> 目录中 — 这个目录可能是不可写的。</para> + + <note> + <para>压缩包会以同源代码一样的方式解压缩， 因此不需要自行完成解压缩操作， + 并复制补丁文件。 如果您一定要这样做， 就要注意， + 不要让解压缩出来的文件覆盖先前已经存在的文件。 + 此外， 这么做还需要手工增加命令， + 以便在 <maketarget>pre-clean</maketarget> target + 中删除这些复制出来的文件。</para> + </note> + </sect2> + + <sect2 id="porting-master-sites-n"> + <title>来自不同站点的多个源代码包或补丁文件 + (<literal>MASTER_SITES:n</literal>)</title> + + <para>(这一节在某种程度上应被视作 <quote>进阶话题</quote>； + 刚开始阅读这份文档的读者可能会希望先跳过这一部分)。</para> + + <para>这一节提供了被称作 <literal>MASTER_SITES:n</literal> 和 + <literal>MASTER_SITES_NN</literal> 的下载控制机制。 + 这里我们把它们称为 <literal>MASTER_SITES:n</literal>。</para> + + <para>首先给出一些背景。 OpenBSD 在其 <makevar>DISTFILES</makevar> 和 + <makevar>PATCHFILES</makevar> 变量中提供了一个很棒的功能， + 即， 允许这些文件和补丁拥有 <literal>:n</literal> + 后缀， 其中 <literal>n</literal> 可以使用 + <literal>[0-9]</literal>， 来表达组。 例如：</para> + + <programlisting>DISTFILES= alpha:0 beta:1</programlisting> + + <para>在 OpenBSD 中， 源码包文件 <filename>alpha</filename> + 应被关联到变量 + <makevar>MASTER_SITES0</makevar> 而不是公共的 + <makevar>MASTER_SITES</makevar> 变量上； 而 + <filename>beta</filename> 则应关联到 + <makevar>MASTER_SITES1</makevar> 上。</para> + + <para>这是一个很有意思的功能， + 它可以避免无休止地搜索正确的下载站点的过程。</para> + + <para>想象 <makevar>DISTFILES</makevar> 中指定了 2 个文件， + 而 <makevar>MASTER_SITES</makevar> 包含了 20 个站点的情形， + 这其中许多站点慢如蜗牛， 而 <filename>beta</filename> 可以在 + <makevar>MASTER_SITES</makevar> 的所有站点找到， 而 + <filename>alpha</filename> 只能在第 20 个上面找到。 + 如果监护人了解这一点， 那么检查所有的站点无疑是在浪费时间， + 不是吗？ 这显然不是开始一个愉快周末的好办法！</para> + + <para>现在您有了一个感性的认识了， 想象一下 + <makevar>DISTFILES</makevar> 和更多的 + <makevar>MASTER_SITES</makevar>。 显然， 我们的 + <quote>distfiles 调查员先生</quote> + 会感谢您减少他浪费在等待下载上所耗费的时间。</para> + + <para>下一节中， 将按照 FreeBSD 对上述想法的实现来加以阐释。 + 我们对 OpenBSD 所提出的概念进行了一些改进。</para> + + <sect3> + <title>简化信息</title> + + <para>这一节将介绍如何迅速地对从不同的站点以及子目录下载多个源码包和补丁进行精确的控制。 + 这里， 我们将描述 <literal>MASTER_SITES:n</literal> 的一种简化用法。 + 对于多数情况而言这样做是足够的。 然而， 如果您需要更多信息， + 还需要参考下面的几节。</para> + + <para>一些应用程序需要从多个站点下载不同的源码包。 例如， + <application>Ghostscript</application> 包括了程序核心本身， + 以及大量的驱动文件， 以及则取决于用户的打印机品牌和型号的驱动程序。 + 某些驱动文件已经随程序核心附带， 但也有很多需要从其他站点下载。</para> + + <para>为了适应这种需要， 每一个 + <makevar>DISTFILES</makevar> 项应跟随一个冒号， + 以及一个 <quote>标签名</quote>。 在 + <makevar>MASTER_SITES</makevar> 的每个站点也应跟随冒号和标签名， + 以便指定从哪个网站下载源码包文件。</para> + + <para>例如， 考虑一个将源代码包分为两部分， + 即 <filename>source1.tar.gz</filename> + 和 <filename>source2.tar.gz</filename> 的软件， + 它必须从两个不同的站点下载。 port 的 + <filename>Makefile</filename> 应包括类似 + <xref + linkend="ports-master-sites-n-example-simple-use-one-file-per-site"> + 的配置。</para> + + <example + id="ports-master-sites-n-example-simple-use-one-file-per-site"> + <title>简化的 <literal>MASTER_SITES:n</literal> + 用法， 每个文件来自一个站点</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>多个源码包可以使用同一个标签。 继续前面的例子， + 假定增加了第三个源码包， <filename>source3.tar.gz</filename>， + 应从 <hostid>ftp.example2.com</hostid> 下载。 + <filename>Makefile</filename> 的这部分应写成 + <xref + linkend="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"> + 的样子。</para> + + <example + id="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"> + <title>简化的 <literal>MASTER_SITES:n</literal> 用法， + 其中同一个站点上提供了不止一个文件</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> + + <sect3> + <title>深入介绍</title> + + <para>前面的例子无法满足您的需求？ 这一节， + 我们将详细介绍 <literal>MASTER_SITES:n</literal> + 的精细控制是如何工作的， 以及如何修改您的 port + 来使用它们。</para> + + <orderedlist> + <listitem> + <para>元素可以包含 + <literal>:<replaceable>n</replaceable></literal> 这样的后缀， 其中 + <replaceable>n</replaceable> 是 + <literal>[^:,]+</literal>， 概念上即 + <replaceable>n</replaceable> 可以取任意数字或字母， + 但我们目前将其限定为 + <literal>[a-zA-Z_][0-9a-zA-Z_]+</literal>。</para> + + <para>此外， 字符串匹配时对大小写是敏感的； + 换言之， <literal>n</literal> 与 + <literal>N</literal> 不同。</para> + + <para>但是， 由于表达特殊的意义， 下列单词不能用于后缀： + <literal>default</literal>、 <literal>all</literal> 和 + <literal>ALL</literal> (它们会在 <xref + linkend="porting-master-sites-n-what-changes-in-port-targets"> + 中介绍的部分用到)。 此外， <literal>DEFAULT</literal> + 是一个有特殊用途的词 (请参见 <xref + linkend="porting-master-sites-n-DEFAULT-group">)。</para> + </listitem> + + <listitem> + <para>后缀为 <literal>:n</literal> + 的项目属于 <literal>n</literal> 组， 而 + <literal>:m</literal> 属于 + <literal>m</literal> 组， 依此类推。</para> + </listitem> + + <listitem id="porting-master-sites-n-DEFAULT-group"> + <para>没有后缀的元素是无组的， 也就是它们都属于那个特殊的 + <literal>DEFAULT</literal> 组。 给元素加入 + <literal>DEFAULT</literal> 后缀通常是多余的， + 除非您有同时属于 <literal>DEFAULT</literal> 和其他组的元素 + (参见 <xref + linkend="porting-master-sites-n-comma-operator">)。</para> + + <para>下面的例子是等价的， 但通常应适用第一个：</para> + + <programlisting>MASTER_SITES= alpha + +MASTER_SITES= alpha:DEFAULT</programlisting> + </listitem> + + <listitem> + <para>组之间不是互斥的， 同一元素可以同时隶属于多个组， + 而组则可以为空或者有任意多个元素。 同一组中的重复元素， + 并不会被自动消去。</para> + </listitem> + + <listitem id="porting-master-sites-n-comma-operator"> + <para>如果希望同一元素同时属于多个组， 可以用逗号 + (<literal>,</literal>) 分开。</para> + + <para>这种办法可以避免仅为指定不同的组而多次重复同一元素。 例如 + <literal>:m,n,o</literal> 表示这个元素同时属于 + <literal>m</literal>、 <literal>n</literal> 和 <literal>o</literal> + 这三组。</para> + + <para>下面这些写法都是等价的， 但只推荐使用最后一种：</para> + + <programlisting>MASTER_SITES= alpha alpha:SOME_SITE + +MASTER_SITES= alpha:DEFAULT alpha:SOME_SITE + +MASTER_SITES= alpha:SOME_SITE,DEFAULT + +MASTER_SITES= alpha:DEFAULT,SOME_SITE</programlisting> + </listitem> + + <listitem> + <para>同一组中的所有站点， 会根据 + <makevar>MASTER_SORT_AWK</makevar> 排序。 + 在 <makevar>MASTER_SITES</makevar> 和 + <makevar>PATCH_SITES</makevar> 中的组也会进行排序。</para> + </listitem> + + <listitem id="porting-master-sites-n-group-semantics"> + <para>在 <makevar>MASTER_SITES</makevar>、 + <makevar>PATCH_SITES</makevar>、 + <makevar>MASTER_SITE_SUBDIR</makevar>、 + <makevar>PATCH_SITE_SUBDIR</makevar>、 + <makevar>DISTFILES</makevar>， 以及 + <makevar>PATCHFILES</makevar> 中， 都可以使用组， + 其语法为：</para> + + <orderedlist> + <listitem> + <para>所有 <makevar>MASTER_SITES</makevar>、 + <makevar>PATCH_SITES</makevar>、 + <makevar>MASTER_SITE_SUBDIR</makevar> 以及 + <makevar>PATCH_SITE_SUBDIR</makevar> 的元素， 都必须以 + <literal>/</literal> 字符结尾。 如果有元素属于某些组， + 则组后缀 + <literal>:<replaceable>n</replaceable></literal> + 必须出现在终结符 + <literal>/</literal> 之后。 + <literal>MASTER_SITES:n</literal> 机制依赖于 + <literal>/</literal> 的存在， 以避免在 <literal>:n</literal> + 是元素一部分， 而 <literal>:n</literal> 同时又表示组 + <literal>n</literal> 时发生混淆。 为了兼容性的考虑， + 因为之前 <literal>/</literal> 终结符在 + <makevar>MASTER_SITE_SUBDIR</makevar> 和 + <makevar>PATCH_SITE_SUBDIR</makevar> 元素中都不是必需的， + 如果后缀所紧跟的字符不是 <literal>/</literal>， + 则 <literal>:n</literal> 将被认为是元素的一部分， + 而不被当作组后缀， 即使元素拥有 <literal>:n</literal> + 后缀。 请参见 <xref + linkend="ports-master-sites-n-example-detailed-use-master-site-subdir"> + 和 <xref + linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"> + 以了解进一步的细节。</para> + + <example id="ports-master-sites-n-example-detailed-use-master-site-subdir"> + <title>在 <makevar>MASTER_SITE_SUBDIR</makevar> 中 + <literal>MASTER_SITES:n</literal> 的详细用法</title> + + <programlisting>MASTER_SITE_SUBDIR= old:n new/:NEW</programlisting> + + <itemizedlist> + <listitem> + <para>组 <literal>DEFAULT</literal> 中的目录 + -> old:n</para> + </listitem> + + <listitem> + <para>组 <literal>NEW</literal> 中的目录 + -> new</para> + </listitem> + </itemizedlist> + </example> + + <example + id="ports-master-sites-n-example-detailed-use-complete-example-master-sites"> + <title>用到逗号分隔符、 多个文件， 多个站点和 + 不同子目录的 <literal>MASTER_SITES:n</literal> + 详细用法</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>前述的例子的结果是下述的对于下载行为的精细控制。 + 站点的列表按照使用的顺序给出。</para> + + <itemizedlist> + <listitem> + <para><filename>file1</filename> 将从</para> + + <itemizedlist> + <listitem> + <para><makevar>MASTER_SITE_OVERRIDE</makevar></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><makevar>MASTER_SITE_BACKUP</makevar></para> + </listitem> + </itemizedlist> + + <para>下载。</para> + </listitem> + + <listitem> + <para><filename>file2</filename> 将和 + <filename>file1</filename> 以同样的方式下载， + 因为它们属于同一组</para> + + <itemizedlist> + <listitem> + <para><makevar>MASTER_SITE_OVERRIDE</makevar></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><makevar>MASTER_SITE_BACKUP</makevar></para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para><filename>file3</filename> 将从</para> + + <itemizedlist> + <listitem> + <para><makevar>MASTER_SITE_OVERRIDE</makevar></para> + </listitem> + + <listitem> + <para>http://site3/</para> + </listitem> + + <listitem> + <para><makevar>MASTER_SITE_BACKUP</makevar></para> + </listitem> + </itemizedlist> + + <para>下载。</para> + </listitem> + + <listitem> + <para><filename>file4</filename> 将从</para> + + <itemizedlist> + <listitem> + <para><makevar>MASTER_SITE_OVERRIDE</makevar></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><makevar>MASTER_SITE_BACKUP</makevar></para> + </listitem> + </itemizedlist> + + <para>下载。</para> + </listitem> + + <listitem> + <para><filename>file5</filename> 将从</para> + + <itemizedlist> + <listitem> + <para><makevar>MASTER_SITE_OVERRIDE</makevar></para> + </listitem> + + <listitem> + <para><makevar>MASTER_SITE_BACKUP</makevar></para> + </listitem> + </itemizedlist> + + <para>下载。</para> + </listitem> + + <listitem> + <para><filename>file6</filename> 将从</para> + + <itemizedlist> + <listitem> + <para><makevar>MASTER_SITE_OVERRIDE</makevar></para> + </listitem> + + <listitem> + <para>http://site8/</para> + </listitem> + + <listitem> + <para><makevar>MASTER_SITE_BACKUP</makevar></para> + </listitem> + </itemizedlist> + + <para>下载。</para> + </listitem> + </itemizedlist> + </example> + </listitem> + </orderedlist> + </listitem> + + <listitem> + <para>如何对来自 + <filename>bsd.sites.mk</filename> 的特殊变量， 例如 + <makevar>MASTER_SITE_SOURCEFORGE</makevar> 进行分组？</para> + + <para>参见 <xref + linkend="ports-master-sites-n-example-detailed-use-master-site-sourceforge">。</para> + + <example + id="ports-master-sites-n-example-detailed-use-master-site-sourceforge"> + <title><makevar>MASTER_SITE_SOURCEFORGE</makevar> 中 + <literal>MASTER_SITES:n</literal> 的详细用法</title> + + <programlisting>MASTER_SITES= http://site1/ ${MASTER_SITE_SOURCEFORGE:S/$/:sourceforge,TEST/} +DISTFILES= something.tar.gz:sourceforge</programlisting> + </example> + + <para><filename>something.tar.gz</filename> 将从所有 + <makevar>MASTER_SITE_SOURCEFORGE</makevar> 中的站点下载。</para> + </listitem> + + <listitem> + <para>如何与 <makevar>PATCH*</makevar> 变量连用？</para> + + <para>前面的例子介绍的都是 + <makevar>MASTER*</makevar> 变量， + 但对于 <makevar>PATCH*</makevar> 也是完全一样的， + 它们在 <xref + linkend="ports-master-sites-n-example-detailed-use-patch-sites"> + 有所介绍。</para> + + <example + id="ports-master-sites-n-example-detailed-use-patch-sites"> + <title>简化的 <makevar>PATCH_SITES</makevar> 中的 + <literal>MASTER_SITES:n</literal> 用法。</title> + + <programlisting>PATCH_SITES= http://site1/ http://site2/:test +PATCHFILES= patch1:test</programlisting> + </example> + </listitem> + </orderedlist> + </sect3> + + <sect3> + <title>会改变 ports 的哪些行为？ 哪些不会？</title> + + <orderedlist numeration="lowerroman"> + <listitem> + <para>所有普通的 ports 的行为都会保持不变。 + <literal>MASTER_SITES:n</literal> 功能的代码， + 只有在某些元素包含了前述， 特别是 <xref + linkend="porting-master-sites-n-group-semantics"> + 中所提及语法的 + <literal>:<replaceable>n</replaceable></literal> 后缀时， + 才会启用。</para> + </listitem> + + <listitem id="porting-master-sites-n-what-changes-in-port-targets"> + <para>不受影响的 port target： + <maketarget>checksum</maketarget>、 + <maketarget>makesum</maketarget>、 + <maketarget>patch</maketarget>、 + <maketarget>configure</maketarget>、 + <maketarget>build</maketarget>， 等等。 + 显然， <maketarget>do-fetch</maketarget>、 + <maketarget>fetch-list</maketarget>、 + <maketarget>master-sites</maketarget> 和 + <maketarget>patch-sites</maketarget> 的行为会发生变化。</para> + + <itemizedlist> + <listitem> + <para><maketarget>do-fetch</maketarget>： 会按照新的、 + 带有组后缀的 + <makevar>DISTFILES</makevar> 和 + <makevar>PATCHFILES</makevar> 在 + <makevar>MASTER_SITES</makevar> 和 + <makevar>PATCH_SITES</makevar> 所匹配的组元素， 以及 + <makevar>MASTER_SITE_SUBDIR</makevar> 和 + <makevar>PATCH_SITE_SUBDIR</makevar> 来进行。 + 请参见 <xref + linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites">。</para> + </listitem> + + <listitem> + <para><maketarget>fetch-list</maketarget>： 和旧式的 + <maketarget>fetch-list</maketarget> 类似， 但以同 + <maketarget>do-fetch</maketarget> 相似的方式处理组。</para> + </listitem> + + <listitem> + <para><maketarget>master-sites</maketarget> 和 + <maketarget>patch-sites</maketarget>： + (与旧版本不兼容) 仅返回组 <literal>DEFAULT</literal> + 的元素； 事实上， 它们会执行 + <maketarget>master-sites-default</maketarget> 和 + <maketarget>patch-sites-default</maketarget> + 这两个 target。</para> + + <para>更进一步， 使用 + <maketarget>master-sites-all</maketarget> 或 + <maketarget>patch-sites-all</maketarget> 这两个 + target 之一， 要比直接检查 + <maketarget>MASTER_SITES</maketarget> 或 + <maketarget>PATCH_SITES</maketarget> 更好。 + 此外， 未来版本可能不再保证直接检查能够正确工作。 + 请参见 <xref + linkend="porting-master-sites-n-new-port-targets-master-sites-all"> + 以了解关于这些新 target 的更多技术细节。</para> + </listitem> + + </itemizedlist> + </listitem> + + <listitem> + <para>port 中的新 target</para> + + <orderedlist> + <listitem> + <para>一系列 + <maketarget>master-sites-<replaceable>n</replaceable></maketarget> + 和 + <maketarget>patch-sites-<replaceable>n</replaceable></maketarget> + target 可以分别用来列出 <makevar>MASTER_SITES</makevar> 和 + <makevar>PATCH_SITES</makevar> 中的 <replaceable>n</replaceable> + 组的内容。 例如， + <maketarget>master-sites-DEFAULT</maketarget> 和 + <maketarget>patch-sites-DEFAULT</maketarget> 都会返回 + <literal>DEFAULT</literal> 组的内容， 而 + <maketarget>master-sites-test</maketarget> 和 + <maketarget>patch-sites-test</maketarget> 则返回 + <literal>test</literal> 组的内容， 等等。</para> + </listitem> + + <listitem id="porting-master-sites-n-new-port-targets-master-sites-all"> + <para>新增的 + <maketarget>master-sites-all</maketarget> 和 + <maketarget>patch-sites-all</maketarget> 这两个 target， + 会完成先前 + <maketarget>master-sites</maketarget> 和 + <maketarget>patch-sites</maketarget> 所做的工作。 + 它们会返回所有组的元素， 就像这些元素都属于同一组一样， + 并且会列出与 + <makevar>MASTER_SITE_BACKUP</makevar> 或 + <makevar>MASTER_SITE_OVERRIDE</makevar> 中在 + <makevar>DISTFILES</makevar> 或 + <makevar>PATCHFILES</makevar> 中指定的同样多个； 分别对于 + <maketarget>master-sites-all</maketarget> 和 + <maketarget>patch-sites-all</maketarget>。</para> + </listitem> + </orderedlist> + </listitem> + </orderedlist> + </sect3> + </sect2> + + <sect2> + <title><makevar>DIST_SUBDIR</makevar> (独立的源码包子目录)</title> + + <para>避免让您的 port 使 + <filename>/usr/ports/distfiles</filename> 陷入混乱。 + 如果您的 port 需要下载很多文件， 或者需要下载可能与其它 port + 的源文件名冲突的文件 (例如， + <filename>Makefile</filename>)， 则应将 <makevar>DIST_SUBDIR</makevar> + 设置为 port 的名字 (通常可以用 <literal>${PORTNAME}</literal> 或 + <literal>${PKGNAMEPREFIX}${PORTNAME}</literal>)。 这将把 + <makevar>DISTDIR</makevar> 从默认的 + <filename>/usr/ports/distfiles</filename> 改为 + <filename>/usr/ports/distfiles/<makevar>DIST_SUBDIR</makevar></filename>， + 并将与您的 port 有关的文件放到那个目录中。</para> + + <para>此外， 它也会在备份文件主服务器 <filename>ftp.FreeBSD.org</filename> + 上查找同一子目录下的文件 (直接在您的 + <makevar>Makefile</makevar> 中设置 <makevar>DISTDIR</makevar> + 则不会有这样的效果， 因此您应使用 + <makevar>DIST_SUBDIR</makevar>。)</para> + + <note> + <para>这一设置并不影响您在 <filename>Makefile</filename> + 中定义的 <makevar>MASTER_SITES</makevar>。</para> + </note> + </sect2> + </sect1> + + <sect1 id="makefile-maintainer"> + <title><makevar>MAINTAINER</makevar> (监护人)</title> + + <para>请在此处写上您的电子邮件地址。 <!-- smiley + --><emphasis>:-)</emphasis></para> + + <para>需要注意的是， <makevar>MAINTAINER</makevar> 的值只允许一个电子邮件地址， + 其格式是 <literal>user@hostname.domain</literal>。 + 此处不要写任何说明性的文字， 例如您的真实姓名 — 这会使 + <filename>bsd.port.mk</filename> 感到困惑。 此类文字， + 应放在 <filename>pkg-descr</filename> 中。</para> + + <para>监护人的职责说明， + 可以在 <ulink url="&url.books.developers-handbook;/policies.html#POLICIES-MAINTAINER">Makefiles + 中的 MAINTAINER</ulink> 找到。</para> + + <para>如果某一 port 的监护人没有在两周 (重要的公共假日除外) + 之内响应用户的更新请求， 则视为监护人超时， + 从而允许在没有监护人明确同意的情形下进行更新。 + 如果监护人没有在三个月之内予以响应， 且属于不辞而别的情形， + 则可以变更相应 port 的监护人。 此规定对于监护人为 &a.portmgr; 或 + &a.security-officer; 的 port 不适用。 未经许可， + 不允许 commit 这些小组所监护的 port。</para> + + <para>&a.portmgr; 保留以任何原因收回或绕过监护权的权力， + 而 &a.security-officer; 则保留以安全原因收回或绕过监护权的权力。</para> + </sect1> + + <sect1 id="makefile-comment"> + <title><makevar>COMMENT</makevar> (一句话说明)</title> + + <para>这一变量用于指定 port 的一句话说明。 + <emphasis>请</emphasis> 勿将 package 的名字 (或软件的版本) + 放在说明中。 这一说明的第一个字母应大写， 结尾不用句点。 + 下面是一个例子：</para> + + <programlisting>COMMENT= A cat chasing a mouse all over the screen</programlisting> + + <para><filename>Makefile</filename> 中的 COMMENT 变量应该紧接着 MAINTAINER + 变量出现。</para> + + <para>请务必将 COMMENT 这行限制在 70 个字符之内， + 因为它的主要目的是向用户展示 port 的一句话简介。</para> + </sect1> + + <sect1 id="makefile-depend"> + <title>依赖关系</title> + + <para>许多 port 会依赖其他 port。 + 有七个变量用于帮助您确保所需的文件都存在于用户的机器上。 + 此外， 也提供了用于支持常见情形的依赖关系变量， + 以及对依赖关系行为的更多控制。</para> + + <sect2> + <title><makevar>LIB_DEPENDS</makevar> (依赖的函数库/共享库)</title> + + <para>这个变量用于指定 port 所依赖的共享库。 其内容是由一系列 + <replaceable>lib</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> + 元组构成的表， 其中 <replaceable>lib</replaceable> 是共享库的名字， + 而 <replaceable>dir</replaceable> 则是在找不到时应该从哪里构建和安装， + 最后， <replaceable>target</replaceable> 用于指定在那个目录中调用的 + target。 例如， + <programlisting>LIB_DEPENDS= jpeg.9:${PORTSDIR}/graphics/jpeg:install</programlisting> + 会检测主版本号为 9 的 jpeg 共享库， 如果它不存在， + 则会进入到您的 ports 目录中的 <filename>graphics/jpeg</filename> + 子目录， 并构建和安装它。 如果您指定的 <replaceable>target</replaceable> + 就是 <makevar>DEPENDS_TARGET</makevar> (默认是 + <literal>install</literal>)， 则可以略去不写。</para> + + <note> + <para><replaceable>lib</replaceable> 部分是一个正则表达式， 用于在 + <command>ldconfig -r</command> 的输出中进行查找。 可以使用类似 + <literal>intl.[5-7]</literal> 和 <literal>intl</literal> 这样的值。 + 后者表示任意主版本号的 <literal>intl</literal> 库。</para> + </note> + + <para>依赖关系会被检测两次， 一次是在 + <maketarget>extract</maketarget> target 中， 而另一次则是在 + <maketarget>install</maketarget> target。 另外， + 依赖关系的名字会放到 package 中， 以便让 + &man.pkg.add.1; 能够自动地在用户系统上安装所需的未安装的其他 + package。</para> + </sect2> + + <sect2> + <title><makevar>RUN_DEPENDS</makevar> (依赖的运行环境)</title> + + <para>这个变量可以用来指定 port 在运行时所需要的可执行文件， + 以及资源文件。 它是一系列 + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> + 元组的列表， 这里， <replaceable>path</replaceable> 时所需的可执行， + 或者资源文件的名字， <replaceable>dir</replaceable> 是在无法找到这些文件或目录时， + 去什么地方完成构建和安装以便获得这些文件； 而 + <replaceable>target</replaceable> 则用来指定在这个目录中所调用的 + target 的名字。 假如 <replaceable>path</replaceable> 以斜线 + (<literal>/</literal>) 开始， 则会当作普通文件， + 使用 <command>test -e</command> 来测试； 反之， + 则系统会假定这是一个可执行文件， 并且用 <command>which -s</command> + 来检测程序是否存在于搜索路径中。</para> + + <para>例如，</para> + + <programlisting>RUN_DEPENDS= ${LOCALBASE}/etc/innd:${PORTSDIR}/news/inn \ + wish8.0:${PORTSDIR}/x11-toolkits/tk80</programlisting> + + <para>将检查文件， 或者目录 + <filename>/usr/local/etc/innd</filename> 是否存在， + 如果找不到， 则将从 port 目录的 + <filename>news/inn</filename> 子目录加以安装。 + 系统也会检查是否能够在搜索路径中找到名为 <command>wish8.0</command> + 的文件， 如果找不到的话， 则会进入 ports 目录中的 + <filename>x11-toolkits/tk80</filename> 子目录， + 并进行构建和安装的操作。</para> + + <note> + <para>这种情况下， <command>innd</command> 实际上是一个可执行文件； + 如果可执行文件不会出现在搜索路径中， 您就需要指定完整路径了。</para> + </note> + + <note> + <para>ports 构建集群上官方的搜索 <envar>PATH</envar> 是</para> + + <programlisting>/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin:/usr/X11R6/bin</programlisting> + </note> + + <para>这个依赖关系会在 + <maketarget>install</maketarget> target 的过程中进行检查。 + 此外， 依赖关系的名字会被放到 package 中， 以便 + &man.pkg.add.1; 能够在用户的系统中尚未安装相关软件时自动地安装那些 package。 + 如果您希望指定一个的 <replaceable>target</replaceable> + 和默认的 <makevar>DEPENDS_TARGET</makevar> 相同， + 则可以略去不写。</para> + </sect2> + + <sect2> + <title><makevar>BUILD_DEPENDS</makevar> (依赖的构建环境)</title> + + <para>此变量用于指定用来构建 port 的可执行文件或资源文件。 + 与 <makevar>RUN_DEPENDS</makevar> 类似， 它是一个 + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> + 元组的列表。 例如， <programlisting> BUILD_DEPENDS= + unzip:${PORTSDIR}/archivers/unzip</programlisting> 将检测名为 + <command>unzip</command> 的可执行文件是否存在， 如果不存在， + 则会进入到您的 ports 目录中的 <filename>archivers/unzip</filename> + 并完成构建和安装工作。</para> + + <note> + <para>这里的 <quote>build</quote> 表示从解压缩到编译的全部过程。 + 依赖关系是在 <maketarget>extract</maketarget> target 的过程中检测的。 + 假如您要指定的 <replaceable>target</replaceable> 和 + <makevar>DEPENDS_TARGET</makevar> 相同， 则可以略去不写。</para> + </note> + </sect2> + + <sect2> + <title><makevar>FETCH_DEPENDS</makevar> (依赖的下载环境)</title> + + <para>这一变量用于指定 port 在下载时所需的可执行文件或资源文件。 + 和前两个类似， 它是一组 + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> + 元组。 例如， <programlisting> FETCH_DEPENDS= + ncftp2:${PORTSDIR}/net/ncftp2</programlisting> + 将检测名为 <command>ncftp2</command> 的可执行文件是否存在， + 如果找不到， 则将进入到您 ports 目录中的 + <filename>net/ncftp2</filename> 子目录并加以构建和安装。</para> + + <para>这个依赖关系是在 + <maketarget>fetch</maketarget> target 过程中检查的。 + 如果与 <makevar>DEPENDS_TARGET</makevar> 相同， + 则可以省略 <replaceable>target</replaceable> 部分。</para> + </sect2> + + <sect2> + <title><makevar>EXTRACT_DEPENDS</makevar> (依赖的解压缩环境)</title> + + <para>此变量用于指定 port 在解压缩时所需的可执行文件或其他资源文件。 + 和前一个变量类似， 它是一系列 + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> + 元组的列表。 例如， <programlisting>EXTRACT_DEPENDS= + unzip:${PORTSDIR}/archivers/unzip</programlisting> 将检查名为 + <command>unzip</command> 的可执行文件是否存在， 如果不存在， + 则会进入到您的 ports 目录中的 <filename>archivers/unzip</filename> + 子目录， 予以构建和安装。</para> + + <para>这个依赖关系是在 + <maketarget>extract</maketarget> target 的过程中检查的。 如果与 + <makevar>DEPENDS_TARGET</makevar> 相同， + 则可以略去 <replaceable>target</replaceable> 部分。</para> + + <note> + <para>只有在其他方式都不可用 (默认是 <command>gzip</command>) + 而且无法通过 <xref + linkend="use-vars"> 所介绍的 <makevar>USE_ZIP</makevar> 或 + <makevar>USE_BZIP2</makevar> 都不能达到需要时， + 才应使用这个变量。</para> + </note> + </sect2> + + <sect2> + <title><makevar>PATCH_DEPENDS</makevar> (依赖的打补丁环境)</title> + + <para>这个变量用于指定 port 在进行 patch + 操作时所需的可执行文件或其他资源文件。 和前一个变量类似， 它是一组 + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> + 元组的表。 例如， <programlisting> PATCH_DEPENDS= + ${NONEXISTENT}:${PORTSDIR}/java/jfc:extract + </programlisting> 表示进入到您的 ports 目录中的 + <filename>java/jfc</filename> 子目录， 并将其解压缩， + 而无论它是否之前安装过。</para> + + <para>这个依赖关系是在 + <maketarget>patch</maketarget> target 的过程中检查的。 + <replaceable>target</replaceable> 部分如果和 + <makevar>DEPENDS_TARGET</makevar> 相同， 就可略去不写。</para> + </sect2> + + <sect2> + <title><makevar>DEPENDS</makevar> (一般依赖)</title> + + <para>如果有无法归类于上述类别的依赖关系， 或者您的 port + 需要解压缩其他 port 的源代码才能够完成构建或安装， + 则应使用它来表达。 这个变量是一组格式为 + <replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> + 的元组表， 与前四个不同， 它并不实施检查。 这里的 + <replaceable>target</replaceable> 部分， + 如果与 <makevar>DEPENDS_TARGET</makevar> 相同， 就可以略去不写。</para> + </sect2> + + <sect2 id="use-vars"> + <title><makevar>USE_<replaceable>*</replaceable></makevar></title> + + <para>提供了一系列变量， 用以封装大量 port 都用到的依赖关系。 + 虽然使用这些变量是可选的， 但它们能显著减少 port 的 + <filename>Makefile</filename> 复杂性。 这些变量的共同特征在于， + 它们的名字都是 <makevar>USE_<replaceable>*</replaceable></makevar> + 这样的形式。 这些变量的使用， 应严格限制于 port 的 + <filename>Makefile</filename> 以及 + <filename>ports/Mk/bsd.*.mk</filename>， + 而绝不应用于表达用户能够设置的选项 — 这种情况下应采用 + <makevar>WITH_<replaceable>*</replaceable></makevar> 和 + <makevar>WITHOUT_<replaceable>*</replaceable></makevar> + 这样的变量。</para> + + <note> + <para><emphasis>任何</emphasis> 情况下， 都不应在 + <filename>/etc/make.conf</filename> 中配置 + <makevar>USE_<replaceable>*</replaceable></makevar>。 + 例如， 设置 <programlisting>USE_GCC=3.2</programlisting> + 将导致每一个 port 都依赖于 gcc32， 甚至包括 + gcc32 本身！</para> + </note> + + <table frame="none"> + <title>常用的 <makevar>USE_<replaceable>*</replaceable></makevar> + 变量</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>变量</entry> + + <entry>含义</entry> + </row> + </thead> + + <tbody> + <row> + <entry><makevar>USE_BZIP2</makevar></entry> + + <entry>此 port 的源码包是使用 + <command>bzip2</command> 压缩的。</entry> + </row> + + <row> + <entry><makevar>USE_ZIP</makevar></entry> + + <entry>此 port 的源码包是用 + <command>zip</command> 压缩的。</entry> + </row> + + <row> + <entry><makevar>USE_GMAKE</makevar></entry> + + <entry>此 port 需要使用<command>gmake</command> 来进行构建。</entry> + + </row> + + <row> + <entry><makevar>USE_PERL5</makevar></entry> + + <entry>此 port 的构建和安装需要使用 <literal>perl 5</literal>。 参见 + <xref linkend="using-perl"> 以了解与 <literal>perl</literal> + 有关的其他变量。</entry> + </row> + + <row> + <entry><makevar>USE_X_PREFIX</makevar></entry> + + <entry>此 port 将安装到 <makevar>X11BASE</makevar> + 而非默认的 <makevar>PREFIX</makevar>。 请参见 + <xref linkend="using-x11"> 以了解其他与 X11 有关的变量。</entry> + </row> + + <row> + <entry><makevar>USE_AUTOMAKE_VER</makevar></entry> + + <entry>此 port 的构建过程中用到了 GNU <command>automake</command>。 + 请参见 <xref linkend="using-automake"> 以了解与 + <command>automake</command> 有关的其他变量。</entry> + </row> + + <row> + <entry><makevar>USE_AUTOCONF_VER</makevar></entry> + + <entry>此 port 的构建过程中用到了 GNU <command>autoconf</command>。 + 请参见 <xref linkend="using-automake"> 以了解与 + <command>autoconf</command> 有关的其他变量。</entry> + </row> + + <row> + <entry><makevar>USE_LIBTOOL_VER</makevar></entry> + + <entry>此 port 构建过程用到了 GNU <command>libtool</command>。 + 请参见 <xref linkend="using-automake"> 以了解与 + <command>libtool</command> 有关的其他变量。</entry> + </row> + + <row> + <entry><makevar>GMAKE</makevar></entry> + + <entry><command>gmake</command> 的完整路径， 如果它不在 + <envar>PATH</envar> 中的话。</entry> + </row> + + <row> + <entry><makevar>USE_BISON</makevar></entry> + + <entry>此 port 在构建时使用 <command>bison</command>。</entry> + </row> + + <row> + <entry><makevar>USE_SDL</makevar></entry> + + <entry>此 port 使用 <literal>SDL</literal> 来完成构建和支持运行。 + 参见 <xref linkend="using-sdl"> 以了解如何使用 + <makevar>USE_SDL</makevar>。</entry> + </row> + + <row> + <entry><makevar>USE_GCC</makevar></entry> + + <entry>此 port 需要使用某一特定版本的 + <command>gcc</command> 才能完成编译。 + 可以使用类似 <literal>3.2</literal> 这样的值来精确指定版本。 + 如果希望使用不低于某一版本的编译器， 则可以用 + <literal>3.2+</literal> 这样的形式。 如果与所希望的版本吻合， + 则将使用基本系统中所提供的 <command>gcc</command>， 反之， + 系统会从 ports 中安装所希望版本的 <command>gcc</command>， + 并调整 <makevar>CC</makevar> 以及 + <makevar>CXX</makevar> 变量的设置。 需要注意的是， + <makevar>USE_GCC</makevar> 不能与 + <makevar>USE_LIBTOOL_VER</makevar> 联用。</entry> + </row> + + <row> + <entry><makevar>NO_INSTALL_MANPAGES</makevar></entry> + + <entry>不要使用 <maketarget>install.man</maketarget> + target。</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>如果您的 port 需要使用 X Window 系统， + 则应定义 <literal>USE_XLIB=yes</literal>。 (如果定义了 + <makevar>USE_IMAKE</makevar> 则会作隐含定义)。 如果您的 port + 使用了 GNU <command>make</command> 而不是 BSD + <command>make</command>， 还应定义 + <literal>USE_GMAKE=yes</literal>。 如果需要运行 GNU autoconf， + 还需要定义 <literal>USE_AUTOCONF_VER=213</literal>。 + 定义 <literal>USE_QT_VER=3</literal> 表示您的 port 需要使用最新的 + Qt toolkit。 此外， 还可以用 + <literal>USE_PERL5=yes</literal> 来表示 port 需要 + <literal>perl</literal> 语言的第 5 版。 (最后一个变量很重要， + 因为某些版本的 FreeBSD 的基本系统中包含了 <literal>perl5</literal>， + 而新版本则没有。)</para> + </sect2> + + <sect2> + <title>关于依赖关系的补充说明</title> + + <para>如前面所提到的那样， 在需要某一依赖的 port 时， + 将调用 <maketarget>DEPENDS_TARGET</maketarget> 所指定的 target。 + 这一变量的默认值是 <literal>install</literal>。 这不是一个用户变量， + 它不应在 port 的 + <filename>Makefile</filename> 中予以定义。 如果您的 port 需要使用特殊的 + target 来处理依赖关系， 应使用 <makevar>*_DEPENDS</makevar> 的 + <literal>:target</literal> 部分， 而不是重定义 + <makevar>DEPENDS_TARGET</makevar> 来完成。</para> + + <para>当您输入 <command>make clean</command> 时， 其依赖的 port + 也会自动进行清理。 如果您不希望如此， 应定义环境变量 + <makevar>NOCLEANDEPENDS</makevar>。 如果 port + 依赖一些重新构建需要花费很长时间的 port 时， 例如 KDE， GNOME + 或 Mozilla 时， 这一方法会非常有用。</para> + + <para>要无条件地依赖某个 port， 可以使用 <makevar>${NONEXISTENT}</makevar> + 作为 <makevar>BUILD_DEPENDS</makevar> 或 + <makevar>RUN_DEPENDS</makevar> 的第一部分。 只有在您需要使用其他 + port 提供的源代码时才应这样做。 通常也可以通过这样指定来缩短编译所需的时间。 + 例如 + + <programlisting>BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract</programlisting> + + 表示依赖 <literal>jpeg</literal> port 并将其解压缩。</para> + + <para>除非其他方式都不适合， 否则不要使用 <makevar>DEPENDS</makevar>。 + 这样指定将在任何情况下都构建 (默认情况下还会安装) 其他 port， + 而且这依赖关系还会进入 package。 如果真的需要这样， 写成 + <literal>BUILD_DEPENDS</literal> 和 + <literal>RUN_DEPENDS</literal> 可能更合适一些 — + 至少它的表达更为明确。</para> + </sect2> + + <sect2> + <title>循环的依赖关系是致命的</title> + + <important> + <para>不要在 ports tree 中引入任何循环依赖关系!</para> + </important> + + <para>ports 构建技术不能够容忍循环依赖关系。 如果您引入了这样的关系， + 就一定会有人安装的 FreeBSD 会因此而损坏， 而且这种现象会越来越多。 + 这些情形很难检测； 如果有疑虑， 在进行这样的修改之前， 务必执行： + <command>cd /usr/ports; make index</command>。 这个过程在旧的机器上会很慢， + 但能够让大量的用户 — 也包括您自己 — + 拯救于由这种问题所造成的困惑之中。</para> + </sect2> + + </sect1> + + <sect1 id="makefile-options"> + <title>Makefile 选项</title> + + <para>某些大型应用程序可以在构建时使用一系列配置选项， + 用以在系统中已经安装了某些库或应用程序时增加一些功能。 + 例如， 选择某种自然 (人类的) 语言， GUI 或命令行界面， + 由于并不是所有的用户都希望使用这些库或者应用程序， port + 系统提供了一组方便的机制， 来让 port 的作者控制构建时的配置。 + 支持这些特性可以让用户体验更好， 并达到事半功倍的效果。</para> + + <sect2> + <title><makevar>WITH_<replaceable>*</replaceable></makevar> 和 + <makevar>WITHOUT_<replaceable>*</replaceable></makevar></title> + + <para>这些变量是为系统管理员准备的。 许多这样的变量被标准化并置于 + <filename>ports/Mk/bsd.*.mk</filename>； 也有一些没有， + 这可能会比较令人困惑。 如果您需要增加类似的配置变量， + 请考虑使用下表中的变量。</para> + + <note> + <para>您不应假定每一个 + <makevar>WITH_<replaceable>*</replaceable></makevar> + 都会有对应的 + <makevar>WITHOUT_<replaceable>*</replaceable></makevar> + 变量， 反之亦然。 一般而言， 会使用默认值。</para> + </note> + + <note> + <para>除非另有说明， 这些变量都是测试是否定义， + 而不是它们设置了 <literal>YES</literal> 或 + <literal>NO</literal>。</para> + </note> + + <table frame="none"> + <title><makevar>WITH_<replaceable>*</replaceable></makevar> + 和 <makevar>WITHOUT_<replaceable>*</replaceable></makevar> + 变量</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>变量</entry> + + <entry>意义</entry> + </row> + </thead> + + <tbody> + <row> + <entry><makevar>WITH_APACHE2</makevar></entry> + + <entry>如果定义了这个变量， 则使用 + <filename role="package">www/apache2</filename> + 而不是默认的 + <filename role="package">www/apache</filename>。</entry> + </row> + + <row> + <entry><makevar>WITH_BERKELEY_DB</makevar></entry> + + <entry>这个变量表示所用的 Berkeley 数据库软件包版本， 例如 + <filename role="package">databases/db41</filename>。 + <makevar>WITH_BDB_VER</makevar> 可以取的值包括 + 2、 3、 4、 41 和 42。</entry> + </row> + + <row> + <entry><makevar>WITH_MYSQL</makevar></entry> + + <entry>这个变量用于指定所用的 MySQL 数据库软件包的版本， 例如 + <filename role="package">databases/mysql40-server</filename>。 + <makevar>WANT_MYSQL_VER</makevar> 可以取的值， + 包括 323、 40、 41 和 50。</entry> + </row> + + <row> + <entry><makevar>WITHOUT_NLS</makevar></entry> + + <entry>表示不需要国际化支持， 这可以节省编译所消耗的时间。 + 默认情况下， 会启用国际化支持。</entry> + </row> + + <row> + <entry><makevar>WITH_OPENSSL_BASE</makevar></entry> + + <entry>使用基本系统中的 OpenSSL 版本。</entry> + </row> + + <row> + <entry><makevar>WITH_OPENSSL_PORT</makevar></entry> + + <entry>使用从 <filename role="package">security/openssh</filename> + 中安装的 OpenSSL 版本， 并覆盖原先随基本系统安装的 + OpenSSL 版本。</entry> + </row> + + <row> + <entry><makevar>WITH_POSTGRESQL</makevar></entry> + + <entry>这个变量用于指定所需的 PostGreSQL 数据库软件包的版本， 例如 + <filename role="package">databases/postgresql72</filename>。 + </entry> + </row> + + <row> + <entry><makevar>WITHOUT_X11</makevar></entry> + + <entry>如果 port 能够在是否包含 + X 支持的情况下分别构建， 则一般情况应该默认以包含 + X 支持的配置来构建。 如果定义了这一变量， + 则应构建不包含 X 支持的版本。</entry> + </row> + </tbody> + </tgroup> + </table> + + </sect2> + + <sect2> + <title><makevar>OPTIONS</makevar> (菜单式可选项)</title> + + <sect3> + <title>背景</title> + <para><makevar>OPTIONS</makevar> 变量将向安装 port + 的用户给出一个对话框， 其中给出可用的选项， 这些选项将保存到 + <filename>/var/db/ports/portname/options</filename> 中。 + 下次重新构建 port 时， 这些选项将被重用。 这样， + 就不再需要记忆您上次构建 port 时所用的那样多的 + <makevar>WITH_<replaceable>*</replaceable></makevar> 和 + <makevar>WITHOUT_<replaceable>*</replaceable></makevar> 了！</para> + </sect3> + + <sect3> + <title>语法</title> + <para><makevar>OPTIONS</makevar> 变量的语法是： + +<programlisting>OPTIONS= OPTION "说明性文字" 默认值 ... +</programlisting> + + 默认值必须是 <literal>ON</literal> 和 + <literal>OFF</literal> 之一。 这种三元组可以使用多次。</para> + + <para>当用户执行 <command>make config</command> (或首次执行 + <command>make build</command>) 时， + 系统将检查 <filename>/var/db/ports/<replaceable>portname</replaceable> + /options</filename>。 如果这个文件不存在， 它将使用 + <makevar>OPTIONS</makevar> 中的值来显示一个对话框， + 以便启用或禁用某些选项。 随后， 用户所选的项目将被保存起来， + 而对应的变量则将用于构建过程。</para> + + <para>用 <command>make showconfig</command> 来查看保存的配置。 + 用 <command>make rmconfig</command> 删除已经保存的配置。</para> + + <sect3> + <title>例子</title> + <example id="ports-options-simple-use"> + <title>简单的 <makevar>OPTIONS</makevar> 用法</title> + <para><programlisting>OPTIONS= FOO "启用 foo 选项" On \ + BAR "支持 bar 选项" Off + +.include <bsd.port.pre.mk> + +.if defined(WITHOUT_FOO) +CONFIGURE_ARGS+= --without-foo +.else +CONFIGURE_ARGS+= --with-foo +.endif + +.if defined(WITH_BAR) +RUN_DEPENDS+= bar:${PORTSDIR}/bar/bar +.endif + +.include <bsd.port.post.mk></programlisting></para> + </example> + + <sect3> + <title>已知问题</title> + <itemizedlist> + <listitem> + <para><command>make index</command> 目前还不能按照 + <makevar>OPTIONS</makevar> 的设置来完成生成过程 (ports/75727)</para> + </listitem> + <listitem> + <para><makevar>PACKAGE_BUILDING</makevar> 目前无法正确配合 + <makevar>OPTIONS</makevar> (ports/75727?)</para> + </listitem> + </itemizedlist> + </sect3> + + </sect2> + + </sect1> + + <sect1 id="makefile-wrkdir"> + <title>指定工作临时目录</title> + + <para>每个 port 都会被解压缩到一个工作临时目录中， 这个目录必须是可写的。 + ports 系统默认情况下会将 + <makevar>DISTFILES</makevar> 解压缩到一个叫做 + <literal>${DISTNAME}</literal> 的目录中。 换言之， 如果设了：</para> + + <programlisting>PORTNAME= foo +PORTVERSION= 1.0</programlisting> + + <para>则 port 的源码包文件的顶级目录将是 + <filename>foo-1.0</filename>。</para> + + <para>如果这不是所希望的情形， 您可以修改一系列变量的设置。</para> + + <sect2> + <title><makevar>WRKSRC</makevar> (开始构建操作的目录名)</title> + + <para>这个变量给出了在应用程序的源代码包解压缩之后所生成的目录的名字。 + 如果我们之前的例子解压缩生成一个叫做 <filename>foo</filename> (而不是 + <filename>foo-1.0</filename>) 的目录， 您应：</para> + + <programlisting>WRKSRC= ${WRKDIR}/foo</programlisting> + + <para>或者， 也可能是</para> + + <programlisting>WRKSRC= ${WRKDIR}/${PORTNAME}</programlisting> + </sect2> + + <sect2> + <title><makevar>NO_WRKSUBDIR</makevar> (不需要临时的构建目录)</title> + + <para>如果 port 完全不需要写入到某个子目录中， + 您应设置 <makevar>NO_WRKSUBDIR</makevar> 以明示这一点。</para> + + <programlisting>NO_WRKSUBDIR= yes</programlisting> + </sect2> + </sect1> + + <sect1 id="conflicts"> + <title><makevar>CONFLICTS</makevar> (设置与其它包的冲突)</title> + + <para>如果您的软件包无法与某些其它软件包共存 + (由于文件冲突， 运行环境不兼容， 等等)， + 将这些包的名字列在 <makevar>CONFLICTS</makevar> + 变量中。 此处可以使用 shell 通配符， 如 <literal>*</literal> 和 + <literal>?</literal>。 列举软件包的名称时， 应采用 + <filename>/var/db/pkg</filename> 中的形式。 请确认 + <makevar>CONFLICTS</makevar> 不会匹配它本身， 否则将导致 + <makevar>FORCE_PKG_REGISTER</makevar> 无法正常工作。 + </para> + + <note> + <para><makevar>CONFLICTS</makevar> 会自动地设置 + <makevar>IGNORE</makevar>， 后者的完整介绍， + 可以在 <xref linkend="dads-noinstall"> 找到。</para> + </note> + </sect1> + + <sect1 id="makefile-build"> + <title>构建机制</title> + + <para>如果您的软件用到了 GNU <command>make</command>， 则应设置 + <literal>USE_GMAKE=yes</literal>。 如果包含 + <command>configure</command>， 还应设置 + <literal>HAS_CONFIGURE=yes</literal>。 假如要使用 GNU + <command>configure</command>， 则需要设置 + <literal>GNU_CONFIGURE=yes</literal> (这会自动设置 + <literal>HAS_CONFIGURE</literal>)。 如果希望向 + <command>configure</command> 传递一些参数 (对于 GNU + <command>configure</command> 而言， 其默认值是 + <literal>--prefix=${PREFIX}</literal>， 而对非 GNU + <command>configure</command> 则是空串)， 将这些额外的参数设置为 + <makevar>CONFIGURE_ARGS</makevar>。 如果您的软件包使用 GNU + <command>autoconf</command>， 可以设置 + <literal>USE_AUTOCONF_VER=213</literal>。 这会自动设置 + <makevar>GNU_CONFIGURE</makevar>， 并让 + <command>autoconf</command> 在 + <command>configure</command> 之前执行。</para> + + <note> + <para>如果软件包用到 GNU <command>configure</command>， + 而最终生成的可执行文件的名字很 <quote>奇怪</quote>， 例如 + <filename>i386-portbld-freebsd4.7-</filename><replaceable>appname</replaceable>， + 您需要额外地手工修改 + <makevar>CONFIGURE_TARGET</makevar> 变量， + 按照较新版的 <command>autoconf</command> + 希望的方式指定目标的名字。 做法是在 <filename>Makefile</filename> + 中的 <literal>GNU_CONFIGURE=yes</literal> 这行之后加入：</para> + + <para> + <literal>CONFIGURE_TARGET=--build=${MACHINE_ARCH}-portbld-freebsd${OSREL}</literal> + </para> + </note> + + <para>如果您的软件包是 X 应用程序， 并且使用 <command>imake</command> + 从 <filename>Imakefile</filename> 中生成的 <filename>Makefile</filename>， + 就应设置 + <literal>USE_IMAKE=yes</literal>。 这样， 就能够在 configure + 阶段自动地执行 <command>xmkmf -a</command>。 如果您的 port 使用 + <option>-a</option> 参数会导致问题， 需要进一步设置 + <literal>XMKMF=xmkmf</literal>。 如果 port 使用 + <command>imake</command> 但无法采用 + <maketarget>install.man</maketarget> target， 则应设置 + <literal>NO_INSTALL_MANPAGES=yes</literal>。 最后， + 这些问题应通知您所 port 软件的原作者。 <!-- + smiley --><emphasis>:-></emphasis></para> + + <para>如果您的 port 的源 <filename>Makefile</filename> + 用于构建的 target 名字不是 <maketarget>all</maketarget>， + 需要相应地设置 <makevar>ALL_TARGET</makevar>； 同理， + 对于 <maketarget>install</maketarget> 可以配置 + <makevar>INSTALL_TARGET</makevar>。</para> + </sect1> + </chapter> + + <chapter id="special"> + <title>特殊情况</title> + + <para>有一些您在创建port时的特殊情况，我们在这里提一下。</para> + + <sect1 id="porting-shlibs"> + <title>共享库</title> + + <para>如果您的port安装了一个或多个共享库,那么请定义一个 + <makevar>INSTALLS_SHLIB</makevar> make 变量， + 在<maketarget>post-install</maketarget>标记把它注册进共享库 + 缓冲时会调用<filename>bsd.port.mk</filename>去运行 + <literal>${LDCONFIG} -m</literal>来指向新库的安装目录。 + (通常是 <filename><makevar>PREFIX</makevar>/lib</filename>) + 同样，您也可以适当的在您的 + <filename>pke-plist</filename>文件 + 中定义一组<literal>@exec /sbin/ldconfig -m</literal> + 和<literal>@unexec /sbin/ldconfig -R，</literal> + 那么用户可以在安装后马上 + 就能使用，并且在卸载软件包后系统也不会认为这些共享库仍然存在。</para> + + <para>如果您需要把共享库安装在缺省的位置之外， + 可以定义 <makevar>LDCONFIG_DIRS</makevar> + make 变量，它包含安装共享库的目录列表 + 例如： + 如果您的共享库安装到 + <filename><makevar>PREFIX</makevar>/lib/foo</filename> 和 + <filename><makevar>PREFIX</makevar>/lib/bar</filename> + directories目录，您可以在您的 + <filename>Makefile</filename>中这样设置:</para> + + <programlisting>INSTALLS_SHLIB= yes +LDCONFIG_DIRS= %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting> + + <para>值得注意的是这里 <makevar>LDCONFIG_DIRS</makevar> 的内 + 容就像 <filename>pkg-plist</filename> + 的其他部分一样要通过&man.sed.1;过滤，所 + 以 <makevar>PLIST_SUB</makevar> + 置换也会应用。我们推荐您使用 <literal>%%PREFIX%%</literal> 替换 + <makevar>PREFIX</makevar>，<literal>%%LOCALBASE%%</literal> + 替换<makevar>LOCALBASE</makevar>，<literal>%%X11BASE%%</literal> + 替换<makevar>X11BASE</makevar>.</para> + </sect1> + + <sect1 id="porting-restrictions"> + <title>Ports的发行限制</title> + + <para>众多协议，并且其中的一些致力于 + 限制怎样的应用程序能被打包， + 是否能用于销售赢利等等。</para> + + <important> + <para> + 做为一名porter您有义务去阅读软件的协议 + 并且确保FreeBSD 项目不必为通过FTP/HTTP + 或CD-ROM重新发布源码或编译的二进制而解释 + 什么。如果有任何疑问， + 请联系 &a.ports;。</para> + </important> + + <para>处于这种情况，就可以设置以下描述 + 的变量。</para> + + <sect2> + <title><makevar>NO_PACKAGE</makevar> (禁止编译结果打包)</title> + + <para>这个变量表示我们可能不能生成这个应用 + 程序的二进制文件。例如，他的协议不允许 + 二进制文件的再次发行，或者他可能禁止从 + 补丁过的源代码打包的发行。</para> + + <para>不管怎么样，port的 <makevar>DISTFILES</makevar> 可以 + 随意的镜像到FTP/HTTP。除非<makevar>NO_CDROM</makevar> + 变量也被设置，软件包也可以发行在一张CD-ROM + （或类似的媒介上）。</para> + + <para><makevar>NO_PACKAGE</makevar>也能用在当二进制包 + 不是非常有用，并且这个应用软件经常要 + 从源代码编译。例如：当这个应用软件在 + 编译的时候要在配置信息中指定特定的硬件 + 代码时，可以设置<makevar>NO_PACKAGE</makevar>。</para> + + <para><makevar>NO_PACKAGE</makevar>应该设置成字符串 + 来描述为什么这个软件 + 不能打包。</para> + </sect2> + + <sect2> + <title><makevar>NO_CDROM</makevar> (禁止以 CDROM 发行预编译包)</title> + + <para>这个变量仅仅指出虽然我们允许 + 生成二进制包，但也许我们既不能把这个 + 软件包也不能把port的<makevar>DISTFILES</makevar> + 放在光盘（或类似的媒介）上销售。但不管怎么样， + 二进制包和port的<makevar>DISTFILES</makevar> + 可以从FTP/HTTP上获得。</para> + + + <para>如果这个变量和 + <makevar>NO_PACKAGE</makevar>一起被设置， + 那么这个port的<makevar>DISTFIELS</makevar> + 将只能从FTP/HTTP上获得。</para> + + <para><makevar>NO_CDROM</makevar> 应该被设置成一个字符串 + 来描述为什么这个port不能重新发布在CD-ROM上。 + 例如：如果这个port的协议仅仅是用于<quote>非商业活动</quote> + ,那么这个变量就能设置了。</para> + </sect2> + + <sect2> + <title><makevar>RESTRICTED</makevar> (禁止任何形式的再分发)</title> + + <para>如果应用程序既不允许镜像其 <makevar>DISTFILES</makevar>， + 也不允许发布其预编译版本的包， 设置它就可以了。</para> + + <para><makevar>NO_CDROM</makevar> 或 <makevar>NO_PACKAGE</makevar> + 不应与 <makevar>RESTRICTED</makevar> 同时设置， + 因为它包含了这些情形。</para> + + <para><makevar>RESTRICTED</makevar> 应设置为一个说明 port 为何不能发布的串。 + 典型情况可能是由于 port 包含了专有的软件， 因而用户需要自行下载 + <makevar>DISTFILES</makevar>， 可能是注册或者同意某一 + <acronym>EULA</acronym> 的条款。</para> + </sect2> + + <sect2> + <title><makevar>RESTRICTED_FILES</makevar> (禁止某些文件的再分发)</title> + + <para>当设置了 <makevar>RESTRICTED</makevar> 或 <makevar>NO_CDROM</makevar> + 时， 这个变量会默认设置为 <literal>${DISTFILES} + ${PATCHFILES}</literal>， 否则它会为空。 如果只有某些源码包文件是受限的， + 则可以用这个变量来指明它们。</para> + + <para>注意， port committer 应该在 + <filename>/usr/ports/LEGAL</filename> 中为每一个源码包文件撰写对应的项目， + 并介绍这些限制的原因。</para> + </sect2> + </sect1> + + <sect1 id="using-perl"> + <title>使用 <literal>perl</literal></title> + + <table frame="none"> + <title>使用 <literal>perl</literal> 的 ports 可以使用的变量</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>变量</entry> + + <entry>意义</entry> + </row> + </thead> + + <tbody> + <row> + <entry><makevar>USE_PERL5</makevar></entry> + + <entry>表示 port 将 <literal>perl 5</literal> 用于构建和运行。</entry> + </row> + + <row> + <entry><makevar>USE_PERL5_BUILD</makevar></entry> + + <entry>表示 port 将 <literal>perl 5</literal> 用于构建。</entry> + </row> + + <row> + <entry><makevar>USE_PERL5_RUN</makevar></entry> + + <entry>表示 port 将 <literal>perl 5</literal> 用于运行。</entry> + </row> + + <row> + <entry><makevar>PERL</makevar></entry> + + <entry><literal>perl 5</literal> 的完整路径， 可能是系统自带的， + 或者从 port 安装， 但没有版本号。 如果您需要在脚本中替换 + <quote><literal>#!</literal></quote> 行， 则应使用这个变量。</entry> + </row> + + <row> + <entry><makevar>PERL_CONFIGURE</makevar></entry> + + <entry>采用 Perl 的 MakeMaker 进行配置。 这一变量隐含设置 + <makevar>USE_PERL5</makevar>。</entry> + </row> + + <row> + <entry><makevar>PERL_MODBUILD</makevar></entry> + + <entry>使用 Module::Build 进行配置、 构建并安装。 + 这一变量隐含设置 <makevar>PERL_CONFIGURE</makevar>。</entry> + </row> + </tbody> + </tgroup> + + <tgroup cols="2"> + <thead> + <row> + <entry>只读变量</entry> + </row> + </thead> + + <tbody> + <row> + <entry><makevar>PERL_VERSION</makevar></entry> + + <entry>系统中安装的 <literal>perl</literal> 的完整版本 (例如， + <literal>5.00503</literal>)。</entry> + </row> + + <row> + <entry><makevar>PERL_VER</makevar></entry> + + <entry>系统中安装的 <literal>perl</literal> 的短版本 (例如， + <literal>5.005</literal>)。</entry> + </row> + + <row> + <entry><makevar>PERL_LEVEL</makevar></entry> + + <entry>系统中安装的 <literal>perl</literal> 的版本整数值， + 其形式为 <literal>MNNNPP</literal> + (例如， <literal>500503</literal>)。</entry> + </row> + + <row> + <entry><makevar>PERL_ARCH</makevar></entry> + + <entry><literal>perl</literal> 保存某平台专用的库的位置。 + 默认值为 <literal>${ARCH}-freebsd</literal>。</entry> + </row> + + <row> + <entry><makevar>PERL_PORT</makevar></entry> + + <entry>系统中所安装的 <literal>perl</literal> port 的名字 + (例如， <literal>perl5</literal>)。</entry> + </row> + + <row> + <entry><makevar>SITE_PERL</makevar></entry> + + <entry>站点专用的 + <literal>perl</literal> package 安装路径。 + 其值会自动加入到 PLIST_SUB 中。</entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + + <sect1 id="using-x11"> + <title>使用 X11</title> + + <table frame="none"> + <title>用到 X 的 port 可以使用的变量</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><makevar>USE_X_PREFIX</makevar></entry> + + <entry>此 port 将文件安装到 <makevar>X11BASE</makevar> 而非通常的 + <makevar>PREFIX</makevar>。</entry> + </row> + + <row> + <entry><makevar>USE_XLIB</makevar></entry> + + <entry>此 port 用到了 X 库。</entry> + </row> + + <row> + <entry><makevar>USE_MOTIF</makevar></entry> + + <entry>此 port 使用 Motif 工具包。 这一变量暗含 + <makevar>USE_XPM</makevar> 设置。</entry> + </row> + + <row> + <entry><makevar>USE_IMAKE</makevar></entry> + + <entry>此 port 用到了 <command>imake</command>。 这一变量也会自动设置 + <makevar>USE_X_PREFIX</makevar>。</entry> + </row> + + <row> + <entry><makevar>XMKMF</makevar></entry> + + <entry>设置为 <command>xmkmf</command> 的完整路径名， 如果它不在 + <envar>PATH</envar> 中的话。 默认值是 <literal>xmkmf + -a</literal>。</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none"> + <title>用于表示对 X11 某些组件的依赖关系的变量</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><makevar>X_IMAKE_PORT</makevar></entry> + + <entry>用以提供 <command>imake</command> 以及许多其他用于构建 + X11 的工具的 port。</entry> + </row> + + <row> + <entry><makevar>X_LIBRARIES_PORT</makevar></entry> + + <entry>用以提供 X11 库的 port。</entry> + </row> + + <row> + <entry><makevar>X_CLIENTS_PORT</makevar></entry> + + <entry>用以提供 X 客户的 port。</entry> + </row> + + <row> + <entry><makevar>X_SERVER_PORT</makevar></entry> + + <entry>用以提供 X 服务的 port。</entry> + </row> + + <row> + <entry><makevar>X_FONTSERVER_PORT</makevar></entry> + + <entry>用以提供字体服务的 port。</entry> + </row> + + <row> + <entry><makevar>X_PRINTSERVER_PORT</makevar></entry> + + <entry>用以提供打印服务的 port。</entry> + </row> + + <row> + <entry><makevar>X_VFBSERVER_PORT</makevar></entry> + + <entry>用以提供在虚拟帧缓存服务(virtual framebuffer server) 的 port。</entry> + </row> + + <row> + <entry><makevar>X_NESTSERVER_PORT</makevar></entry> + + <entry>用以提供嵌套 X 服务的 port。</entry> + </row> + + <row> + <entry><makevar>X_FONTS_ENCODINGS_PORT</makevar></entry> + + <entry>用以为字体提供编码的 port。</entry> + </row> + + <row> + <entry><makevar>X_FONTS_MISC_PORT</makevar></entry> + + <entry>用以提供多种位图字体的 port。</entry> + </row> + + <row> + <entry><makevar>X_FONTS_100DPI_PORT</makevar></entry> + + <entry>用以提供 100dpi 位图字体的 port。</entry> + </row> + + <row> + <entry><makevar>X_FONTS_75DPI_PORT</makevar></entry> + + <entry>用以提供 75dpi 位图字体的 port。</entry> + </row> + + <row> + <entry><makevar>X_FONTS_CYRILLIC_PORT</makevar></entry> + + <entry>用以提供西里尔位图字体的 port。</entry> + </row> + + <row> + <entry><makevar>X_FONTS_TTF_PORT</makevar></entry> + + <entry>用以提供 &truetype; 字体的 port。</entry> + </row> + + <row> + <entry><makevar>X_FONTS_TYPE1_PORT</makevar></entry> + + <entry>用以提供 Type1 字体的 port。</entry> + </row> + + <row> + <entry><makevar>X_MANUALS_PORT</makevar></entry> + + <entry>用以提供面向开发人员的联机手册的 port。</entry> + </row> + </tbody> + </tgroup> + </table> + + <example id="using-x11-vars"> + <title>在变量中使用与 X11 有关的变量</title> + <programlisting># 使用 X11 库并依赖字体服务和西里尔字体。 +RUN_DEPENDS= ${X11BASE}/bin/xfs:${X_FONTSERVER_PORT} \ + ${X11BASE}/lib/X11/fonts/cyrillic/crox1c.pcf.gz:${X_FONTS_CYRILLIC_PORT} + +USE_XLIB= yes</programlisting> + </example> + </sect1> + + <sect1 id="using-automake"> + <title>使用 <command>automake</command>、 <command>autoconf</command>， + 以及 <command>libtool</command></title> + + <table frame="none"> + <title>用到 automake, autoconf 或 libtool 的 port 可以使用的变量</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>变量</entry> + + <entry>意义</entry> + </row> + </thead> + + <tbody> + <row> + <entry><makevar>AUTOMAKE</makevar></entry> + + <entry>如果没有在 <envar>PATH</envar> 中的话， + <command>automake</command> 的完整路径。</entry> + </row> + + <row> + <entry><makevar>USE_AUTOMAKE_VER</makevar></entry> + + <entry>表示此 port 使用 <command>automake</command>。 + 它可能的取值包括 <literal>14</literal> 和 + <literal>15</literal>， 并且会自动地设置 + <makevar>AUTOMAKE_DIR</makevar> 和 + <makevar>ACLOCAL_DIR</makevar> 这两个变量为适当的值。</entry> + </row> + + <row> + <entry><makevar>AUTOMAKE_ARGS</makevar></entry> + + <entry>设置了 <makevar>USE_AUTOMAKE_VER</makevar> 时， 希望传递给 + <makevar>AUTOMAKE</makevar> 的参数。</entry> + </row> + + <row> + <entry><makevar>AUTOMAKE_ENV</makevar></entry> + + <entry>执行 <makevar>AUTOMAKE</makevar> 之前应设置的环境变量 + (以及这些变量的值)。</entry> + </row> + + <row> + <entry><makevar>ACLOCAL</makevar></entry> + + <entry>GNU <command>aclocal</command> 的完整路径， + 如果它不在 <envar>PATH</envar> 中的话。 默认值是 + <makevar>USE_AUTOMAKE_VER</makevar> 变量的设置决定的。</entry> + </row> + + <row> + <entry><makevar>ACLOCAL_DIR</makevar></entry> + + <entry>GNU <command>aclocal</command> 共享目录的完整路径。 默认值是由 + <makevar>USE_AUTOMAKE_VER</makevar> 变量的设置决定的。</entry> + </row> + + <row> + <entry><makevar>AUTOMAKE_DIR</makevar></entry> + + <entry>GNU <command>automake</command> 共享目录的完整路径。 默认值是由 + <makevar>USE_AUTOMAKE_VER</makevar> 变量的设置决定的。</entry> + </row> + + <row> + <entry><makevar>USE_AUTOCONF_VER</makevar></entry> + + <entry>指定 port 所用 <command>autoconf</command> 的版本。 + 它会自动设置 <literal>GNU_CONFIGURE</literal>。 + 此变量默认值为 213。</entry> + </row> + + <row> + <entry><makevar>AUTOCONF</makevar></entry> + + <entry>GNU <command>autoconf</command> 的完整路径， + 如果它不在 <envar>PATH</envar> 中的话。 默认值与 + <makevar>USE_AUTOCONF_VER</makevar> 变量的设置有关。</entry> + </row> + + <row> + <entry><makevar>AUTOCONF_ARGS</makevar></entry> + + <entry>传递给 <command>autoconf</command> 的命令行参数。</entry> + </row> + + <row> + <entry><makevar>AUTOCONF_ENV</makevar></entry> + + <entry>在运行 <command>autoconf</command> 之前， 将按照它来设置 + <literal><replaceable>变量名</replaceable>=<replaceable>值</replaceable></literal> + 的环境变量。</entry> + </row> + + <row> + <entry><makevar>USE_AUTOHEADER_VER</makevar></entry> + + <entry>指定 port 所用的 <command>autoheader</command> 版本。 + 它会自动设置 <literal>USE_AUTOCONF_VER</literal>。 + 此变量默认值为 213。</entry> + </row> + + <row> + <entry><makevar>AUTOHEADER</makevar></entry> + + <entry>GNU <command>autoheader</command> 的完整路径， + 如果它不在 <envar>PATH</envar> 中的话。 默认值和 + <makevar>USE_AUTOCONF_VER</makevar> 的设置有关。</entry> + </row> + + <row> + <entry><makevar>AUTORECONF</makevar></entry> + + <entry>GNU <command>autoreconf</command> 的完整路径， + 如果它不在 <envar>PATH</envar> 中的话。 默认值和 + <makevar>USE_AUTOCONF_VER</makevar> 的设置有关。</entry> + </row> + + <row> + <entry><makevar>AUTOSCAN</makevar></entry> + + <entry>GNU <command>autoscan</command> 的完整路径， + 如果它不在 <envar>PATH</envar> 中的话。 默认值和 + <makevar>USE_AUTOCONF_VER</makevar> 的设置有关。</entry> + </row> + + <row> + <entry><makevar>AUTOIFNAMES</makevar></entry> + + <entry>GNU <command>autoifnames</command> 的完整路径， + 如果它不在 <envar>PATH</envar> 中的话。 默认值和 + <makevar>USE_AUTOCONF_VER</makevar> 的设置有关。</entry> + </row> + + <row> + <entry><makevar>USE_LIBTOOL_VER</makevar></entry> + + <entry>这一 port 使用的 <command>libtool</command> 版本。 它会自动设置 + <makevar>GNU_CONFIGURE</makevar>。 默认值是 13。</entry> + </row> + + <row> + <entry><makevar>LIBTOOL</makevar></entry> + + <entry><command>libtool</command> 的完整路径， + 如果它不在 <envar>PATH</envar> 中的话。</entry> + </row> + + <row> + <entry><makevar>LIBTOOLFILES</makevar></entry> + + <entry>用于对 <command>libtool</command> 作自动修改的文件。 + 如果定义了 <makevar>USE_AUTOCONF</makevar>， + 则是 <literal>aclocal.m4</literal>； 否则应该是 + <literal>configure</literal>。</entry> + </row> + + <row> + <entry><makevar>LIBTOOLFLAGS</makevar></entry> + + <entry>将要传递给 + <command>ltconfig</command> 的额外标志参数。 默认是 + <literal>--disable-ltlibs</literal>。</entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + + <sect1 id="using-gnome"> + <title>使用 GNOME</title> + + <para>The FreeBSD/GNOME project 使用一组自己的变量来定义 port + 所使用的 GNOME 组件。 + <ulink url="http://www.FreeBSD.org/gnome/docs/porting.html">这些变量的详细列表 + </ulink> 可以在 FreeBSD/GNOME 项目的主页找到。</para> + + <note> + <para>如果只是安装 + <application>pkg-config</application> 元数据文件到 + <filename><makevar>PREFIX</makevar>/libdata/pkgconfig</filename> + 的话， 您的 port 就不需要依赖 GNOME。 同其他 port 类似， + 您的 port 应做好清理的准备， 并删除那些空的目录。 假定您的 port 安装 + <filename>gtkmumble.pc</filename> 到上述位置， + 则应在 <filename>pkg-plist</filename> 中加入：</para> + + <programlisting>libdata/pkgconfig/gtkmumble.pc +@unexec rmdir %B 2>/dev/null || true</programlisting> + + <para>后一行必须紧挨前一行， 以便 <literal>%B</literal> 能够正确地展开。 + 请参考 &man.pkg.create.1; 以进一步了解关于 <filename>pkg-plist</filename> + 中所用的语法的资料。</para> + </note> + + </sect1> + + <sect1 id="using-kde"> + <title>使用 KDE</title> + + <table frame="none"> + <title>用于使用 KDE 的 port 的变量</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><makevar>USE_QT_VER</makevar></entry> + + <entry>表示您的 port 有用到了 Qt。 可选的值是 + <literal>1</literal> 和 + <literal>3</literal>； 它们表示所用的 Qt 的主版本号。 + 这个变量将自动把 <makevar>MOC</makevar> 和 + <makevar>QTCPPFLAGS</makevar> 设置为适当的值。</entry> + </row> + + <row> + <entry><makevar>USE_KDELIBS_VER</makevar></entry> + + <entry>表示您的 port 有使用 KDE 库。 可选的值是 + <literal>3</literal>； 它表示所用 KDE 的主版本号。 + 这个变量会自动将 <makevar>USE_QT_VER</makevar> + 设置为合适的版本。</entry> + </row> + + <row> + <entry><makevar>USE_KDEBASE_VER</makevar></entry> + + <entry>表示您的 port 要使用 KDE 基本运行环境。 可选的值是 + <literal>3</literal>； 它表示所用 KDE 的主版本号。 + 这个变量会自动将 <makevar>USE_KDELIBS_VER</makevar> + 设置为合适的版本。</entry> + </row> + + <row> + <entry><makevar>MOC</makevar></entry> + + <entry>设置 <command>moc</command> 的路径。 + 默认的值， 与 <makevar>USE_QT_VER</makevar> + 有关。</entry> + </row> + + <row> + <entry><makevar>QTCPPFLAGS</makevar></entry> + + <entry>设置用于处理 Qt 代码的 <makevar>CPPFLAGS</makevar>。 + 默认设置与 + <makevar>USE_QT_VER</makevar> 的值有关。</entry> + </row> + </tbody> + </tgroup> + </table> + + </sect1> + + <sect1 id="using-java"> + <title>使用 Java</title> + + <sect2 id="java-variables"> + <title>变量定义</title> + + <para>如果您的 port 需要 Java™ 开发包 (JDK) 来完成构建、 + 支持运行， 甚至完成解开源代码包这样的工作， + 就应该定义 <makevar>USE_JAVA</makevar>。</para> + + <para>在 Ports Collection 中有许多不同的 JDK， 它们的版本各不相同， + 或是来自不同的供应商。 如果您的 port 必须使用其中的某个特定的版本， + 也可以予以定义。 最新的稳定版本是 + <filename role="package">java/jdk14</filename>。</para> + + <table frame="none"> + <title>用到 Java 的 port 可以使用的变量</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>变量</entry> + <entry>意义</entry> + </row> + </thead> + <tbody> + <row> + <entry><makevar>USE_JAVA</makevar></entry> + <entry>只有定义它才能使其他变量生效。</entry> + </row> + <row> + <entry><makevar>JAVA_VERSION</makevar></entry> + <entry>用空格分开的适合 port 使用的 Java 版本。 + 可选的 <literal>"+"</literal> 可以用于指定某个范围的版本 (可以用： + <literal>1.1[+] 1.2[+] 1.3[+] 1.4[+]</literal>)。</entry> + </row> + <row> + <entry><makevar>JAVA_OS</makevar></entry> + <entry>用空格分开的适应 port 的 JDK port 操作系统类型 (可以用： <literal>native + linux</literal>)。</entry> + </row> + <row> + <entry><makevar>JAVA_VENDOR</makevar></entry> + <entry>用空格分开的适应 port 的 JDK port 供应商 + (可以用： <literal>freebsd bsdjava sun ibm + blackdown</literal>)。</entry> + </row> + <row> + <entry><makevar>JAVA_BUILD</makevar></entry> + <entry>设置这个变量表示所选的 JDK port 应被列入 port 的构建依赖关系。</entry> + </row> + <row> + <entry><makevar>JAVA_RUN</makevar></entry> + <entry>设置这个变量表示所选的 JDK port 应被列入 port 的运行环境依赖关系。</entry> + </row> + <row> + <entry><makevar>JAVA_EXTRACT</makevar></entry> + <entry>设置这个变量表示所选的 JDK port 应被列入 port 的解压缩支持依赖关系。</entry> + </row> + <row> + <entry><makevar>USE_JIKES</makevar></entry> + <entry>port 是否应使用 + <command>jikes</command> bytecode 编译器进行构建。 + 如果没有设置， 则 port 将在 + <command>jikes</command> 可用的情况下在构建时使用它。 + 您也可以明确地禁止使用或要求使用 + <command>jikes</command> (通过将这个变量设置为 <literal>'no'</literal> + 或 <literal>'yes'</literal>)。 后一种情形中， <filename + role="package">devel/jikes</filename> 将加入 port 的构建依赖关系。 + 任何情况下， 如果 <command>jikes</command> + 被作为 <command>javac</command> 使用， 则 + <filename>bsd.java.mk</filename> 会定义 + <makevar>HAVE_JIKES</makevar> 变量。</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>下面是在设置了 <makevar>USE_JAVA</makevar> 之后， + port 能够从系统中获得的配置：</para> + + <table frame="none"> + <title>向使用了 Java 的 port 提供的变量</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>变量</entry> + <entry>值</entry> + </row> + </thead> + <tbody> + <row> + <entry><makevar>JAVA_PORT</makevar></entry> + <entry>JDK port 的名字 (例如 + <literal>'java/jdk14'</literal>)。</entry> + </row> + <row> + <entry><makevar>JAVA_PORT_VERSION</makevar></entry> + <entry>JDK port 的完整版本 (例如 + <literal>'1.4.2'</literal>)。 如果您只需要版本号的前两位， 则可用 + <makevar>${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}</makevar>。</entry> + </row> + <row> + <entry><makevar>JAVA_PORT_OS</makevar></entry> + <entry>所用 JDK port 的操作系统 (例如 + <literal>'linux'</literal>)。</entry> + </row> + <row> + <entry><makevar>JAVA_PORT_VENDOR</makevar></entry> + <entry>所用 JDK port 的供应商 (例如 + <literal>'sun'</literal>)。</entry> + </row> + <row> + <entry><makevar>JAVA_PORT_OS_DESCRIPTION</makevar></entry> + <entry>所用 JDK port 操作系统的描述 + (例如 <literal>'Linux'</literal>)。</entry> + </row> + <row> + <entry><makevar>JAVA_PORT_VENDOR_DESCRIPTION</makevar></entry> + <entry>所用 JDK port 供应商的描述 (例如 + <literal>'FreeBSD Foundation'</literal>)。</entry> + </row> + <row> + <entry><makevar>JAVA_HOME</makevar></entry> + <entry>JDK 的安装目录 (例如 + <filename>'/usr/local/jdk1.3.1'</filename>)。</entry> + </row> + <row> + <entry><makevar>JAVAC</makevar></entry> + <entry>所用 Java 编译器的完整路径 (例如 + <filename>'/usr/local/jdk1.1.8/bin/javac'</filename> 或 + <filename>'/usr/local/bin/jikes'</filename>)。</entry> + </row> + <row> + <entry><makevar>JAR</makevar></entry> + <entry>所用 <command>jar</command> 工具的完整路径 (例如 + <filename>'/usr/local/jdk1.2.2/bin/jar'</filename> 或 + <filename>'/usr/local/bin/fastjar'</filename>)。</entry> + </row> + <row> + <entry><makevar>APPLETVIEWER</makevar></entry> + <entry>所用 <command>appletviewer</command> 工具的完整路径 (例如 + <filename>'/usr/local/linux-jdk1.2.2/bin/appletviewer'</filename>)。</entry> + </row> + <row> + <entry><makevar>JAVA</makevar></entry> + <entry>所用 <command>java</command> 执行文件的完整路径。 + 您应使用它来执行 Java 程序 (例如 + <filename>'/usr/local/jdk1.3.1/bin/java'</filename>)。</entry> + </row> + <row> + <entry><makevar>JAVADOC</makevar></entry> + <entry>所用 <command>javadoc</command> 工具的完整路径。</entry> + </row> + <row> + <entry><makevar>JAVAH</makevar></entry> + <entry>所用 <command>javah</command> 程序的完整路径。</entry> + </row> + <row> + <entry><makevar>JAVAP</makevar></entry> + <entry>所用 <command>javap</command> 程序的完整路径。</entry> + </row> + <row> + <entry><makevar>JAVA_KEYTOOL</makevar></entry> + <entry>所用 <command>keytool</command> 工具的完整路径。 + 只有当 JDK 是 Java 1.2 或更高版本时才可用。</entry> + </row> + <row> + <entry><makevar>JAVA_N2A</makevar></entry> + <entry>所用 <command>native2ascii</command> 工具的完整路径。</entry> + </row> + <row> + <entry><makevar>JAVA_POLICYTOOL</makevar></entry> + <entry>所用 <command>policytool</command> 程序的完整路径。 + 只有当 JDK 是 Java 1.2 或更高版本时才可用。</entry> + </row> + <row> + <entry><makevar>JAVA_SERIALVER</makevar></entry> + <entry>所用 <command>serialver</command> 程序的完整路径。</entry> + </row> + <row> + <entry><makevar>RMIC</makevar></entry> + <entry>所用 RMI 桩/架 生成器， + <command>rmic</command> 的完整路径。</entry> + </row> + <row> + <entry><makevar>RMIREGISTRY</makevar></entry> + <entry>所用 RMI 注册表程序， + <command>rmiregistry</command> 的完整路径。</entry> + </row> + <row> + <entry><makevar>RMID</makevar></entry> + <entry>所用 RMI 服务程序 <command>rmid</command> 的完整路径。 + 只有当 JDK 是 Java 1.2 或更高版本时才可用。</entry> + </row> + <row> + <entry><makevar>JAVA_CLASSES</makevar></entry> + <entry>所用 JDK 类文件目录的完整路径。 + 对 JDK 1.2 和更高版本的环境而言， 这应该是 + <filename>${JAVA_HOME}/jre/lib/rt.jar</filename>。 更早版本的 + JDK 则使用 + <filename>${JAVA_HOME}/lib/classes.zip</filename>。</entry> + </row> + <row> + <entry><makevar>HAVE_JIKES</makevar></entry> + <entry>随 <command>jikes</command> 是否将被应用于 port + 的构建过程而定 (参见前述 <makevar>USE_JIKES</makevar>)。</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>您可以使用 <literal>java-debug</literal> make target + 以获取用于调试 port 的信息。 大多数前述变量的值皆会予以呈现。</para> + + <para>此外， 还会定义下述常量， 以确保所有的 + Java port 均以一致之方式安装：</para> + + <table frame="none"> + <title>为使用 Java 的 port 定义的常量</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>常量</entry> + <entry>值</entry> + </row> + </thead> + <tbody> + <row> + <entry><makevar>JAVASHAREDIR</makevar></entry> + <entry>所有 Java 相关资料的安装根目录。 + 默认值： <filename>${PREFIX}/share/java</filename>. + </entry> + </row> + <row> + <entry><makevar>JAVAJARDIR</makevar></entry> + <entry>用以安装 JAR 文件的目录。 默认值： + <filename>${JAVASHAREDIR}/classes</filename>。</entry> + </row> + <row> + <entry><makevar>JAVALIBDIR</makevar></entry> + <entry>其他 port 安装的 JAR 文件所在的目录。 默认值： + <filename>${LOCALBASE}/share/java/classes</filename>。</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>相关的项也在 + <makevar>PLIST_SUB</makevar> (在 + <xref linkend="porting-plist"> 中进行介绍) 和 + <makevar>SUB_LIST</makevar> 提供了对应的定义。</para> + + </sect2> + + <sect2 id="java-building-with-ant"> + <title>采用 Ant 进行构建</title> + + <para>如果 port 采用 Apache Ant 进行构建， + 则需要定义 <makevar>USE_ANT</makevar>。 如是， 则 Ant + 将作为 子-make 命令来使用。 如果 port 未予定义 + <literal>do-build</literal> target， 则默认将依 <makevar>MAKE_ENV</makevar>、 + <makevar>MAKE_ARGS</makevar> 和 <makevar>ALL_TARGETS</makevar> + 的设置执行 Ant。 这类似于 <makevar>USE_GMAKE</makevar> 的机制， + 后者在 <xref linkend="makefile-build"> 有所介绍。</para> + + <para>若 <command>jikes</command> 被作为 + <command>javac</command> 使用 (参见 <xref linkend="java-variables"> + 中的 <makevar>USE_JIKES</makevar>)， 则 Ant 将自动地用它来构建 port。</para> + + </sect2> + + <sect2 id="java-best-practices"> + <title>最佳实践</title> + + <para>如果您正移植某个 Java 库， 您的 port 应把 + JAR 文件安装到 <filename>${JAVAJARDIR}</filename>， 而其他文件则应放在 + <filename>${JAVASHAREDIR}/${PORTNAME}</filename> 下 + (除了文档， 参见下文)。 要减少打包文件的尺寸， + 您可以直接在 <filename>Makefile</filename> 中引用这些 JAR 文件， + 具体做法是使用下面的语句 (此处的 <filename>myport.jar</filename> + 是作为 port 一部分安装的 JAR 文件的名字)：</para> + + <programlisting>PLIST_FILES+= %%JAVAJARDIR%%/myport.jar</programlisting> + + <para>移植 Java 应用程序时， port 通常会希望将所有文件安装到同一目录 + (包括其依赖的 JAR)。 这时强烈建议使用 + <filename>${JAVASHAREDIR}/${PORTNAME}</filename>。 + 移植软件的开发人员， 可以自行决定是否将所依赖的其他 JAR 安装到此目录， + 或直接使用已经装好的那些 + (来自 <filename>${JAVAJARDIR}</filename>)。</para> + + <para>无论您正制作哪一类的 port (库或者应用程序)， + 附加的文档都应安装到和其他 port + <link linkend="dads-documentation">同样的位置</link>。 + 已经知道， JavaDoc 会根据 JDK 版本的不同而产生不同的文件。 + 对于那些不打算强制使用某一特定版本 JDK 的 port 而言， + 这无疑提高了制作装箱单 + (<filename>pkg-plist</filename>) 的难度。 这是为什么强烈建议使用 + <makevar>PORTDOCS</makevar> 宏的原因。 更进一步， 即使您能够预测 + <command>javadoc</command> 将要生成的文件， 所需的 + <filename>pkg-plist</filename> 的尺寸， 也是鼓吹使用 + <makevar>PORTDOCS</makevar> 的一大理由。</para> + + <para><makevar>DATADIR</makevar> 的默认值是 + <filename>${PREFIX}/share/${PORTNAME}</filename>。 + 对 Java port 而言将 <makevar>DATADIR</makevar> 改为 + <filename>${JAVASHAREDIR}/${PORTNAME}</filename> 是一个好主意。 + 当然， <makevar>DATADIR</makevar> 会自动加到 + <makevar>PLIST_SUB</makevar> 中 (在 <xref + linkend="porting-plist"> 有所介绍) 因此您可以在 + <filename>pkg-plist</filename> 中直接使用 + <literal>%%DATADIR%%</literal>。</para> + + <para>撰写本文时， 对是应该从源代码构建， 还是直接安装预编译的 + Java ports 安装包并没有明确的规定。 尽管如此， <ulink + url="http://www.freebsd.org/java/">&os; Java Project</ulink> + 的开发人员仍鼓励移植软件的开发者在不麻烦的情况下尽可能从源代码完成构建。</para> + + <para>本节中所介绍的全部特性， 均是在 <filename>bsd.java.mk</filename> + 中实现的。 如果您感觉自己的 port 需要更为复杂的 Java 支持， + 请首先参阅 <ulink + url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.java.mk"> + bsd.java.mk CVS 日志</ulink>， 因为通常撰文介绍最新特性需要一些时间。 + 此外， 如果您认为所缺少的支持对许多其他 Java port 亦属有益， + 请在 &a.java; 对其进行讨论。</para> + + <para>在 PR 中的 <literal>java</literal> 类别， + 主要是用于 &os; Java project 移植 JDK 本身之用。 + 因而， 提交您的 Java port 时， 应归入 + <literal>ports</literal> 类别， 除非您正尝试解决的问题是 JDK + 实现本身或 <filename>bsd.java.mk</filename> 的。</para> + + <para>类似地， 您应参考 <xref linkend="makefile-categories"> 中所详述的关于 + <makevar>CATEGORIES</makevar> 在 Java port 中的使用规则。</para> + + </sect2> + + </sect1> + + <sect1 id="using-php"> + <title>使用 Apache 和 PHP</title> + + <sect2 id="using-apache"> + <title>Apache</title> + + <table frame="none"> + <title>用到 Apache 的 port 可以使用的变量</title> + + <tgroup cols="2"> + <tbody> + + <row> + <entry>USE_APACHE</entry> + + <entry>此 port 需要 Apache。</entry> + </row> + + <row> + <entry>WITH_APACHE2</entry> + + <entry>此 port 需要 Apache 2.0。 如果没有这个变量， + 则 port 将依赖 Apache 1.3。</entry> + </row> + + <row> + <entry>APXS</entry> + + <entry>到 <command>apxs</command> 程序的完整路径 + (这是一个只读的变量)。</entry> + </row> + + </tbody> + </tgroup> + </table> + + </sect2> + + <sect2 id="php-variables"> + <title>PHP</title> + + <table frame="none"> + <title>用到 PHP 的 port 中可以使用的变量</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><makevar>USE_PHP</makevar></entry> + + <entry>此 port 需要 PHP。 取值为 <literal>yes</literal> + 将把 PHP 加入依赖关系。 此外， 还可以在此指定将所需要的 PHP + 扩展模块。 例如： <literal>pcre xml + gettext</literal></entry> + </row> + + <row> + <entry><makevar>DEFAULT_PHP_VER</makevar></entry> + + <entry>选择在没有安装 PHP 时自动安装的 PHP 主版本。 默认是 + <literal>4</literal>。 可选 <literal>4</literal>、 + <literal>5</literal> 之一。</entry> + </row> + + <row> + <entry><makevar>BROKEN_WITH_PHP</makevar></entry> + + <entry>此 port 无法与给定版本的 PHP 一同工作。 + 可选值为 <literal>4</literal>、 + <literal>5</literal> 之一。</entry> + </row> + + <row> + <entry><makevar>USE_PHPIZE</makevar></entry> + + <entry>此 port 将作为 PHP 扩展模块进行构建。</entry> + </row> + + <row> + <entry><makevar>USE_PHPEXT</makevar></entry> + + <entry>此 port 将作为 PHP 扩展， + 且需要作为扩展模块注册。</entry> + </row> + + <row> + <entry><makevar>USE_PHP_BUILD</makevar></entry> + + <entry>构建依赖于 PHP。</entry> + </row> + + <row> + <entry><makevar>WANT_PHP_CLI</makevar></entry> + + <entry>希望使用 CLI (命令行) 版本的 PHP。</entry> + </row> + + <row> + <entry><makevar>WANT_PHP_CGI</makevar></entry> + + <entry>希望使用 CGI 版本的 PHP。</entry> + </row> + + <row> + <entry><makevar>WANT_PHP_MOD</makevar></entry> + + <entry>希望使用 Apache 模块版本的 PHP。</entry> + </row> + + <row> + <entry><makevar>WANT_PHP_SCR</makevar></entry> + + <entry>希望使用 CLI 或 CGI 版本的 PHP。</entry> + </row> + + <row> + <entry><makevar>WANT_PHP_WEB</makevar></entry> + + <entry>希望使用 Apache 模块或 CGI 版本的 PHP。</entry> + </row> + + <row> + <entry><makevar>WANT_PHP_PEAR</makevar></entry> + + <entry>希望使用 PEAR 框架。</entry> + </row> + + </tbody> + </tgroup> + </table> + + </sect2> + + <sect2> + <title>PEAR 模块</title> + + <para>移植 PEAR 模块的过程非常简单。</para> + + <para>使用 <makevar>FILES</makevar>、 + <makevar>TESTS</makevar>、 <makevar>DATA</makevar>、 + <makevar>SQLS</makevar>、 <makevar>SCRIPTFILES</makevar>、 + <makevar>DOCS</makevar> 以及 <makevar>EXAMPLES</makevar> + 这些变量来指明您希望安装的文件。 + 所有这里列出的文件都会自动安装到合适的位置， 并加入 + <filename>pkg-plist</filename>。</para> + + <para>在 <filename>Makefile</filename> 的最后一行引用 + <filename>${PORTSDIR}/devel/pear-PEAR/Makefile.common</filename>。</para> + + <example id="pear-makefile"> + <title>用于 PEAR 类的 Makefile 例子</title> + <programlisting>PORTNAME= Date +PORTVERSION= 1.4.3 +CATEGORIES= devel www pear + +MAINTAINER= example@domain.com +COMMENT= PEAR Date and Time Zone Classes + +BUILD_DEPENDS= ${PEARDIR}/PEAR.php:${PORTSDIR}/devel/pear-PEAR +RUN_DEPENDS= ${BUILD_DEPENDS} + +FILES= Date.php Date/Calc.php Date/Human.php Date/Span.php \ + Date/TimeZone.php +TESTS= test_calc.php test_date_methods_span.php testunit.php \ + testunit_date.php testunit_date_span.php wknotest.txt \ + bug674.php bug727_1.php bug727_2.php bug727_3.php \ + bug727_4.php bug967.php weeksinmonth_4_monday.txt \ + weeksinmonth_4_sunday.txt weeksinmonth_rdm_monday.txt \ + weeksinmonth_rdm_sunday.txt +DOCS= TODO +_DOCSDIR= . + +.include <bsd.port.pre.mk> +.include "${PORTSDIR}/devel/pear-PEAR/Makefile.common" +.include <bsd.port.post.mk></programlisting> + + </example> + + </sect2> + + </sect1> + + <sect1 id="using-python"> + <title>使用 Python</title> + + <table frame="none"> + <title>对用到 Python 的 port 最有用的一些变量</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry><makevar>USE_PYTHON</makevar></entry> + + <entry>此 port 需要 Python。 可以用 + <literal>2.3+</literal> 这样的形式来指定所希望的版本。</entry> + </row> + + <row> + <entry><makevar>USE_PYDISTUTILS</makevar></entry> + + <entry>使用 Python distutils 来完成配置、 编译和安装。 对包含 + <filename>setup.py</filename> 的 port 而言这是必需的。</entry> + </row> + + <row> + <entry><makevar>PYTHON_PKGNAMEPREFIX</makevar></entry> + + <entry>作为 <makevar>PKGNAMEPREFIX</makevar> 来区分不同 Python + 版本的 package。 例如： <literal>py24-</literal></entry> + </row> + + <row> + <entry><makevar>PYTHON_SITELIBDIR</makevar></entry> + + <entry>全站 package 所在的目录。 一般用于安装 + Python 模块。 如果可能， 尽量在 + <filename>pkg-plist</filename> 中使用 + <literal>%%PYTHON_SITELIBDIR%%</literal>。 默认值： + <literal>lib/python2.4/site-packages</literal></entry> + </row> + + <row> + <entry><makevar>PYNUMERIC</makevar></entry> + + <entry>将数值处理扩展模块加入依赖关系。</entry> + </row> + + <row> + <entry><makevar>PYXML</makevar></entry> + + <entry>将 XML 扩展模块加入依赖关系。</entry> + </row> + + <row> + <entry><makevar>USE_TWISTED</makevar></entry> + + <entry>将 twistedCore 加入依赖关系。 + 也可以用这个变量指定所需的组件， + 例如： <literal>web lore pair + flow</literal></entry> + </row> + + <row> + <entry><makevar>USE_ZOPE</makevar></entry> + + <entry>加入对 Zope， 一种 web 应用平台的依赖。 + 这会把 Python 依赖改为 Python 2.3。 此外 + <makevar>ZOPEBASEDIR</makevar> 也会自动设为 + Zope 安装目录的位置。</entry> + </row> + + </tbody> + </tgroup> + </table> + + <para>完整的可用变量列表， 可以在 + <filename>/usr/ports/Mk/bsd.python.mk</filename> + 中找到。</para> + + </sect1> + + <sect1 id="using-emacs"> + <title>使用 Emacs</title> + + <para>本节尚有待撰写。</para> + </sect1> + + <sect1 id="using-ruby"> + <title>使用 Ruby</title> + + <table frame="none"> + <title>使用 Ruby 的 port 可以使用的变量</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>变量</entry> + <entry>说明</entry> + </row> + </thead> + <tbody> + <row> + <entry><makevar>USE_RUBY</makevar></entry> + + <entry>此 port 需要 Ruby。</entry> + </row> + + <row> + <entry><makevar>USE_RUBY_EXTCONF</makevar></entry> + + <entry>此 port 使用 <filename>extconf.rb</filename> + 来完成配置。</entry> + </row> + + <row> + <entry><makevar>USE_RUBY_SETUP</makevar></entry> + + <entry>此 port 使用 <filename>setup.rb</filename> + 来完成配置。</entry> + </row> + + <row> + <entry><makevar>RUBY_SETUP</makevar></entry> + + <entry>将此变量名设置为所用的 + <filename>setup.rb</filename> 的文件名。 通常会是 + <filename>install.rb</filename>。</entry> + </row> + + </tbody> + </tgroup> + </table> + + <para>下表展示了 ports 系统提供给 port 作者的一些变量。 + 您应使用这些变量， 以便把文件装到合适的位置。 请尽可能多地在 + <filename>pkg-plist</filename> 中使用它们。 这些变量不应在 port + 中重新定义。</para> + + <table frame="none"> + <title>使用 Ruby 的 port 中的一些可用的只读变量</title> + + <tgroup cols="3"> + <thead> + <row> + <entry>变量</entry> + <entry>说明</entry> + <entry>示范值</entry> + </row> + </thead> + <tbody> + + <row> + <entry><makevar>RUBY_PKGNAMEPREFIX</makevar></entry> + + <entry>作为 <makevar>PKGNAMEPREFIX</makevar> 以区分用于不同 + Ruby 版本的 package。</entry> + + <entry><literal>ruby18-</literal></entry> + </row> + + <row> + <entry><makevar>RUBY_VERSION</makevar></entry> + + <entry><literal>x.y.z</literal> 形式的完整 ruby 版本。</entry> + + <entry><literal>1.8.2</literal></entry> + </row> + + <row> + <entry><makevar>RUBY_SITELIBDIR</makevar></entry> + + <entry>平台无关库的安装路径。</entry> + + <entry><literal>/usr/local/lib/ruby/site_ruby/1.8</literal></entry> + </row> + + <row> + <entry><makevar>RUBY_SITEARCHILIBDIR</makevar></entry> + + <entry>平台相关的库的安装路径。</entry> + + <entry><literal>/usr/local/lib/ruby/site_ruby/1.8/amd64-freebsd6</literal></entry> + </row> + + <row> + <entry><makevar>RUBY_MODDOCDIR</makevar></entry> + + <entry>模块文档的安装路径。</entry> + + <entry><literal>/usr/local/share/doc/ruby18/patsy</literal></entry> + </row> + + <row> + <entry><makevar>RUBY_MODEXAMPLESDIR</makevar></entry> + + <entry>模块用例的安装路径。</entry> + + <entry><literal>/usr/local/share/examples/ruby18/patsy</literal></entry> + </row> + + </tbody> + </tgroup> + </table> + + <para>可用变量的完整列表， 可以在 + <filename>/usr/ports/Mk/bsd.ruby.mk</filename> 中找到。</para> + + </sect1> + + <sect1 id="using-sdl"> + <title>使用 SDL</title> + + <para>变量 <makevar>USE_SDL</makevar> 可以用于自动配置 port + 的依赖关系， 以适应使用类似 + <filename role="package">devel/sdl12</filename> 和 + <filename role="package">x11-toolkits/sdl_gui</filename> + 这些依赖 SDL 的库的情形。</para> + + <para>目前系统能够识别下列 SDL 库：</para> + + <itemizedlist> + <listitem> + <para>sdl: <filename role="package">devel/sdl12</filename></para> + </listitem> + + <listitem> + <para>gfx: <filename role="package">graphics/sdl_gfx</filename></para> + </listitem> + + <listitem> + <para>gui: <filename role="package">x11-toolkits/sdl_gui</filename></para> + </listitem> + + <listitem> + <para>image: <filename role="package">graphics/sdl_image</filename></para> + </listitem> + + <listitem> + <para>ldbad: <filename role="package">devel/sdl_ldbad</filename></para> + </listitem> + + <listitem> + <para>mixer: <filename role="package">audio/sdl_mixer</filename></para> + </listitem> + + <listitem> + <para>mm: <filename role="package">devel/sdlmm</filename></para> + </listitem> + + <listitem> + <para>net: <filename role="package">net/sdl_net</filename></para> + </listitem> + + <listitem> + <para>sound: <filename role="package">audio/sdl_sound</filename></para> + </listitem> + + <listitem> + <para>ttf: <filename role="package">graphics/sdl_ttf</filename></para> + </listitem> + </itemizedlist> + + <para>因此， 如果 port 需要依赖 + <filename role="package">net/sdl_net</filename> 和 + <filename role="package">audio/sdl_mixer</filename>， + 则对应的写法将是：</para> + + <programlisting>USE_SDL= net mixer</programlisting> + + <para>同时， <filename role="package">net/sdl_net</filename> 和 + <filename role="package">audio/sdl_mixer</filename> 所依赖的 + <filename role="package">devel/sdl12</filename> 也会被自动地加入。</para> + + <para>加入您使用 <makevar>USE_SDL</makevar>， 它将自动地：</para> + + <itemizedlist> + <listitem> + <para>将对于 <application>sdl12-config</application> 的依赖关系加入到 + <makevar>BUILD_DEPENDS</makevar></para> + </listitem> + + <listitem> + <para>将变量 <makevar>SDL_CONFIG</makevar> 加入到 + <makevar>CONFIGURE_ENV</makevar></para> + </listitem> + + <listitem> + <para>将对所选的库的依赖， 加入到 + <makevar>LIB_DEPENDS</makevar></para> + </listitem> + </itemizedlist> + + <para>要检查某个特定的 SDL 库是否可用， + 可以通过 <makevar>WANT_SDL</makevar> 变量来达到目的：</para> + + <programlisting>WANT_SDL=yes + +.include <bsd.port.pre.mk> + +.if ${HAVE_SDL:Mmixer}!="" +USE_SDL+= mixer +.endif + +.include <bsd.port.post.mk></programlisting> + + </sect1> + </chapter> + +<!-- + + <chapter> + <title>ELF support</title> + + <para>Since FreeBSD changed to an ELF binary format shortly after + 3.0-RELEASE, we need to convert many ports that build shared + libraries to support ELF. Complicating this task is that a 3.0 + system can run as both ELF and a.out, and we wish to unofficially + support the 2.2 branch as long as possible. Below are the guidelines on + how to convert a.out only ports to support both a.out and ELF + compilation.</para> + + <para>Some part of this list is only applicable during the conversion, + but will be left here for a while for reference in case you have come + across some old port you wish to upgrade.</para> + + <sect1> + <title>Moving a.out libraries out of the way</title> + + <para>Any a.out libraries should be moved out of + <filename>/usr/local/lib</filename> and similar to an + <filename>aout</filename> subdirectory. (If you do not move them out + of the way, ELF ports will happily overwrite a.out libraries.) The + <maketarget>move-aout-libs</maketarget> target in the 3.0-CURRENT + <filename>src/Makefile</filename> (called from + <maketarget>aout-to-elf</maketarget>) will do this for you. It will + only move a.out libs so it is safe to call it on a system with both + ELF and a.out libs in the standard directories.</para> + </sect1> + + <sect1> + <title>Format</title> + + <para>The ports tree will build packages in the format the machine is + in. This means a.out for 2.2 and a.out or ELF for 3.0 depending on + what <command>`objformat`</command> returns. Also, once users move + a.out libraries to a subdirectory, building a.out libraries will be + unsupported. (I.e., it may still work if you know what you are + doing, but you are on your own.)</para> + + <note> + <para>If a port only works for a.out, set + <makevar>BROKEN_ELF</makevar> to a string describing the reason + why. Such ports will be skipped during a build on an ELF + system.</para> + </note> + </sect1> + + <sect1> + <title><makevar>PORTOBJFORMAT</makevar></title> + + <para><filename>bsd.port.mk</filename> will set + <makevar>PORTOBJFORMAT</makevar> to <literal>aout</literal> or + <literal>elf</literal> and export it in the environments + <envar>CONFIGURE_ENV</envar>, <envar>SCRIPTS_ENV</envar> and + <envar>MAKE_ENV</envar>. (It is always going to be + <literal>aout</literal> in 2.2-STABLE). It is also passed to + <maketarget>PLIST_SUB</maketarget> as + <literal>PORTOBJFORMAT=${PORTOBJFORMAT}</literal>. (See comment on + <literal>ldconfig</literal> lines below.)</para> + + <para>The variable is set using this line in + <filename>bsd.port.mk</filename>:</para> + + <programlisting>PORTOBJFORMAT!= test -x /usr/bin/objformat && /usr/bin/objformat || echo aout</programlisting> + + <para>Ports' make processes should use this variable to decide what to + do. However, if the port's <filename>configure</filename> script + already automatically detects an ELF system, it is not necessary to + refer to <makevar>PORTOBJFORMAT</makevar>.</para> + </sect1> + + <sect1> + <title>Building shared libraries</title> + + <para>The following are differences in handling shared libraries for + a.out and ELF.</para> + + <itemizedlist> + <listitem> + <para>Shared library versions</para> + + <para>An ELF shared library should be called + <filename>libfoo.so.<replaceable>M</replaceable></filename> + where <replaceable>M</replaceable> is the single version number, + and an a.out library should be called + <filename>libfoo.so.<replaceable>M</replaceable>.<replaceable>N</replaceable></filename> + where <replaceable>M</replaceable> is the major version and + <replaceable>N</replaceable> is the minor version number. + Do not mix those; <emphasis>never</emphasis> install an ELF + shared library called + <filename>libfoo.so.<replaceable>N</replaceable>.<replaceable>M</replaceable></filename> + or an a.out shared library (or symlink) called + <filename>libfoo.so.<replaceable>N</replaceable></filename>.</para> + </listitem> + + <listitem> + <para>Linker command lines</para> + + <para>Assuming <command>cc -shared</command> is used rather than + <command>ld</command> directly, the only difference is that you + need to add + <option>-Wl,-<replaceable>soname,libfoo.so.M</replaceable></option> + on the command line for ELF.</para> + </listitem> + </itemizedlist> + + <para>You need to install a symlink from + <filename>libfoo.so</filename> to + <filename>libfoo.so.<replaceable>N</replaceable></filename> to make + ELF linkers happy. Since it should be listed in + <filename>pkg-plist</filename> too, and it will not hurt in the a.out case + (some ports even require the link for dynamic loading), you should + just make this link regardless of the setting of + <makevar>PORTOBJFORMAT</makevar>.</para> + </sect1> + + <sect1> + <title><makevar>LIB_DEPENDS</makevar></title> + + <para>All port <filename>Makefile</filename>s are edited to remove minor numbers from + <makevar>LIB_DEPENDS</makevar>, and also to have the regexp support + removed. (E.g., <literal>foo\\.1\\.\\(33|40\\)</literal> becomes + <literal>foo.2</literal>.) They will be matched using <command>grep + -wF</command>.</para> + </sect1> + + <sect1> + <title><filename>pkg-plist</filename></title> + + <para><filename>pkg-plist</filename> should contain the short (ELF) shlib + names if the a.out minor number is zero, and the long (a.out) names + otherwise. <filename>bsd.port.mk</filename> will automatically add + <literal>.0</literal> to the end of short shlib lines if + <makevar>PORTOBJFORMAT</makevar> equals <literal>aout</literal>, and + will delete the minor number from long shlib names if + <makevar>PORTOBJFORMAT</makevar> equals + <literal>elf</literal>.</para> + + <para>In cases where you really need to install shlibs with two + versions on an ELF system or those with one version on an a.out + system (for instance, ports that install compatibility libraries for + other operating systems), define the variable + <makevar>NO_FILTER_SHLIBS</makevar>. This will turn off the editing + of <filename>pkg-plist</filename> mentioned in the previous + paragraph.</para> + </sect1> + + <sect1> + <title><literal>ldconfig</literal></title> + + <para>The <literal>ldconfig</literal> line in <filename>Makefile</filename>s should + read:</para> + + <programlisting>${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....</programlisting> + + <para>In <filename>pkg-plist</filename> it should read;</para> + + <programlisting>@exec /usr/bin/env OBJFORMAT=%%PORTOBJFORMAT%% /sbin/ldconfig -m ... +@unexec /usr/bin/env OBJFORMAT=%%PORTOBJFORMAT%% /sbin/ldconfig -R</programlisting> + + <para>This is to ensure that the correct <command>ldconfig</command> + will be called depending on the format of the package, not the + default format of the system.</para> + </sect1> + </chapter> + +--> + + <chapter id="porting-masterdir"> + <title><makevar>MASTERDIR</makevar> (主 port 所在的目录)</title> + + <para>如果您的 port 需要通过某些变量 (例如， 分辨率， 或纸型) + 取不同的值来构建软件包， + 则为它创建一个新的目录将使用户更容易知道他们自己在做什么； + 此时应在不同的 port 之间共享尽可能多的文件。 一般情况下， 您只需要一个很短的 + <filename>Makefile</filename>， 如果对变量的运用得当的话。 + 这种 <filename>Makefile</filename> 中可以使用 <makevar>MASTERDIR</makevar> + 来指定其他文件所在的目录。 另外， 您还应指定一个 + <link linkend="porting-pkgname"><makevar>PKGNAMESUFFIX</makevar></link> + 以便让 package 的名字上有所区别。</para> + + <para>这些使用例子来加以阐述会更为明晰。 下面是 + <filename>japanese/xdvi300/Makefile</filename> 的部分代码：</para> + + <programlisting>PORTNAME= xdvi +PORTVERSION= 17 +PKGNAMEPREFIX= ja- +PKGNAMESUFFIX= ${RESOLUTION} + : +# default +RESOLUTION?= 300 +.if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \ + ${RESOLUTION} != 300 && ${RESOLUTION} != 400 + @${ECHO} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\"" + @${ECHO} "Possible values are: 118, 240, 300 (default) and 400." + @${FALSE} +.endif</programlisting> + + <para><filename role="package">japanese/xdvi300</filename> 也提供了全部常规的补丁， + 以及打包用到的文件等等内容。 如果您在那里输入 <command>make</command>， + 它将使用默认的分辨率值 (300) 并构建 port。</para> + + <para>与其他分辨率的版本类似， 下面是 <emphasis>完整的</emphasis> + <filename>xdvi118/Makefile</filename>：</para> + + <programlisting>RESOLUTION= 118 +MASTERDIR= ${.CURDIR}/../xdvi300 + +.include "${MASTERDIR}/Makefile"</programlisting> + + <para>(<filename>xdvi240/Makefile</filename> 和 + <filename>xdvi400/Makefile</filename> 是相似的)。 + <makevar>MASTERDIR</makevar> 定义会告诉 + <filename>bsd.port.mk</filename> 常规的目录， + 例如 <makevar>FILESDIR</makevar> 和 + <makevar>SCRIPTDIR</makevar> 应该在 + <filename>xdvi300</filename> 中查找。 + <literal>RESOLUTION=118</literal> 这行将覆盖在 + <filename>xdvi300/Makefile</filename> 所进行的 + <literal>RESOLUTION=300</literal> 设置， 从而以分辨率 118 + 构建 port。</para> + </chapter> + + <chapter id="shared"> + <title>共享库的版本</title> + + <para>请阅读我们的 <ulink url="&url.books.developers-handbook;/policies-shlib.html">关于共享库版本命名的规定</ulink> + 以了解在为共享库指定版本时的一般规则。 + 不要盲目地假定软件的作者知道他们在做什么； 许多人并不清楚。 + 仔细地考虑这些细节非常重要， 因为我们需要面对许多互相冲突的软件并存的情形。 + 粗心地引入 port 曾经在过去导致过非常严重的问题 (您是否留意过， + 为什么 <filename>jpeg-6b</filename> 的共享库版本是 9?)。 如果有疑虑， + 请致信 &a.ports; 询问。 绝大多数时候， + 您的工作会以选择了一个适当的共享库版本， + 并恰当地对软件进行修改而得以实现。</para> + +<!-- + <para>However, if there is a port which is a different version of the + same software already in the tree, the situation is much more complex. + In short, the FreeBSD implementation does not allow the user to + specify to the linker which version of shared library to link against + (the linker will always pick the highest numbered version). This + means, if there is a <filename>libfoo.so.3.2</filename> and + <filename>libfoo.so.4.0</filename> in the system, there is no way to + tell the linker to link a particular application to + <filename>libfoo.so.3.2</filename>. It is essentially completely + overshadowed in terms of compilation-time linkage. In this case, the + only solution is to rename the <emphasis>base</emphasis> part of the + shared library. For instance, change + <filename>libfoo.so.4.0</filename> to + <filename>libfoo4.so.1.0</filename> so both version 3.2 and 4.0 can be + linked from other ports.</para> +--> + </chapter> + + <chapter id="porting-manpages"> + <title>联机手册</title> + + <para>如果使用了 <makevar>MAN[1-9LN]</makevar> 变量， + 就会自动地将联机手册加入到 <filename>pkg-plist</filename> 中 + (这意味着您 <emphasis>绝不</emphasis> 应该把联机手册列入 + <filename>pkg-plist</filename>—参见 <link + linkend="porting-plist">生成 PLIST</link> 了解更多细节)。 + 此外， 这也会让安装阶段自动地根据在 <filename>/etc/make.conf</filename> + 中的 <makevar>NOMANCOMPRESS</makevar> 设置来压缩或解压缩联机手册文件。</para> + + <para>如果您的 port 尝试将联机手册使用硬连接安装成多个名字， + 则必须通过 <makevar>MLINKS</makevar> 变量来予以说明。 + 由您的 port 安装的连接会被 <filename>bsd.port.mk</filename> + 毁掉和重建， 以保证它们指向了正确的文件。 所有在 MLINKS 中给出的联机手册， + 都不应再在 <filename>pkg-plist</filename> 中列出。</para> + + <para>要指定联机手册是否在安装时进行压缩， + 可以使用 <makevar>MANCOMPRESSED</makevar> 变量。 + 这个变量可以使用三个值， <literal>yes</literal>、 <literal>no</literal> 和 + <literal>maybe</literal>。 <literal>yes</literal> + 表示联机手册已经以压缩的形式安装， <literal>no</literal> 表示还没有， + 而 <literal>maybe</literal> 则表示所安装的软件会尊重 + <makevar>NOMANCOMPRESS</makevar> 的设置值， 换言之 + <filename>bsd.port.mk</filename> 不需要做什么特别的事情。</para> + + <para>如果设置了 <makevar>USE_IMAKE</makevar> 而未定义 + <makevar>NO_INSTALL_MANPAGES</makevar>， + <makevar>MANCOMPRESSED</makevar> 会自动设置为 + <literal>yes</literal>， 反之则是 <literal>no</literal>。 + 除非默认值不合适， 否则就不需要在您的 port 中修改之。</para> + + <para>如果您的 port 将手册页的目录放到了 + <makevar>PREFIX</makevar> 以外的地方， 则可以使用 + <makevar>MANPREFIX</makevar> 来设置它。 此外， + 如果只有某些部分的联机手册会安装到不标准的位置， 例如某些 <literal>perl</literal> + 模块的 port， 还可以配置 + <makevar>MAN<replaceable>sect</replaceable>PREFIX</makevar> (这里 + <replaceable>sect</replaceable> 是 <literal>1-9</literal>、 + <literal>L</literal> 或 <literal>N</literal> 之一)。</para> + + <para>如果您的联机手册需要装入专用于某一语言专用的子目录， + 需要将 <makevar>MANLANG</makevar> 设置为那一语言。 + 这个变量的默认值是 <literal>""</literal> (也就是只用英语)。</para> + + <para>下面是一个综合的例子。</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>这表示 port 会安装六个文件；</para> + + <programlisting>${PREFIX}/man/man1/foo.1.gz +${PREFIX}/man/ja/man1/foo.1.gz +${PREFIX}/share/foobar/man/man3/bar.3.gz +${PREFIX}/share/foobar/man/ja/man3/bar.3.gz +${PREFIX}/man/man4/baz.4.gz +${PREFIX}/man/ja/man4/baz.4.gz</programlisting> + + <para>另外 <filename>${PREFIX}/man/man8/alt-name.8.gz</filename> + 可能会通过您的 port 安装， 也可能不会。 无论如何， + 都会创建一个符号连接， 把 foo(1) 和 + alt-name(8) 联机手册连起来。</para> + + </chapter> + + <chapter id="porting-motif"> + <title>需要使用 Motif 的 port</title> + + <para>许多程序在编译时会用到 Motif 库 (有很多商业版本， + 另外也有一个能够支持许多应用程序运行的 + <filename role="package">x11-toolkits/lesstif</filename>)。 + 因为这是一个非常流行的工具包， 而且其授权通常允许发布静态连接的可执行文件， + 我们对处理需要 Motif 的 port 是有一些特殊的规定， + 这样就能够轻松地编译动态连接的可执行文件 (用于从 port + 编译程序的用户) 或静态地连接 (用于那些希望发布 package 的用户)。</para> + + <sect1 id="motif-use"> + <title><makevar>USE_MOTIF</makevar> (用到了 Motif)</title> + + <para>如果您的 port 需要 Motif， 则应在 + <filename>Makefile</filename> 定义它。 这样没有安装 Motif + 的用户就不会尝试编译它了。</para> + </sect1> + + <sect1 id="motif-lib"> + <title><makevar>MOTIFLIB</makevar> (指定使用的 Motif 库版本)</title> + + <para>这个变量会被 <filename>bsd.port.mk</filename> 设置为对 Motif + 库的适当的引用。 请对您的 port 中用到的源代码进行修改， + 把所有直接指定 Motif 库的 <filename>Makefile</filename> 和 + <filename>Imakefile</filename> 改为使用这个变量。</para> + + <para>下面是两种常见的情形：</para> + + <itemizedlist> + <listitem> + <para>如果 port 在其 <filename>Makefile</filename> 或 + <filename>Imakefile</filename> 中以 <literal>-lXm</literal> + 的形式引用了 Motif 库， 简单地将其改为 + <literal>${MOTIFLIB}</literal> 即可。</para> + </listitem> + + <listitem> + <para>如果 port 在其 <filename>Imakefile</filename> 中使用了 + <literal>XmClientLibs</literal>， 则应将其改为 + <literal>${MOTIFLIB} ${XTOOLLIB} + ${XLIB}</literal>。</para> + </listitem> + + </itemizedlist> + + <para>注意 <makevar>MOTIFLIB</makevar> (通常情况下) 会展开成 + <literal>-L/usr/X11R6/lib -lXm</literal> 或 + <literal>/usr/X11R6/lib/libXm.a</literal>， 这样就不再需要在前面增加 + <literal>-L</literal> 或 <literal>-l</literal> 了。</para> + </sect1> + </chapter> + + <chapter id="x11-fonts"> + <title>X11 字体</title> + + <para>如果您的 port 需要向 X Window 系统安装字体， 应把它们放到 + <filename><makevar>X11BASE</makevar>/lib/X11/fonts/local</filename>。 + 这个目录是在 <application>XFree86 3.3.3</application> 中新增的。 + 如果它不存在， 则应建立一个， 并给出一条消息要求用户将 + <application>XFree86</application> 更新到 3.3.3 或更新版本， + 或者， 至少将这个目录加入到 <filename>/etc/XF86Config</filename> + 中的字体路径中。</para> + </chapter> + + <chapter id="porting-info"> + <title>Info 文件</title> + + <para>如果您的 package 需要安装 GNU info 文件， + 应把它们列在 <makevar>INFO</makevar> 变量中 (不需要指定 + <literal>.info</literal> 后缀)， 这样安装/卸载代码就会自动地在 package + 注册时加入到 <filename>pkg-plist</filename> 了。</para> + </chapter> + + <chapter id="pkg-files"> + <title><filename>pkg-<replaceable>*</replaceable></filename> 文件</title> + + <para>前面有一些没有提及的关于 + <filename>pkg-<replaceable>*</replaceable></filename> 文件的技巧， + 它们可以方便地完成许多任务。</para> + + <sect1 id="porting-message"> + <title><filename>pkg-message</filename> (安装预编译包时显示的消息文件)</title> + + <para>如果您需要在安装时显示一条消息给用户， + 可以把这消息放在 <filename>pkg-message</filename> 中。 + 这一特性通常可以用于在 &man.pkg.add.1; 之后显示一些附加的安装步骤， + 或显示关于授权的信息。</para> + + <note> + <para><filename>pkg-message</filename> 文件， + 并不需要明确地加到 <filename>pkg-plist</filename> 中。 + 此外， 在用户使用 port 而不是 package 来安装软件时， + 它并不会被显示出来。 因此如果需要的话， 您应该在 + <maketarget>post-install</maketarget> target 中指定显示它。</para> + </note> + </sect1> + + <sect1 id="pkg-install"> + <title><filename>pkg-install</filename> (安装预编译包时执行的脚本文件)</title> + + <para>如果您的 port 需要在预编译的安装包通过 &man.pkg.add.1; + 安装时执行一些命令， 则应通过 + <filename>pkg-install</filename> 脚本来完成。 + 这个脚本会自动地加入 package， 并被 + &man.pkg.add.1; 执行两次： 第一次是 + <literal>${SH} pkg-install ${PKGNAME} + PRE-INSTALL</literal> 而第二次是 + <literal>${SH} pkg-install ${PKGNAME} POST-INSTALL</literal>。 + <literal>$2</literal> 可被用来检测脚本运行的模式。 + 环境变量 <envar>PKG_PREFIX</envar> 将设置为 package 的安装目录。 + 请参见 &man.pkg.add.1; 以了解更进一步的细节。</para> + + <note> + <para>在使用 <command>make install</command> 时这个脚本不会被自动运行。 + 如果需要运行它， 则必须在您的 port 中的 + <filename>Makefile</filename> 里明确地予以调用， 其方法是加入类似 + <literal>PKG_PREFIX=${PREFIX} ${SH} ${PKGINSTALL} + ${PKGNAME} PRE-INSTALL</literal> 这样的命令。</para> + </note> + </sect1> + + <sect1 id="pkg-deinstall"> + <title><filename>pkg-deinstall</filename> (卸载时执行的脚本文件)</title> + + <para>这一脚本将在 package 被卸载时执行。</para> + + <para>此脚本会被 &man.pkg.delete.1; 执行两次。 + 第一次是 <literal>${SH} pkg-deinstall ${PKGNAME} + DEINSTALL</literal> 而第二次则是 + <literal>${SH} pkg-deinstall ${PKGNAME} POST-DEINSTALL</literal>。 + </para> + </sect1> + + <sect1 id="pkg-req"> + <title><filename>pkg-req</filename> (安装预编译包时检测是否应执行操作的脚本文件)</title> + + <para>如果您的 port 需要确定它是否应被安装， + 可以创建 <filename>pkg-req</filename> <quote>requirements</quote> + 脚本。 它会在安装/卸载时自动运行， 以决定操作是否应被实施。</para> + + <para>这个脚本会在使用 &man.pkg.add.1; 安装时以 + <literal>pkg-req ${PKGNAME} INSTALL</literal> 的命令行执行。 + 卸载时， 它将由 &man.pkg.delete.1; 以 + <literal>pkg-req ${PKGNAME} DEINSTALL</literal> 的命令行执行。</para> + </sect1> + + <sect1 id="porting-plist"> + <title>根据 make 变量改变 <filename>pkg-plist</filename></title> + + <para>某些 port， 特别是 <literal>p5-</literal> port， + 会需要根据配置选项 (或对于 <literal>p5-</literal> 而言， + <literal>perl</literal> 的版本) 来对它们的<filename>pkg-plist</filename> + 进行修改。 为方便起见， 在 + <filename>pkg-plist</filename> 中的 <literal>%%OSREL%%</literal>、 + <literal>%%PERL_VER%%</literal>， 以及 + <literal>%%PERL_VERSION%%</literal> 都会被适当地予以替换。 + 其中， <literal>%%OSREL%%</literal> 表示操作系统的数字形式的值 (例如 + <literal>4.9</literal>)。 <literal>%%PERL_VERSION%%</literal> + 则被替换为 <command>perl</command> 的完整版本号 (例如， + <literal>5.00502</literal>) 而 <literal>%%PERL_VER%%</literal> + 则表示 <command>perl</command> 版本号去掉 patchlevel + 的部分 (例如， <literal>5.005</literal>)。 许多其它的关于 + ports 的文档文件的 + <literal>%%<replaceable>VARS</replaceable>%%</literal> 的描述， + 在 <link + linkend="dads-documentation">相关小节</link> 中会分别介绍。</para> + + <para>如果您还需要进行其它的替换， 可以通过在 + <makevar>PLIST_SUB</makevar> 变量中设置一组 + <literal><replaceable>VAR</replaceable>=<replaceable>VALUE</replaceable></literal> + 来把 <filename>pkg-plist</filename> 中的 + <literal>%%<replaceable>VAR</replaceable>%%</literal> + 替换为 <replaceable>VALUE</replaceable>。</para> + + <para>举例来说， 如果您的 port 需要把很多文件放到和版本有关的目录中， + 可以在 <filename>Makefile</filename> 中按照类似下面的例子：</para> + + <programlisting>OCTAVE_VERSION= 2.0.13 +PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting> + + <para>来书写， 并把 <filename>pkg-plist</filename> 中的具体版本改为 + <literal>%%OCTAVE_VERSION%%</literal>。 这样， 在您升级 port 时， + 就不需要再到 <filename>pkg-plist</filename> 中修改那几十 (或者， + 某些情况下可能是数百) 行的内容了。</para> + + <para>这一替换 (以及加入 <link + linkend="porting-manpages">联机手册</link>) + 会在 <maketarget>pre-install</maketarget> 和 + <maketarget>do-install</maketarget> 两个 target 之间， 通过读取 + <filename><makevar>PLIST</makevar></filename> 并写入 + <filename><makevar>TMPPLIST</makevar></filename> 来完成 + (默认情况下， 是 + <filename><makevar>WRKDIR</makevar>/.PLIST.mktmp</filename>)。 + 如果您的 port 直接构建 <filename><makevar>PLIST</makevar></filename>， + 则应在 <maketarget>pre-install</maketarget> 或之前进行。 + 此外， 如果您的 port 需要编辑生成的最终文件， 应在 + <maketarget>post-install</maketarget> 中对 + <filename><makevar>TMPPLIST</makevar></filename> 进行操作。</para> + + <para>另一种可能是， 需要基于 <makevar>PLIST_FILES</makevar> 和 + <makevar>PLIST_DIRS</makevar> 变量配置来修改 port 的装箱单。 + 这两个变量的值会作为路径名写入到 <filename><makevar>TMPPLIST</makevar></filename> + 和 <filename><makevar>PLIST</makevar></filename>。 + 在 <makevar>PLIST_FILES</makevar> 和 <makevar>PLIST_DIRS</makevar> + 中列出的名字也会进行和前面介绍的方式相同的 + <literal>%%<replaceable>VAR</replaceable>%%</literal> + 替换。 初次之外， 在 <makevar>PLIST_FILES</makevar> + 中的路径名会不加修改地出现在最终的装箱单中， + 而 <literal>@dirrm</literal> 则会加入来自 <makevar>PLIST_DIRS</makevar> + 所预先指定的名字。 要达到效果， <makevar>PLIST_FILES</makevar> 和 + <makevar>PLIST_DIRS</makevar> 必须在写入 + <filename><makevar>TMPPLIST</makevar></filename> 之前进行设置， + 也就是 <maketarget>pre-install</maketarget> 或更早。</para> + </sect1> + + <sect1 id="pkg-names"> + <title id="porting-pkgfiles">改变 + <filename>pkg-<replaceable>*</replaceable></filename> 文件的名字</title> + + <para>所有 <filename>pkg-<replaceable>*</replaceable></filename> 文件的名字， + 皆系采用变量予以定义， 因此在需要时可以在您的 + <filename>Makefile</filename> 中加以改变。 当您需要在多个 port + 之间共享某些 <filename>pkg-<replaceable>*</replaceable></filename> 文件， + 或需要写入某些文件时就非常有用了。 (参见 在 + <link linkend="porting-wrkdir"> + <makevar>WRKDIR</makevar></link> 以外的地方写文件， + 以了解为什么直接将变更写入 <filename>pkg-<replaceable>*</replaceable></filename> + 子目录是个糟糕的主意)</para> + + <para>下面是一组变量以及它们的默认值 (<makevar>PKGDIR</makevar> 默认情况下是 + <makevar>${MASTERDIR}</makevar>。)</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>变量</entry> + <entry>默认值</entry> + </row> + </thead> + + <tbody> + <row> + <entry><makevar>DESCR</makevar></entry> + <entry><literal>${PKGDIR}/pkg-descr</literal></entry> + </row> + + <row> + <entry><makevar>PLIST</makevar></entry> + <entry><literal>${PKGDIR}/pkg-plist</literal></entry> + </row> + + <row> + <entry><makevar>PKGINSTALL</makevar></entry> + <entry><literal>${PKGDIR}/pkg-install</literal></entry> + </row> + + <row> + <entry><makevar>PKGDEINSTALL</makevar></entry> + <entry><literal>${PKGDIR}/pkg-deinstall</literal></entry> + </row> + + <row> + <entry><makevar>PKGREQ</makevar></entry> + <entry><literal>${PKGDIR}/pkg-req</literal></entry> + </row> + + <row> + <entry><makevar>PKGMESSAGE</makevar></entry> + <entry><literal>${PKGDIR}/pkg-message</literal></entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>请修改这些变量， 而不是直接覆盖 + <makevar>PKG_ARGS</makevar> 的值。 如果您改变了 + <makevar>PKG_ARGS</makevar>， 这些文件将无法在安装 port + 时正确地复制到 <filename>/var/db/pkg</filename> 目录。</para> + </sect1> + + <sect1 id="using-sub-files"> + <title>使用 <makevar>SUB_FILES</makevar> 和 + <makevar>SUB_LIST</makevar></title> + + <para><makevar>SUB_FILES</makevar> 和 <makevar>SUB_LIST</makevar> + 这两个变量可以用来在 port 文件中使用某些动态的值， 例如 + <filename>pkg-message</filename> 中的 + installation <makevar>PREFIX</makevar>。</para> + + <para>使用 <makevar>SUB_FILES</makevar> + 变量可以指定需要自动修改的文件列表。 在 + <makevar>SUB_FILES</makevar> 中的每一个 + <replaceable>file</replaceable>， 都必须有一个对应的、 + 存在于 <makevar>FILESDIR</makevar> 目录的 + <filename><replaceable>file</replaceable>.in</filename> 文件。 + 如果您加入了一些文件， 例如 + <filename>pkg-message</filename>、 <filename>pkg-install</filename>、 + <filename>pkg-deinstall</filename> 或 <filename>pkg-reg</filename>， 则相关的 + <makevar>PKG-<replaceable>FILE</replaceable></makevar> 变量就应设置为 + <filename><makevar>WRKDIR</makevar>/pkg-<replaceable>file</replaceable></filename>。</para> + + <para>用 <makevar>SUB_FILES</makevar> 变量， + 可以指定需要自动进行修改的文件列表。 在 + <makevar>SUB_FILES</makevar> 中的每一个 + <replaceable>文件</replaceable>， + 在 <makevar>FILESDIR</makevar> 目录中都必须有一个对应的 + <filename><replaceable>文件</replaceable>.in</filename>。 + 修改后的版本将保存在 <makevar>WRKDIR</makevar>。 + 在 <makevar>USE_RC_SUBR</makevar> 和 + <makevar>USE_RCORDER</makevar> 中定义的文件会自动加入到 + <makevar>SUB_FILES</makevar> 中。 对于 + <filename>pkg-message</filename>、 + <filename>pkg-install</filename>、 <filename>pkg-deinstall</filename> + and <filename>pkg-reg</filename>， 对应的 Makefile 变量会被自动设置， + 以指向处理过的版本。</para> + + <para><makevar>SUB_LIST</makevar> 这个变量的内容是一系列 + <literal>VAR=VALUE</literal> 对。 <makevar>SUB_FILES</makevar> + 所列出的文件中所有的 + <literal>%%VAR%%</literal> 都将被替换为 + <literal>VALUE</literal>。 系统自动定义了一些常用的替换对， + 包括： <makevar>PREFIX</makevar>、 + <makevar>LOCALBASE</makevar>、 <makevar>X11BASE</makevar>、 + <makevar>DATADIR</makevar>、 <makevar>DOCSDIR</makevar>， 以及 + <makevar>EXAMPLESDIR</makevar>。 替换结果中所有以 + <literal>@comment</literal> 开头的行， + 都将在变量替换之后被删去。</para> + + <para>下面的例子中， 将把 <filename>pkg-message</filename> + 中的 <literal>%%ARCH%%</literal> 替换为系统所运行的架构名称：</para> + + <programlisting>SUB_FILES= pkg-message +SUB_LIST= ARCH=${ARCH}</programlisting> + + <para>注意， 在上述例子中， <makevar>FILESDIR</makevar> + 里必须有 <filename>pkg-message.in</filename> 这个文件。</para> + + <para>下面是一个正确的 <filename>pkg-message.in</filename> 例子：</para> + + <programlisting>Now it's time to configure this package. +Copy %%PREFIX%%/share/examples/putsy/%%ARCH%%.conf into your home directory +as .putsy.conf and edit it.</programlisting> + + </sect1> + </chapter> + + <chapter id="testing"> + <title>测试您的 port</title> + + <sect1 id="make-describe"> + <title>运行 <command>make describe</command></title> + + <para>许多 &os; port 维护工具， 例如 + &man.portupgrade.1;， 会依赖于一个名为 + <filename>/usr/ports/INDEX</filename> 的数据库的正确性， + 它提供了关于 port 的相关信息， 例如依赖关系等等。 + <filename>INDEX</filename> 是由顶级的 + <filename>ports/Makefile</filename> 通过 + <command>make index</command> 来建立的， 这个命令会进入每一个 port + 的子目录， 并在那里执行 <command>make describe</command>。 + 因此， 如果某个 port 的 <command>make describe</command> 失败， + 就没有人能生成 <filename>INDEX</filename>， + 人们很快会变得不高兴。</para> + + <note> + <para>无论在 <filename>make.conf</filename> 中设置了什么选项， + 这个文件都应能够正确地生成。 因此， + 应避免在 (例如) 某个依赖关系无法满足时使用 <literal>.error</literal>。</para> + </note> + + <example id="dot-error-breaks-index"> + <title>如何避免使用 <literal>.error</literal></title> + <para>考虑有人在 <filename>make.conf</filename> 中设置了 + <programlisting>USE_POINTYHAT=yes</programlisting> 的情形。 + 下面的例子中， 第一个 <filename>Makefile</filename> + 将导致 <command>make index</command> 失败， 而第二个不会：</para> + <programlisting>.if USE_POINTYHAT +.error "POINTYHAT is not supported" +.endif</programlisting> + <programlisting>.if USE_POINTYHAT +IGNORE=POINTYHAT is not supported +.endif</programlisting> + </example> + + <para>如果 <command>make describe</command> 只是产生一个字符串， + 而不是错误信息， 可能就没什么问题。 请参见 + <filename>bsd.port.mk</filename> 以了解所生成的串的意义。</para> + + <para>最后要说明的是， 新版本的 + <command>portlint</command> (在下一节中将进行介绍) + 将会自动地运行 <command>make describe</command>。</para> + </sect1> + + <sect1 id="testing-portlint"> + <title>Portlint</title> + + <para>在提交或 commit 之前， 应使用 <link + linkend="porting-portlint"><command>portlint</command></link> + 来进行检查。 <command>portlint</command> 会对常见的、 + 包括功能上的和格式上的错误给出警告。 对于新的 (或在 repocopy 代码库中复制的) + port， <command>portlint -A</command> 可以完成全面检查； + 对于暨存的 port， <command>portlint -C</command> 一般就足够了。</para> + + <para>由于 <command>portlint</command> 采用启发式方法来检查错误， + 有时它会产生误警。 另外， 有时由于 port + 框架的限制可能没有办法修正它指出的问题。 如果您有疑虑， + 请写信询问 &a.ports;。</para> + </sect1> + + <sect1 id="porting-prefix"> + <title><makevar>PREFIX</makevar> (安装时的顶级目录名)</title> + + <para>尽可能让 port 安装到 + <makevar>PREFIX</makevar> 之下的目录。 (一般情况下， + 这个变量的值是 <makevar>LOCALBASE</makevar> (默认为 + <filename>/usr/local</filename>)。 如果设置了 + <makevar>USE_X_PREFIX</makevar> 或 <makevar>USE_IMAKE</makevar>， + 则 <makevar>PREFIX</makevar> 将是 <makevar>X11BASE</makevar> (默认为 + <filename>/usr/X11R6</filename>)。 如果设置了 + <makevar>USE_LINUX_PREFIX</makevar>， <makevar>PREFIX</makevar> + 将是 <makevar>LINUXBASE</makevar> (默认为 + <filename>/compat/linux</filename>)。</para> + + <para>避免在源代码中的任何地方硬编码 <filename>/usr/local</filename> 或 + <filename>/usr/X11R6</filename> 这样的路径， 这会让您的 + port 灵活许多， 而且能够适应大型站点的需求。 + 对于使用了 <command>imake</command> 的 X port 而言， + 这是自动的； 对于其他 port， + 这通常可以通过把在 脚本/<filename>Makefile</filename> + 中出现的 <filename>/usr/local</filename> (或对于不使用 imake 的 X port， + <filename>/usr/X11R6</filename>) 改为使用 + <makevar>${PREFIX}</makevar> 来完成， + 因为这个变量会传达到构建和安装的各个步骤。</para> + + <para>确认一下您的应用程序不会错误地把文件安装到 + <filename>/usr/local</filename> 而非 <makevar>PREFIX</makevar>。 + 简单的测试步骤是：</para> + + <screen>&prompt.root; <userinput>make clean; make package PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput></screen> + + <para>如果有文件安装到了 <makevar>PREFIX</makevar> 以外的地方， + 打包过程将抱怨找不到这些文件。</para> + + <!-- XXX This paragraph is confusing and poorly indented. --> + <para>这一步骤并不能帮助发现内部引用， 或纠正在引用其它 port + 中的文件时使用的 <makevar>LOCALBASE</makevar>。 您需要在 + <filename>/var/tmp/<replaceable>port-name</replaceable></filename> + 中测试安装好的软件， 才能够达到这样的目的。</para> + + <para>除非真的需要， 否则不要设置 <makevar>USE_X_PREFIX</makevar> + (例如， 如果它需要连接或引用 <makevar>X11BASE</makevar> 中的 X + 库或文件)。</para> + + <para>您可以在自己的 <filename>Makefile</filename> 中改变 + <makevar>PREFIX</makevar> 变量的值， 也可以通过用户环境变量来影响它。 + 然而， 一般情况下决不应该在 <filename>Makefile</filename> + 中明确设置它的值。</para> + + <para>此外， 引用其它 port 中的文件时， 应使用前面介绍的变量， + 而不要直接指定它们的路径名。 例如， 如果您的 port + 需要使用 <literal>PAGER</literal> 这个宏来指明 + <command>less</command> 的完整路径， 应使用下面的编译选项： + + <programlisting>-DPAGER=\"${LOCALBASE}/bin/less\"</programlisting> + + 而非 + <literal>-DPAGER=\"/usr/local/bin/less\"</literal>。 + 这种方法能够增加在系统管理员把整个 <filename>/usr/local</filename> + 目录挪到其他位置时安装成功的机会。</para> + </sect1> + </chapter> + + <chapter id="port-upgrading"> + <title>升级</title> + + <para>如果您发现某个 port 相对原作者所发布的版本已经过时， + 则首先需要确认的是您的 port 是最新的。 您可以在 &os; FTP 镜像的 + <filename>ports/ports-current</filename> 目录中找到它们。 + 但是， 如果您正在使用较多的 port， 则可能使用 + <application>CVSup</application> 来保持 Ports Collection 最新更为简单， 这在 + <ulink url="&url.books.handbook;/synching.html#CVSUP-CONFIG">使用手册</ulink> + 中进行了介绍。 此外， 这样做也有助于保持 port 依赖关系的正确性。</para> + + <para>下一步是检查是否已经有在等待的更新。 要完成这项工作， + 可以采用下列两种方法之一。 有一个用于搜索 + <ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"> + FreeBSD 问题报告 (PR) 数据库</ulink> (也被称作 + <literal>GNATS</literal>)。 在下拉框中选择 <literal>ports</literal>， + 然后输入 port 的名字。</para> + + <para>但是， 有些时候人们会忘记将避免混淆的 port 的名字放到 Synopsis 字段中。 + 这种时候， 您可以试试看 <link linkend="portsmon"> + FreeBSD Ports 监视系统</link> (也被叫做 + <literal>portsmon</literal>)。 这个系统会尝试按照 port 的名字来进行分类。 + 要搜索和某个特定 port 有关的 PR， 可以使用 <ulink + url="http://portsmon.firepipe.net/portoverview.py"> + port概览</ulink>。</para> + + <para>如果没有候审的 PR， 下一步是给 port 的维护者写信， 这可以通过执行 + <command>make maintainer</command> 看到。 这个人可能正在进行升级工作， + 或者由于某种理由暂时没有升级 (例如， 新版本有稳定性问题)； + 一般您不希望重复他们的工作。 注意没有维护者的 port 的维护者会显示为 + <literal>ports@FreeBSD.org</literal>， 这是一般性 port 问题的邮件列表， + 因此发邮件给它一般没什么意义。</para> + + <para>如果维护者要求您去完成升级， 或者没有维护者， + 您就可以通过自行完成升级来帮助 &os; 了！ 请进行修改， + 并保存在新旧目录上执行的递归式 <command>diff</command> 的输出 (例如， + 如果您修改的 port 的目录名是 <filename>superedit</filename> + 而修改前的目录的名字是 <filename>superedit.bak</filename>， 则应提交的是 + <command>diff -ruN superedit.bak superedit</command> 的结果)。 + 一致式 (unified) 或 上下文式 (context) diff 都是可以的， + 但一般来说 port committer 会更喜欢一致式 diff。 + 请注意这里使用的选项 <literal>-N</literal>， 它的目的是强制 diff + 正确地处理出现新文件， 或老文件被删除的情形。 在把 diff 发给我们之前， + 请再次检查输出， 以便确认每一个修改都是有意义的。 + 为了简化常用的补丁文件操作， 您可以使用 + <filename>/usr/ports/Tools/scripts/patchtool.py</filename>。 + 使用之前， 请首先阅读 + <filename>/usr/ports/Tools/scripts/README.patchtool</filename>。</para> + + <para>如果 port 目前还无人维护， 而且您自己经常使用它， + 请考虑自荐为它的维护者。 &os; 有超过 2000 个没有维护者的 port， + 而这正是最需要志愿人员的领域。 + (要了解关于维护者的任务描述， 请参见 + <ulink url="&url.books.developers-handbook;/policies.html#POLICIES-MAINTAINER"> + Makefile 中的 MAINTAINER</ulink> 小节)。</para> + + <para>将 diff 发送给我们的最佳方式是通过 &man.send-pr.1; (category 一栏写 + <literal>ports</literal>)。 如果您是维护那个 port 的志愿者， + 请务必在 synopsis 的开头写上 <literal>[maintainer update]</literal>， + 并将您的 PR 的 <quote>Class</quote> 设置为 <literal>maintainer-update</literal>。 + 反之， 您的 PR 的 <quote>Class</quote> 就应该是 + <literal>change-request</literal>。 请在信中逐个提及每一个删除或增加的文件， + 因为这些都必须明确地在使用 &man.cvs.1; 进行 commit 时明确地指定。 + 如果 diff 超过了 20K， 请考虑压缩并对其进行 uuencode； + 否则， 简单地将其原样加入 PR 即可。</para> + + <para>在您 &man.send-pr.1; 之前， 请再次阅读 Problem + Reports 一文中的 + <ulink url="&url.articles.problem-reports;/pr-writing.html"> + 如何撰写问题报告</ulink> 小节； + 它给出了丰富的关于如何撰写更好的问题报告的介绍。</para> + + <important> + <para>如果您的更新是由于安全考虑， 或修复已经 commit 的 port + 中的严重问题， 请通知 &a.portmgr; 来申请立即重建和分发您的 port + 的 package。 否则， 不愿怀疑的使用 &man.pkg.add.1; 的用户， + 可能会在未来数周之内继续通过使用 <command>pkg_add -r</command> + 安装旧版本。</para> + </important> + + <note> + <para>再次强调， 请使用 &man.diff.1; 而非 &man.shar.1; 来发送现有 port 的更新！</para> + </note> + + <para>现在您已经了解了所需的所有操作， 您可能会像要阅读在 + <xref linkend="keeping-up"> 中关于如何保持最新的描述。</para> + + </chapter> + + <chapter id="security"> + <title>Ports 的安全</title> + + <sect1 id="security-intro"> + <title>安全为何如此重要</title> + + <para>软件中偶尔会引入 bug。 毋庸置疑， 安全漏洞是最为危险的。 + 从技术角度看， 这些漏洞可以通过消除导致它们的 bug 来修复。 + 然而， 处理一般的 bug 和安全漏洞的策略是截然不同的。</para> + + <para>典型的小 bug 通常只影响那些启用了某些能够触发它的选项组合的用户。 + 开发人员最终会在发布没有那个问题的新版之后给出一个补丁来修正它， + 而用户中的主体并不会立即升级， 因为他们并没有因存在问题而感到苦恼。 + 严重的 bug 可能会导致数据丢失和其他问题， 无论如何， + 谨慎的用户知道， 除了软件 bug 之外还有很多其他事故可能会导致数据丢失， + 因此他们会备份重要数据； 此外， 严重的 bug 通常会被很快发现。</para> + + <para>安全漏洞则完全不同。 第一， 它们可能存在数年而不被发现， + 因为它们可能并不导致软件无法正常工作。 第二， 通过利用漏洞， + 恶意的一方可能会得到未获授权的访问权限， + 并利用这些权限毁掉或修改敏感数据； + 而更糟糕的情况则是用户可能根本注意不到损害已经发生。 第三， + 暴露出安全漏洞的系统， 往往能够帮助攻击者闯入其他之前不可能进入的系统。 + 因此， 只是修正安全漏洞是不够的： 必须以清晰和全面的方式通知公众， + 这样他们就能够评估风险， 并采取适当的措施。</para> + </sect1> + + <sect1 id="security-fix"> + <title>修复安全漏洞</title> + + <para>当说起 port 或 package 时， 安全漏洞往往是出现在原作者的发行包， + 或移植过程中加入的文件里。 对于前一种情况， + 软件的原作者通常会立刻发布一个补丁甚至新版， + 您只需要按照原作者的修正去更新 port 就可以了。 + 如果由于某种原因修正被延误， 则要么 <link linkend="dads-noinstall">将 + port 标记为 <makevar>FORBIDDEN</makevar></link>， 要么在 port + 中加入一个自己的补丁。 如果有存在漏洞的 port， 尽可能尽快修复其漏洞就是。 + 无论是哪种情况， 您还是需要按照 <link + linkend="port-upgrading">标准的提交流程</link> 提交， + 除非您有直接在 ports tree 上 commit 的权限。</para> + + <important> + <para>作为 ports committer 并不能够随便 commit 所有 port。 + 请注意通常 port 都有维护者， 而他们应得到您的尊重。</para> + </important> + + <para>在漏洞被修正之后， 一定要同时增加 port 的修订版本号。 + 这样， 规律性地升级安装的 package 的用户就能够看到他们需要进行升级。 + 另外， 还应构建预编译的安装包， 并通过 FTP 和 WWW 镜像发布， + 以取代有漏洞的版本。 注意要增加 + <makevar>PORTREVISION</makevar> 数字， 除非在修正问题时 + <makevar>PORTVERSION</makevar> 发生了变化。 一般来说， + 如果在 port 中增加了补丁文件， 就应该增加 <makevar>PORTREVISION</makevar>， + 但例外的例子是您已经将软件升级到了最新版， + 因为这时已经改掉 <makevar>PORTVERSION</makevar> 了。 请参见 + <link linkend="makefile-naming-revepoch">相关小节</link> + 以了解进一步的信息。</para> + </sect1> + + <sect1 id="security-notify"> + <title>通知整个用户群体</title> + + <sect2 id="security-notify-vuxml-db"> + <title>VuXML 数据库</title> + + <para>当发现了安全漏洞时的一项重要而紧迫的步骤， + 就是让使用 port 的用户群了解其危险。 这类通知有两重目的。 + 首先， 如果危害真的很严重， 可能理性的办法就是立即应用一项缓解措施， + 例如， 停止受到影响的服务， 甚至完全删除 port， 直到问题被修正为止。 + 其次， 许多用户只是偶尔升级所安装的软件包， 通过通知， + 他们能够知道已经到了 <emphasis>必须</emphasis> 更新软件的时候， + 因为已经有了修正这些问题的版本了。</para> + + <para>由于现有的 port 数量极其庞大， 为每一个问题都发布安全公告， + 毫无疑问地会发表和狼来了一样多的安全公告， + 并增大受众在真的发生严重的问题时忽略问题的可能。 + 因此， 在 port 中发现的安全漏洞， 会在 <ulink + url="http://vuxml.freebsd.org/">FreeBSD VuXML + 数据库</ulink> 中记录。 安全官团队成员会持续地追踪这个数据库的修改， + 以了解需要他们注意的内容。</para> + + <para>如果您是 committer， 则可以自行更新 VuXML 数据库。 + 这样， 您就能够同时帮助安全官团队， + 并尽早将至关重要的信息传达给用户群体。 然而， 如果您不是 committer， + 或者您相信自己发现了一个异常严重的漏洞， 或者由于其他情况， + 请不要由于按照 <ulink + url="http://www.freebsd.org/zh_CN/security/#how">FreeBSD + 安全信息</ulink> 页面上的方法联系安全官团队。</para> + + <para>现在您选择了一条艰难的路。 正如其名称所暗示的那样， VuXML + 数据库本质上是一个 XML 文档。 其源文件 <filename>vuln.xml</filename> + 被保存在 <filename + role="package">security/vuxml</filename> port 的目录中。 + 所以， 它的全名是 + <filename><envar>PORTSDIR</envar>/security/vuxml/vuln.xml</filename>。 + 每当您发现 port 中的安全漏洞时， 请把新的纪录加入到那个文件中。 + 在熟悉 VuXML 之前， 您最好先看看是否有类似的您发现的问题的其他记录， + 并复制它作为模板。</para> + </sect2> + + <sect2 id="security-notify-vuxml-intro"> + <title>VuXML 简介</title> + + <para>XML 是一个复杂的语言， 它远远超越了这本书的范围。 + 不过， 只需了解标记的命名规则， 就能 VuXML 记录的结构有一个大体的了解了。 + XML 标记的名字应出现在一对尖括号之间。 每一个 + <tag> 必须有一个对应的 </tag>。 标记可以嵌套， + 如果嵌套的话， 内层的标记必须在外层标记之前结束。 + 这就形成了一个标记的层次结构， 也就是关于它们之间如何嵌套的规则。 + 听起来很像 HTML， 是不是？ 最主要的区别在于， XML + 是可扩展的 (e<emphasis>X</emphasis>tensible)， + 例如通过定义新的标记等等。 由于其结构的内在性质， + XML 能够赋予无组织的数据新的形态。 VuXML 是专门为描述安全漏洞设计的语言。</para> + + <para>现在让我们来观察一个实际的 VuXML 记录：</para> + + <programlisting><vuln vid="f4bc80f4-da62-11d8-90ea-0004ac98a7b9"> <co id="co-vx-vid"> + <topic>Several vulnerabilities found in Foo</topic> <co id="co-vx-top"> + <affects> + <package> + <name>foo</name> <co id="co-vx-nam"> + <name>foo-devel</name> + <name>ja-foo</name> + <range><ge>1.6</ge><lt>1.9</lt></range> <co id="co-vx-rng"> + <range><ge>2.*</ge><lt>2.4_1</lt></range> + <range><eq>3.0b1</eq></range> + </package> + <package> + <name>openfoo</name> <co id="co-vx-nm2"> + <range><lt>1.10_7</lt></range> <co id="co-vx-epo"> + <range><ge>1.2,1</ge><lt>1.3_1,1</lt></range> + </package> + </affects> + <description> + <body xmlns="http://www.w3.org/1999/xhtml"> + <p>J. Random Hacker reports:</p> <co id="co-vx-bdy"> + <blockquote + cite="http://j.r.hacker.com/advisories/1"> + <p>Several issues in the Foo software may be exploited + via carefully crafted QUUX requests. These requests will + permit the injection of Bar code, mumble theft, and the + readability of the Foo administrator account.</p> + </blockquote> + </body> + </description> + <references> <co id="co-vx-ref"> + <freebsdsa>SA-10:75.foo</freebsdsa> <co id="co-vx-fsa"> + <freebsdpr>ports/987654</freebsdpr> <co id="co-vx-fpr"> + <cvename>CAN-2010-0201</cvename> <co id="co-vx-cve"> + <cvename>CAN-2010-0466</cvename> + <bid>96298</bid> <co id="co-vx-bid"> + <certsa>CA-2010-99</certsa> <co id="co-vx-cts"> + <certvu>740169</certvu> <co id="co-vx-ctv"> + <uscertsa>SA10-99A</uscertsa> <co id="co-vx-ucs"> + <uscertta>SA10-99A</uscertta> <co id="co-vx-uct"> + <mlist msgid="201075606@hacker.com">http://marc.theaimsgroup.com/?l=bugtraq&amp;m=203886607825605</mlist> <co id="co-vx-mls"> + <url>http://j.r.hacker.com/advisories/1</url> <co id="co-vx-url"> + </references> + <dates> + <discovery>2010-05-25</discovery> <co id="co-vx-dsc"> + <entry>2010-07-13</entry> <co id="co-vx-ent"> + <modified>2010-09-17</entry> <co id="co-vx-mod"> + </dates> +</vuln></programlisting> + + <para>标记的名字都是简单明了的， 下面我们来介绍一下需要由您填写的字段：</para> + + <calloutlist> + <callout arearefs="co-vx-vid"> + <para>这是 VuXML 记录的顶级 tag。 + 它有一个强制性的字段， <literal>vid</literal>， + 用于为此记录 (它包含的部分) 指定一个全局唯一标识符 (UUID)。 + 您应为每一个新的 vuXML 生成新的 UUID (而且别忘了要把模板中的 + UUID 换成新的， 如果您不是从头开始的话)。 在 FreeBSD 5.x + 和更高版本中， 可以使用 &man.uuidgen.1;。此外也可以用 <filename + role="package">devel/p5-Data-UUID</filename> 并执行：</para> + + <programlisting>perl -MData::UUID -le 'print lc new Data::UUID->create_str'</programlisting> + </callout> + + <callout arearefs="co-vx-top"> + <para>关于问题的一句话描述。</para> + </callout> + + <callout arearefs="co-vx-nam"> + <para>此处给出受到影响的 package 的名字。 可以给出多个名字， + 因为可能有多个软件包基于同一个 master port 或软件产品。 + 这可能包括稳定和开发分支、 本地化版本， + 以及提供了不同的编译时选项的 slave port。</para> + + <important> + <para>撰写 VuXML 记录时， 您有责任找到所有相关的包。 很多时候 + <literal>make search name=foo</literal> 是您的朋友。 + 需要留意的通常包括：</para> + + <itemizedlist> + <listitem> + <para><filename>foo</filename> port 的 + <filename>foo-devel</filename> 变体；</para> + </listitem> + + <listitem> + <para>包含不同后缀的其他变体， 例如 + <literal>-a4</literal> (对于和打印有关的软件包)， + <literal>-without-gui</literal> (提供但禁用了 X + 支持的软件包)， 以及类似的其他情况；</para> + </listitem> + + <listitem> + <para><literal>jp-</literal>， <literal>ru-</literal>、 + <literal>zh-</literal>， 以及其他可能的本地化变体， + 它们通常可以在 Ports Collection 中相应的国家分类中找到。</para> + </listitem> + </itemizedlist> + </important> + </callout> + + <callout arearefs="co-vx-rng"> + <para>受影响的 package 版本， 可以使用 + <literal><lt></literal>, <literal><le></literal>, + <literal><eq></literal>, <literal><ge></literal>, + 和 <literal><gt></literal> 表达成一个或多个版本及其范围。 + 注意给出的版本范围不应存在重叠。</para> + + <para>在描述范围的时候， <literal>*</literal> (星号) + 表达最小的版本。 更具体地说， + <literal>2.*</literal> 小于 <literal>2.a</literal>。 + 因此， 星号可以用来匹配所有可能的 + <literal>alpha</literal>、 <literal>beta</literal>， + 以及 <literal>RC</literal> 版本。 例如， + <literal><ge>2.*</ge><lt>3.*</lt></literal> + 可以选择性地匹配每一个 <literal>2.x</literal> 的版本， 而 + <literal><ge>2.0</ge><lt>3.0</lt></literal> + 显然不能， 因为它会漏掉 + <literal>2.r3</literal> 而匹配 + <literal>3.b</literal>。</para> + + <para>上面的例子指定了受影响的版本， 是包括 <literal>1.6</literal> + 到 <literal>1.9</literal> 上下界的所有版本， 以及 + <literal>2.x</literal> 在 <literal>2.4_1</literal> 之前的版本， + 和 <literal>3.0b1</literal> 版。</para> + </callout> + + <callout arearefs="co-vx-nm2"> + <para>受到影响的一组 package (本质上是 ports) + 可以列在 <literal><affected></literal> 小节中。 + 如果多个软件产品都采用了同样的基础代码， + (比如说 FooBar、 FreeBar 和 OpenBar) 而且包含同样的 bug + 或漏洞。 请注意列出多个名字时， 应该在一个 + <package> 小节中完成。</para> + </callout> + + <callout arearefs="co-vx-epo"> + <para>如果可能， 版本的范围应包括 + <makevar>PORTEPOCH</makevar> 和 + <makevar>PORTREVISION</makevar>。 + 务必注意， 根据加权规则， 带有非零 <makevar>PORTEPOCH</makevar> + 的版本， 系统会认为比没有 + <makevar>PORTEPOCH</makevar> 的版本高， 例如 <literal>3.0,1</literal> + 高于 <literal>3.1</literal> 甚至 + <literal>8.9</literal>。</para> + </callout> + + <callout arearefs="co-vx-bdy"> + <para>关于问题的摘要性信息。 此处使用 + XHTML。 务必要成对使用 + <literal><p></literal> 和 <literal></p></literal>。 + 可以使用较为复杂的标记， 但仅限于有助于让信息更准确和明了的修饰： + 请不要过分地美化。</para> + </callout> + + <callout arearefs="co-vx-ref"> + <para>这部分包含了相关的可供参考的文档。 + 请尽可能多提供参考文献。</para> + </callout> + + <callout arearefs="co-vx-fsa"> + <para>指定 + <ulink url="http://www.freebsd.org/security/#adv">FreeBSD + 安全公告</ulink>。</para> + </callout> + + <callout arearefs="co-vx-fpr"> + <para>指定 + <ulink url="http://www.freebsd.org/support.html#gnats">FreeBSD + 问题报告</ulink>。</para> + </callout> + + <callout arearefs="co-vx-cve"> + <para>指定 <ulink url="http://www.cve.mitre.org/">Mitre + CVE</ulink> ID。</para> + </callout> + + <callout arearefs="co-vx-bid"> + <para>指定 + <ulink url="http://www.securityfocus.com/bid">SecurityFocus + Bug ID</ulink>。</para> + </callout> + + <callout arearefs="co-vx-cts"> + <para>指定 + <ulink url="http://www.cert.org/">US-CERT</ulink> + 安全公告。</para> + </callout> + + <callout arearefs="co-vx-ctv"> + <para>指定 + <ulink url="http://www.cert.org/">US-CERT</ulink> + 漏洞说明。</para> + </callout> + + <callout arearefs="co-vx-ucs"> + <para>指定 + <ulink url="http://www.cert.org/">US-CERT</ulink> + 计算机安全警报。</para> + </callout> + + <callout arearefs="co-vx-uct"> + <para>指定 + <ulink url="http://www.cert.org/">US-CERT</ulink> + 技术性计算机安全警报。</para> + </callout> + + <callout arearefs="co-vx-mls"> + <para>指向邮件列表存档的 URL。 + 属性 <literal>msgid</literal> 是可选项， + 用以指定某一封信的 message ID。</para> + </callout> + + <callout arearefs="co-vx-url"> + <para>一般的 URL。 只有在没有其他更适合的参考文献时， + 才应使用它。</para> + </callout> + + <callout arearefs="co-vx-dsc"> + <para>问题被全面披露的日期 + (<replaceable>YYYY-MM-DD</replaceable>)。</para> + </callout> + + <callout arearefs="co-vx-ent"> + <para>记录加入到数据库中的日期 + (<replaceable>YYYY-MM-DD</replaceable>)。</para> + </callout> + + <callout arearefs="co-vx-mod"> + <para>记录最后一次被修改的日期 + (<replaceable>YYYY-MM-DD</replaceable>)。 新记录不应包括这个字段。 + 只有在修改记录时才应加入它。</para> + </callout> + </calloutlist> + </sect2> + + <sect2 id="security-notify-vuxml-testing"> + <title>测试您对 VuXML 数据库所作的修改</title> + + <para>假定您打算撰写， 或已经写好了一个关于 + package <literal>clamav</literal> 的问题描述， 并且， + 已经知道 <literal>0.65_7</literal> 版本修正了这个问题。</para> + + <para>您需要做的准备工作， 是安装一个新版本的 + ports <filename role="package">security/portaudit</filename> 程序以及 + <filename role="package">security/portaudit-db</filename>。</para> + + <para>首先， 检查一下是否已经有了关于这个漏洞的描述。 + 如果已经有过这样的记录， 那么它将匹配较早版本的 package， + <literal>0.65_6</literal>：</para> + + <screen>&prompt.user; <userinput>packaudit</userinput> +&prompt.user; <userinput>portaudit clamav-0.65_6</userinput></screen> + + <note> + <para>要运行 <command>packaudit</command>， 您必须拥有写入 + <filename><makevar>DATABASEDIR</makevar></filename> 目录， + 通常是 <filename>/var/db/portaudit</filename> 的权限。</para> + </note> + + <para>如果什么都没有发现， 您就可以考虑写一个新的记录来描述这个漏洞了。 + 现在可以生成一个新的 UUID (假设它是 + <literal>74a9541d-5d6c-11d8-80e3-0020ed76ef5a</literal>)， + 然后将您的新记录加入到 VuXML 数据库中。 接下来， + 用下面的命令来检查它是否符合语法：</para> + + <screen>&prompt.user; <userinput>cd ${PORTSDIR}/security/vuxml && make validate</userinput></screen> + + <note> + <para>您需要安装下列 package 中的至少一个： + <filename role="package">textproc/libxml2</filename>、 + <filename role="package">textproc/jade</filename>。</para> + </note> + + <para>接下来从 VuXML 文件重构 <command>portaudit</command> 数据库：</para> + + <screen>&prompt.user; <userinput>packaudit</userinput></screen> + + <para>要验证您新加入的项的 <literal><affected></literal> + 小节能够正确地匹配希望的 package， 可以使用下面的命令：</para> + + <screen>&prompt.user; <userinput>portaudit -f /usr/ports/INDEX -r 74a9541d-5d6c-11d8-80e3-0020ed76ef5a</userinput></screen> + + <note> + <para>请参见 &man.portaudit.1; 以了解关于这个命令语法的更多细节。</para> + </note> + + <para>请确信新添加的记录不会在输出中匹配不应匹配的项。</para> + + <para>现在检查您添加的记录所匹配的版本是否正确：</para> + + <screen>&prompt.user; <userinput>portaudit clamav-0.65_6 clamav-0.65_7</userinput> +Affected package: clamav-0.65_6 (matched by clamav<0.65_7) +Type of problem: clamav remote denial-of-service. +Reference: <http://www.freebsd.org/ports/portaudit/74a9541d-5d6c-11d8-80e3-0020ed76ef5a.html> + +1 problem(s) found.</screen> + + <para>显然， 前一个版本会匹配， 而后一个不会。</para> + + <para>最后， 验证您从 + VuXML 数据库中能够正确地得到预期的网页效果：</para> + + <screen>&prompt.user; <userinput>mkdir -p ~/public_html/portaudit</userinput> +&prompt.user; <userinput>packaudit</userinput> +&prompt.user; <userinput>lynx ~/public_html/portaudit/74a9541d-5d6c-11d8-80e3-0020ed76ef5a.html</userinput></screen> + </sect2> + + <sect2 id="security-notify-noxml"> + <title>假如 VuXML 仍然让您感到恐惧……</title> + + <para>除了撰写 VuXML 之外， 另一种简单的方法， + 就是用简单的多的语法的单行描述， 加入到 + <filename><envar>PORTSDIR</envar>/security/portaudit-db/database/portaudit.txt</filename> + 中。 这个文件是 port <filename + role="package">security/portaudit-db</filename> 的一部分， + 随后， 按照在 <ulink + url="http://www.freebsd.org/security/#how">FreeBSD + 安全信息</ulink> 网页中介绍的方法， + 发一个要求安全官团队进行复审的请求。</para> + + <para>这个文件中的每一行包括四个字段， + 中间使用 <literal>|</literal>， 即管道符分隔。 + 第一个字段是用来匹配可能存在问题的 package 的 &man.pkg.version.1; + 模式。 第二个字段是相关信息的 URL， 中间使用空格分开。 + 第三个字段是对于问题的一句话描述。 第四个字段， + 则是这个项的 UUID。</para> + + <para>您可以参考已经写入 + <filename>portaudit.txt</filename> 的记录， + 并按照类似的格式来撰写新项目。</para> + </sect2> + </sect1> + </chapter> + + <chapter id="porting-dads"> + <title>该做什么和不该做什么</title> + + <sect1 id="dads-intro"> + <title>介绍</title> + + <para>这里是一些在移植软件时可能会遇到的常见问题。 + 您应按照这个列表检查自己的 port， 同样地， + 您也可以帮助检查 <ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">PR 数据库</ulink> + 中由其他人提交的 port。 请按照在 + <ulink url="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL" + >问题报告和一般性注释</ulink> 中介绍的方法提交您的看法。 + 帮助检查 PR 数据库中的 ports 即能够帮助我们更快地 commit 它们， + 也能证明您清楚地了解如何完成这些工作。</para> + </sect1> + + <sect1 id="dads-strip"> + <title>对可执行文件做脱模 (strip) 操作</title> + + <para>除非不得不进行， 否则不要对可执行文件作脱模操作。 + 所有文件在安装时都应脱模， 但 <maketarget>INSTALL_PROGRAM</maketarget> + 宏会在安装的同时对其进行脱模 (参见下一节的内容)。</para> + + <para>如果您需要对某一文件进行脱模， 但不希望使用 + <makevar>INSTALL_PROGRAM</makevar> 宏， 则应使用 + <makevar>${STRIP_CMD}</makevar> 来处理程序。 + 一般而言这应该在 <literal>post-install</literal> + target 中进行。 例如：</para> + + <programlisting>post-install: + ${STRIP_CMD} ${PREFIX}/bin/xdl</programlisting> + + <para>可以使用 &man.file.1; 命令来检查所安装的可执行文件是否进行过脱模。 + 如果它没有给出 <literal>not stripped</literal> 的提示， + 则表示已经做过脱模了。 另外， + &man.strip.1; 不会对已经脱模过的文件重新脱模， 它会直接退出的。</para> + </sect1> + + <sect1 id="dads-install"> + <title>INSTALL_* 宏</title> + + <para>您应使用由 <filename>bsd.port.mk</filename> 提供的宏来完成操作， + 以确保您自己的 <maketarget>*-install</maketarget> target + 能够正确地设置属主和权限信息。</para> + + <itemizedlist> + <listitem> + <para><makevar>INSTALL_PROGRAM</makevar> 代表用于安装二进制的可执行文件的命令。</para> + </listitem> + + <listitem> + <para><makevar>INSTALL_SCRIPT</makevar> 代表用于安装可执行脚本的命令。</para> + </listitem> + + <listitem> + <para><makevar>INSTALL_DATA</makevar> 代表用于安装普通用户可访问的数据的命令。</para> + </listitem> + + <listitem> + <para><makevar>INSTALL_MAN</makevar> 代表用于安装联机手册， + 以及其他文档的命令 (注意， 它并不会对这些文件实施压缩操作)。</para> + </listitem> + </itemizedlist> + + <para>这些宏基本上就是给出了适当参数的 <command>install</command> 命令。 + 下面给出了如何使用它们的例子。</para> + </sect1> + + <sect1 id="porting-wrkdir"> + <title><makevar>WRKDIR</makevar> (构建时使用的临时目录)</title> + + <para>任何时候都不要在 + <makevar>WRKDIR</makevar> 以外的位置写文件。 <makevar>WRKDIR</makevar> + 是在 port 构建过程中唯一的一处一定可写的地方 (参见 + <ulink url="&url.books.handbook;/ports-using.html#PORTS-CD">如何从 + CDROM 安装 port</ulink> 以了解从只读的目录中构建和安装 port 的例子)。 + 如果您需要改变 <filename>pkg-<replaceable>*</replaceable></filename> + 文件， 请按照 <link + linkend="porting-pkgfiles">重新定义某个变量</link> 介绍的方法， + 而不是覆盖它们来实现。</para> + </sect1> + + <sect1 id="porting-wrkdirprefix"> + <title><makevar>WRKDIRPREFIX</makevar> (用于构建的临时目录的父目录名)</title> + + <para>一定要确保您的 port 尊重 <makevar>WRKDIRPREFIX</makevar> 的设置。 + 绝大多数 port 并不需要担心这个。 具体说来， + 当引用其他 port 的 <makevar>WRKDIR</makevar> 时， + 需要注意正确的位置应该是 + <filename><makevar>WRKDIRPREFIX</makevar><makevar>PORTSDIR</makevar>/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> + 而不是 <filename><makevar>PORTSDIR</makevar>/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> 或 <filename><makevar>.CURDIR</makevar>/../../<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename>， + 或别的什么。</para> + + <para>另外， 如果您自行定义了 <makevar>WRKDIR</makevar>， 也要把 + <literal>${WRKDIRPREFIX}${.CURDIR}</literal> 放到前面。</para> + </sect1> + + <sect1 id="porting-versions"> + <title>区分不同的操作系统， 以及 OS 的版本</title> + + <para>在不同版本的 Unix 下可能需要对代码进行一些修改或增加少许编译选项， + 才能够正确地编译和运行。 如果您需要根据一些条件来对代码进行修改， + 请尽可能让这些修改通用， 这样， 我们就能够将这些代码移植回更早的 FreeBSD + 系统， 并交叉移植到其他 BSD 系统， 例如来自 CSRG 的 4.4BSD， + BSD/386， 386BSD， NetBSD 和 OpenBSD。</para> + + <para>推荐的获得 4.3BSD/Reno (1990) 以及更新版本 BSD 代码版本号的方式， 是使用 + <ulink url="http://cvsweb.freebsd.org/src/sys/sys/param.h">sys/param.h</ulink> + 中所定义的 <literal>BSD</literal> 宏的值。 一般来说这个文件已经被引用了； + 如果没有的话， 增加下述代码：</para> + + <programlisting>#if (defined(__unix__) || defined(unix)) && !defined(USG) +#include <sys/param.h> +#endif</programlisting> + + <para>到 <filename>.c</filename> 文件中合适的地方。 + 我们相信所有定义了这两个符号的系统中， 都提供了 + <filename>sys/param.h</filename>。 如果您发现有不这样做的系统， + 请通过致信 &a.ports; 让我们了解这一情况。</para> + + <para>另一种方法是使用 GNU Autoconf 风格的方式：</para> + + <programlisting>#ifdef HAVE_SYS_PARAM_H +#include <sys/param.h> +#endif</programlisting> + + <para>采用这种方法时， 不要忘了把 <literal>-DHAVE_SYS_PARAM_H</literal> 加到 + <filename>Makefile</filename> 中的 <makevar>CFLAGS</makevar> 里。</para> + + <para>一旦引用了 <filename>sys/param.h</filename>， 您就可以使用：</para> + + <programlisting>#if (defined(BSD) && (BSD >= 199103))</programlisting> + + <para>来检测代码是否正在 4.3 Net2 代码基础， + 或更新的系统上编译 (例如 FreeBSD 1.x， 4.3/Reno， NetBSD 0.9， 386BSD， + BSD/386 1.1 以及更高版本)。</para> + + <para>使用：</para> + + <programlisting>#if (defined(BSD) && (BSD >= 199306))</programlisting> + + <para>来检测代码是否正在 4.4 或更新的系统 (例如 FreeBSD 2.x， 4.4， + NetBSD 1.0、 BSD/386 2.0 或更高版本)。</para> + + <para>对于 4.4BSD-Lite2 代码系来说， <literal>BSD</literal> 宏的值应该是 + <literal>199506</literal>。 这里只是作为信息提供， + 您不应使用它来区分基于 4.4-Lite 的 FreeBSD 和基于 4.4-Lite2 的版本。 + 这些情况下， 您应使用 + <literal>__FreeBSD__</literal> 宏。</para> + + <para>保守地使用：</para> + + <itemizedlist> + <listitem> + <para><literal>__FreeBSD__</literal> 在所有版本的 + FreeBSD 中皆有定义。 如果您正进行的修改 + <emphasis>只</emphasis> 影响 FreeBSD， 则应使用这个宏。 + 类似 <literal>sys_errlist[]</literal> 之于 + <function>strerror()</function> 这样的移植问题是伯克利代码系公用的， + 而并非 FreeBSD 所专有。</para> + </listitem> + + <listitem> + <para>在 FreeBSD 2.x 中， <literal>__FreeBSD__</literal> + 定义为 <literal>2</literal>。 更早版本中， 它曾经是 + <literal>1</literal>。 新的版本都会在主要的版本号变化时变更它。</para> + </listitem> + + <listitem> + <para>如果您需要区分 FreeBSD 1.x 系统和 FreeBSD 2.x 及更高版本的区别， + 通常应使用前述的 <literal>BSD</literal> 宏来进行。 + 如果事实上需要一个 FreeBSD 专有的修改 (例如， + 在使用 <command>ld</command> 时需要特殊的共享库选项)， + 则可以用 <literal>__FreeBSD__</literal> 和 <literal>#if + __FreeBSD__ > 1</literal> 来检测 FreeBSD 2.x 和新系统上的变化。 + 如果需要更细粒度地检测 FreeBSD 2.0-RELEASE 之后版本的变化， + 则可以使用：</para> + + <programlisting>#if __FreeBSD__ >= 2 +#include <osreldate.h> +# if __FreeBSD_version >= 199504 + /* 2.0.5+ release specific code here */ +# endif +#endif</programlisting> + </listitem> + </itemizedlist> + + <para>在已有的数百个 port 中， 只有一两个应该使用 <literal>__FreeBSD__</literal>。 + 早期的 port 在不适当的地方使用了它并引发问题， + 并不意味着您也必定如此。</para> + </sect1> + + <sect1 id="freebsd-versions"> + <title>__FreeBSD_version 值</title> + + <para>下面是在 <ulink url="http://cvsweb.freebsd.org/src/sys/sys/param.h">sys/param.h</ulink> + <literal>__FreeBSD_version</literal> 中定义的值及其意义的列表， + 这里给出以方便您查阅：</para> + + <table frame="none"> + <title>__FreeBSD_version 值</title> + <tgroup cols="2"> + <thead> + <row> + <entry>版本</entry> + <entry><literal>__FreeBSD_version</literal></entry> + </row> + </thead> + + <tbody> + <row> + <entry>2.0-RELEASE</entry> + <entry>119411</entry> + </row> + + <row> + <entry>2.1-CURRENT</entry> + <entry>199501, 199503</entry> + </row> + + <row> + <entry>2.0.5-RELEASE</entry> + <entry>199504</entry> + </row> + + <row> + <entry>2.1 之前的 2.2-CURRENT</entry> + <entry>199508</entry> + </row> + + <row> + <entry>2.1.0-RELEASE</entry> + <entry>199511</entry> + </row> + + <row> + <entry>2.1.5 之前的 2.2-CURRENT</entry> + <entry>199512</entry> + </row> + + <row> + <entry>2.1.5-RELEASE</entry> + <entry>199607</entry> + </row> + + <row> + <entry>2.1.6 之前的 2.2-CURRENT</entry> + <entry>199608</entry> + </row> + + <row> + <entry>2.1.6-RELEASE</entry> + <entry>199612</entry> + </row> + + <row> + <entry>2.1.7-RELEASE</entry> + <entry>199612</entry> + </row> + + <row> + <entry>2.2-RELEASE</entry> + <entry>220000</entry> + </row> + + <row> + <entry>2.2.1-RELEASE</entry> + <entry>220000 (无变化)</entry> + </row> + + <row> + <entry>在 2.2.1-RELEASE 之后的 2.2-STABLE</entry> + <entry>220000 (无变化)</entry> + </row> + + <row> + <entry>texinfo-3.9 之后的 2.2-STABLE</entry> + <entry>221001</entry> + </row> + + <row> + <entry>top 之后的 2.2-STABLE</entry> + <entry>221002</entry> + </row> + + <row> + <entry>2.2.2-RELEASE</entry> + <entry>222000</entry> + </row> + + <row> + <entry>2.2.2-RELEASE 之后的 2.2-STABLE</entry> + <entry>222001</entry> + </row> + + <row> + <entry>2.2.5-RELEASE</entry> + <entry>225000</entry> + </row> + + <row> + <entry>2.2.5-RELEASE 之后的 2.2-STABLE</entry> + <entry>225001</entry> + </row> + + <row> + <entry>合并 ldconfig -R 之后的 2.2-STABLE</entry> + <entry>225002</entry> + </row> + + <row> + <entry>2.2.6-RELEASE</entry> + <entry>226000</entry> + </row> + + <row> + <entry>2.2.7-RELEASE</entry> + <entry>227000</entry> + </row> + + <row> + <entry>2.2.7-RELEASE 之后的 2.2-STABLE</entry> + <entry>227001</entry> + </row> + + <row> + <entry>&man.semctl.2; 修改之后的 2.2-STABLE</entry> + <entry>227002</entry> + </row> + + <row> + <entry>2.2.8-RELEASE</entry> + <entry>228000</entry> + </row> + + <row> + <entry>2.2.8-RELEASE 之后的 2.2-STABLE</entry> + <entry>228001</entry> + </row> + + <row> + <entry>&man.mount.2; 修改之前的 3.0-CURRENT</entry> + <entry>300000</entry> + </row> + + <row> + <entry>&man.mount.2; 修改之后的 3.0-CURRENT</entry> + <entry>300001</entry> + </row> + + <row> + <entry>&man.semctl.2; 修改之后的 3.0-CURRENT</entry> + <entry>300002</entry> + </row> + + <row> + <entry>ioctl 参数变化之后的 3.0-CURRENT</entry> + <entry>300003</entry> + </row> + + <row> + <entry>ELF 变换之后的 3.0-CURRENT</entry> + <entry>300004</entry> + </row> + + <row> + <entry>3.0-RELEASE</entry> + <entry>300005</entry> + </row> + + <row> + <entry>3.0-RELEASE 之后的 3.0-CURRENT</entry> + <entry>300006</entry> + </row> + + <row> + <entry>3/4切分之后的 3.0-STABLE</entry> + <entry>300007</entry> + </row> + + <row> + <entry>3.1-RELEASE</entry> + <entry>310000</entry> + </row> + + <row> + <entry>3.1-RELEASE 之后的 3.1-STABLE</entry> + <entry>310001</entry> + </row> + + <row> + <entry>C++ 构建/析构函数顺序变化之后的 3.1-STABLE</entry> + <entry>310002</entry> + </row> + + <row> + <entry>3.2-RELEASE</entry> + <entry>320000</entry> + </row> + + <row> + <entry>3.2-STABLE</entry> + <entry>320001</entry> + </row> + + <row> + <entry>二进制不兼容的 IPFW 和 socket 变化之后的 3.2-STABLE</entry> + <entry>320002</entry> + </row> + + <row> + <entry>3.3-RELEASE</entry> + <entry>330000</entry> + </row> + + <row> + <entry>3.3-STABLE</entry> + <entry>330001</entry> + </row> + + <row> + <entry>libc 中加入 &man.mkstemp.3; 之后的 3.3-STABLE</entry> + <entry>330002</entry> + </row> + + <row> + <entry>3.4-RELEASE</entry> + <entry>340000</entry> + </row> + + <row> + <entry>3.4-STABLE</entry> + <entry>340001</entry> + </row> + + <row> + <entry>3.5-RELEASE</entry> + <entry>350000</entry> + </row> + + <row> + <entry>3.5-STABLE</entry> + <entry>350001</entry> + </row> + + <row> + <entry>3/4切分之后的 4.0-CURRENT</entry> + <entry>400000</entry> + </row> + + <row> + <entry>修改动态连接器处理方式之后的 4.0-CURRENT</entry> + <entry>400001</entry> + </row> + + <row> + <entry>C++ 构建/析构函数顺序变化之后的</entry> + <entry>400002</entry> + </row> + + <row> + <entry>提供 &man.dladdr.3; 之后的 4.0-CURRENT</entry> + <entry>400003</entry> + </row> + + <row> + <entry>修正了 __deregister_frame_info 的 4.0-CURRENT + (也表示在 EGCS 1.1.2 + 集成之后的 4.0-CURRENT) + </entry> + <entry>400004</entry> + </row> + + <row> + <entry>&man.suser.9; API 变化之后的 4.0-CURRENT + (也表示 newbus 之后的 4.0-CURRENT)</entry> + <entry>400005</entry> + </row> + + <row> + <entry>cdevsw 注册机制改变之后的 4.0-CURRENT</entry> + <entry>400006</entry> + </row> + + <row> + <entry>加入了 socket 级凭据的 so_cred 之后的 4.0-CURRENT</entry> + <entry>400007</entry> + </row> + + <row> + <entry>在 libc_r 中加入 poll 系统调用接口之后的 4.0-CURRENT</entry> + <entry>400008</entry> + </row> + + <row> + <entry>将内核中 + <literal>dev_t</literal> 类型改为 <literal>struct + specinfo</literal> 指针之后的 4.0-CURRENT</entry> + <entry>400009</entry> + </row> + + <row> + <entry>修正了一处 &man.jail.2; 漏洞之后的 4.0-CURRENT</entry> + <entry>400010</entry> + </row> + + <row> + <entry><literal>sigset_t</literal> 数据类型改变之后的 4.0-CURRENT</entry> + <entry>400011</entry> + </row> + + <row> + <entry>切换到 GCC 2.95.2 编译器之后的 4.0-CURRENT</entry> + <entry>400012</entry> + </row> + + <row> + <entry>加入了可插的 linux模式 ioctl 处理程序后的 4.0-CURRENT</entry> + <entry>400013</entry> + </row> + + <row> + <entry>引入 OpenSSL 之后的 4.0-CURRENT</entry> + <entry>400014</entry> + </row> + + <row> + <entry>GCC 2.95.2 中 ABI 默认值从 -fvtable-thunks 改为 + -fno-vtable-thunks 之后的 4.0-CURRENT</entry> + <entry>400015</entry> + </row> + + <row> + <entry>引入 OpenSSH 之后的 4.0-CURRENT</entry> + <entry>400016</entry> + </row> + + <row> + <entry>4.0-RELEASE</entry> + <entry>400017</entry> + </row> + + <row> + <entry>4.0-RELEASE 之后的 4.0-STABLE</entry> + <entry>400018</entry> + </row> + + <row> + <entry>引入延迟校验和之后的 4.0-STABLE</entry> + <entry>400019</entry> + </row> + + <row> + <entry>将 libxpg4 的代码并入 libc 之后的 4.0-STABLE</entry> + <entry>400020</entry> + </row> + + <row> + <entry>Binutils 升级到 2.10.0 之后的 4.0-STABLE， ELF + 标志变化， 以及将 tcsh 引入基本系统</entry> + <entry>400021</entry> + </row> + + <row> + <entry>4.1-RELEASE</entry> + <entry>410000</entry> + </row> + + <row> + <entry>4.1-RELEASE 之后的 4.1-STABLE</entry> + <entry>410001</entry> + </row> + + <row> + <entry>&man.setproctitle.3; 从 libutil 移入 libc + 之后的 4.1-STABLE</entry> + <entry>410002</entry> + </row> + + <row> + <entry>4.1.1-RELEASE</entry> + <entry>411000</entry> + </row> + + <row> + <entry>4.1.1-RELEASE 之后的 4.1.1-STABLE</entry> + <entry>411001</entry> + </row> + + <row> + <entry>4.2-RELEASE</entry> + <entry>420000</entry> + </row> + + <row> + <entry>合并 libgcc.a 和 libgcc_r.a， + 并修改了相关的 GCC 连接方式之后的 4.2-STABLE</entry> + <entry>420001</entry> + </row> + + <row> + <entry>4.3-RELEASE</entry> + <entry>430000</entry> + </row> + + <row> + <entry>引入 wint_t 之后的 4.3-STABLE</entry> + <entry>430001</entry> + </row> + + <row> + <entry>PCI 电源状态 API 合并之后的 4.3-STABLE</entry> + <entry>430002</entry> + </row> + + <row> + <entry>4.4-RELEASE</entry> + <entry>440000</entry> + </row> + + <row> + <entry>引入 d_thread_t 之后的 4.4-STABLE</entry> + <entry>440001</entry> + </row> + + <row> + <entry>mount 结构改变之后的 4.4-STABLE (影响文件系统 kld)</entry> + <entry>440002</entry> + </row> + + <row> + <entry>用户态部分的 smbfs 被引入之后的 4.4-STABLE</entry> + <entry>440003</entry> + </row> + + <row> + <entry>4.5-RELEASE</entry> + <entry>450000</entry> + </row> + + <row> + <entry>usb 结构元素改名之后的 4.5-STABLE</entry> + <entry>450001</entry> + </row> + + <row> + <entry>在 &man.rc.conf.5; 变量 + <literal>sendmail_enable</literal> 默认值改为 + <literal>NONE</literal> 之后的 4.5-STABLE</entry> + <entry>450004</entry> + </row> + + <row> + <entry>默认将 XFree86 4 用于预编译包构建之后的 4.5-STABLE</entry> + <entry>450005</entry> + </row> + + <row> + <entry>accept 过滤器修正了安全问题并且不再会轻易被 DoS + 之后的 4.5-STABLE</entry> + <entry>450006</entry> + </row> + + <row> + <entry>4.6-RELEASE</entry> + <entry>460000</entry> + </row> + + <row> + <entry>修正了 &man.sendfile.2; 以吻合文档， + 而不再根据发出的头计算发出数据量之后的 4.6-STABLE</entry> + <entry>460001</entry> + </row> + + <row> + <entry>4.6.2-RELEASE</entry> + <entry>460002</entry> + </row> + + <row> + <entry>4.6-STABLE</entry> + <entry>460100</entry> + </row> + + <row> + <entry>MFC `sed -i' 之后的 4.6-STABLE</entry> + <entry>460101</entry> + </row> + + <row> + <entry>MFC 许多 pkg_install 新特性之后的 4.6-STABLE</entry> + <entry>460102</entry> + </row> + + <row> + <entry>4.7-RELEASE</entry> + <entry>470000</entry> + </row> + + <row> + <entry>4.7-STABLE</entry> + <entry>470100</entry> + </row> + + <row> + <entry>开始生成 __std{in,out,err}p 引用， 而不是 __sF。 + 这将 std{in,out,err} 从编译时表达式变成了运行时值。</entry> + <entry>470101</entry> + </row> + + <row> + <entry>MFC mbuf 相关的将 m_aux mbuf 改为 m_tag + 的修改之后的 4.7-STABLE</entry> + <entry>470102</entry> + </row> + + <row> + <entry>OpenSSL 升级到 0.9.7 之后的 4.7-STABLE</entry> + <entry>470103</entry> + </row> + + <row> + <entry>4.8-RELEASE</entry> + <entry>480000</entry> + </row> + + <row> + <entry>4.8-STABLE</entry> + <entry>480100</entry> + </row> + + <row> + <entry>&man.realpath.3; 变为线程安全的之后的 4.8-STABLE</entry> + <entry>480101</entry> + </row> + + <row> + <entry>对 twe 的 3ware API 修改之后的 4.8-STABLE</entry> + <entry>480102</entry> + </row> + + <row> + <entry>4.9-RELEASE</entry> + <entry>490000</entry> + </row> + + <row> + <entry>4.9-STABLE</entry> + <entry>490100</entry> + </row> + + <row> + <entry>kinfo_eproc 中加入 e_sid 之后的 4.9-STABLE</entry> + <entry>490101</entry> + </row> + + <row> + <entry>MFC rtld 的 libmap 功能之后的 4.9-STABLE</entry> + <entry>490102</entry> + </row> + + <row> + <entry>4.10-RELEASE</entry> + <entry>491000</entry> + </row> + + <row> + <entry>4.10-STABLE</entry> + <entry>491100</entry> + </row> + + <row> + <entry>MFC 20040629 版本的包维护工具之后的 4.10-STABLE</entry> + <entry>491101</entry> + </row> + + <row> + <entry>修正了 VM 当解除 wire 不存在页面时的问题之后的 + 4.10-STABLE</entry> + <entry>491102</entry> + </row> + + <row> + <entry>4.11-RELEASE</entry> + <entry>492000</entry> + </row> + + <row> + <entry>4.11-STABLE</entry> + <entry>492100</entry> + </row> + + <row> + <entry>5.0-CURRENT</entry> + <entry>500000</entry> + </row> + + <row> + <entry>加入 ELF 头字段， 并改变我们的 ELF 执行文件标记方式之后的 + 5.0-CURRENT</entry> + <entry>500001</entry> + </row> + + <row> + <entry>kld 元数据修改之后的 5.0-CURRENT</entry> + <entry>500002</entry> + </row> + + <row> + <entry>buf/bio 修改之后的 5.0-CURRENT</entry> + <entry>500003</entry> + </row> + + <row> + <entry>binutils 升级后的 5.0-CURRENT</entry> + <entry>500004</entry> + </row> + + <row> + <entry>将 libxpg4 并入 libc， + 以及引入 TASKQ 之后的 5.0-CURRENT</entry> + <entry>500005</entry> + </row> + + <row> + <entry>加入 AGP 接口之后的 5.0-CURRENT</entry> + <entry>500006</entry> + </row> + + <row> + <entry>Perl 升级到 5.6.0 之后的 5.0-CURRENT</entry> + <entry>500007</entry> + </row> + + <row> + <entry>KAME 代码升级到 2000/07 之后的 5.0-CURRENT</entry> + <entry>500008</entry> + </row> + + <row> + <entry>ether_ifattach() 和 ether_detach() + 修改之后的 5.0-CURRENT</entry> + <entry>500009</entry> + </row> + + <row> + <entry>将 mtree 改为原先的默认值， + 并使用 -L 来跟随符号连接之后的 5.0-CURRENT</entry> + <entry>500010</entry> + </row> + + <row> + <entry>kqueue API 修改之后的 5.0-CURRENT</entry> + <entry>500011</entry> + </row> + + <row> + <entry>&man.setproctitle.3; 从 libutil 挪到 libc 之后的 + 5.0-CURRENT</entry> + <entry>500012</entry> + </row> + + <row> + <entry>首个 SMPng commit 之后的 5.0-CURRENT</entry> + <entry>500013</entry> + </row> + + <row> + <entry><sys/select.h> 改为 <sys/selinfo.h> + 之后的 5.0-CURRENT</entry> + <entry>500014</entry> + </row> + + <row> + <entry>libgcc.a 和 libgcc_r.a 以及 GCC + 连接方式变动之后的 5.0-CURRENT</entry> + <entry>500015</entry> + </row> + + <row> + <entry>修改以允许 libc 和 libc_r 连接到一起， + 不再鼓励使用 -pthread 之后的 5.0-CURRENT</entry> + <entry>500016</entry> + </row> + + <row> + <entry>从 struct ucred 切换到 struct xucred + 以便使内核为 mountd 等程序导出的 API 稳定下来之后的 + 5.0-CURRENT</entry> + <entry>500017</entry> + </row> + + <row> + <entry>加入 CPUTYPE 用于 CPU 专用的优化的 + make 变量之后的 5.0-CURRENT</entry> + <entry>500018</entry> + </row> + + <row> + <entry>machine/ioctl_fd.h 改为 sys/fdcio.h 之后的 + 5.0-CURRENT</entry> + <entry>500019</entry> + </row> + + <row> + <entry>locale 名称改变之后的 5.0-CURRENT</entry> + <entry>500020</entry> + </row> + + <row> + <entry>引入 bzip2 之后的 5.0-CURRENT， + 同时也代表删去了 S/Key</entry> + <entry>500021</entry> + </row> + + <row> + <entry>加入 SSE 支持之后的 5.0-CURRENT</entry> + <entry>500022</entry> + </row> + + <row> + <entry>KSE 第2个里程碑之后的 5.0-CURRENT</entry> + <entry>500023</entry> + </row> + + <row> + <entry>d_thread_t 之后的 5.0-CURRENT， + 同时 UUCP 被移入 ports</entry> + <entry>500024</entry> + </row> + + <row> + <entry>64-位平台上的描述符和 creds API 变化之后的 + 5.0-CURRENT</entry> + <entry>500025</entry> + </row> + + <row> + <entry>采用 XFree86 4 作为默认的预编译包， + 以及加入 strnstr() libc 函数之后的 5.0-CURRENT</entry> + <entry>500026</entry> + </row> + + <row> + <entry>加入 strcasestr() libc 函数之后的 5.0-CURRENT</entry> + <entry>500027</entry> + </row> + + <row> + <entry>引入了用户态的 smbfs 组件之后的 5.0-CURRENT</entry> + <entry>500028</entry> + </row> + + <row> + <entry>加入了新的 C99 指定位宽整形变量之后的 5.0-CURRENT</entry> + <entry>(未予增加)</entry> + </row> + + <row> + <entry>修改了 &man.sendfile.2; 的返回值之后的 5.0-CURRENT</entry> + <entry>500029</entry> + </row> + + <row> + <entry>引入适合表达文件标志的 <literal>fflags_t</literal> + 类型之后的 5.0-</entry> + <entry>500030</entry> + </row> + + <row> + <entry>usb 结构元素改名之后的 5.0-CURRENT</entry> + <entry>500031</entry> + </row> + + <row> + <entry>引入 Perl 5.6.1 之后的 5.0-CURRENT</entry> + <entry>500032</entry> + </row> + + <row> + <entry>&man.rc.conf.5; 变量 + <literal>sendmail_enable</literal> 默认值改为 + <literal>NONE</literal> 之后的 5.0-CURRENT</entry> + <entry>500033</entry> + </row> + + <row> + <entry>mtx_init() 增加了第三个参数之后的 5.0-CURRENT</entry> + <entry>500034</entry> + </row> + + <row> + <entry>包含 Gcc 3.1 的 5.0-CURRENT</entry> + <entry>500035</entry> + </row> + + <row> + <entry>在 /usr/src 中删去了 Perl 的 5.0-CURRENT</entry> + <entry>500036</entry> + </row> + + <row> + <entry>加入 &man.dlfunc.3; 之后的 5.0-CURRENT</entry> + <entry>500037</entry> + </row> + + <row> + <entry>一些 struct sockbuf 的成员变为结构， + 并重新排列顺序之后的 5.0-CURRENT</entry> + <entry>500038</entry> + </row> + + <row> + <entry>引入 GCC 3.2.1 之后的 5.0-CURRENT。 头文件也不再使用 + _BSD_FOO_T_ 而开始使用 _FOO_T_DECLARED。 + 这个值还可以用于作为一个包含使用 &man.bzip2.1; + 的预编译包支持的预期点。</entry> + <entry>500039</entry> + </row> + + <row> + <entry>以去掉对 disklabel 结构内容的依赖的名义， + 对磁盘相关的函数进行了许多修改之后的 5.0-CURRENT</entry> + <entry>500040</entry> + </row> + + <row> + <entry>libc 中加入 &man.getopt.long.3; 之后的 5.0-CURRENT</entry> + <entry>500041</entry> + </row> + + <row> + <entry>Binutils 2.13 升级， 包含了新的 FreeBSD 模拟， + vec 以及输出格式之后的 5.0-CURRENT</entry> + <entry>500042</entry> + </row> + + <row> + <entry>libc 中加入了弱 pthread_XXX 符号之后的 5.0-CURRENT， + 从而淘汰了 libXThrStub.so。 5.0-RELEASE。</entry> + <entry>500043</entry> + </row> + + <row> + <entry>创建 RELENG_5_0 分支之后的 5.0-CURRENT</entry> + <entry>500100</entry> + </row> + <row> + <entry><sys/dkstat.h> 变成了一个空文件， 不应再被引用</entry> + <entry>500101</entry> + </row> + <row> + <entry>修改 d_mmap_t 接口之后的 5.0-CURRENT</entry> + <entry>500102</entry> + </row> + <row> + <entry>taskqueue_swi 以无全局锁的方式运行之后的 5.0-CURRENT， + 同时还加入了使用全局锁的 taskqueue_swi_giant</entry> + <entry>500103</entry> + </row> + <row> + <entry>去掉了 cdevsw_add() 和 cdevsw_remove() + 出现 MAJOR_AUTO 分配机制</entry> + <entry>500104</entry> + </row> + <row> + <entry>采用新的 cdevsw 初始化方法之后的 5.0-CURRENT</entry> + <entry>500105</entry> + </row> + <row> + <entry>devstat_add_entry() 被 + devstat_new_entry() 取代</entry> + <entry>500106</entry> + </row> + <row> + <entry>修改 devstat 接口； 请参见 sys/sys/param.h 1.149</entry> + <entry>500107</entry> + </row> + <row> + <entry>改变了 Token-Ring 接口</entry> + <entry>500108</entry> + </row> + <row> + <entry>加入 vm_paddr_t</entry> + <entry>500109</entry> + </row> + <row> + <entry>将 &man.realpath.3; 改为线程安全之后的 + 5.0-CURRENT</entry> + <entry>500110</entry> + </row> + <row> + <entry>&man.usbhid.3; 与 NetBSD 同步之后的 5.0-CURRENT</entry> + <entry>500111</entry> + </row> + <row> + <entry>加入新的 NSS 实现， 以及 POSIX.1 getpw*_r, getgr*_r + 函数之后的 5.0-CURRENT</entry> + <entry>500112</entry> + </row> + <row> + <entry>删去旧式 rc 系统之后的 5.0-CURRENT</entry> + <entry>500113</entry> + </row> + <row> + <entry>5.1-RELEASE.</entry> + <entry>501000</entry> + </row> + <row> + <entry>创建 RELENG_5_1 分支之后的 5.1-CURRENT</entry> + <entry>501100</entry> + </row> + <row> + <entry>改正 sigtimedwait(2) 和 sigwaitinfo(2) + 语义之后的 5.1-CURRENT</entry> + <entry>501101</entry> + </row> + <row> + <entry>在 &man.bus.dma.tag.create.9; 中加入了 lockfunc + 和 lockfuncarg 字段之后的 5.1-CURRENT</entry> + <entry>501102</entry> + </row> + <row> + <entry>集成了 GCC 3.3.1-pre 20030711 之后的 + 5.1-CURRENT</entry> + <entry>501103</entry> + </row> + <row> + <entry>twe 中 3ware API 变化之后的 5.1-CURRENT</entry> + <entry>501104</entry> + </row> + <row> + <entry>允许动态连接 /bin 和 /sbin， + 以及将某些库移动到 /lib 之后的 5.1-CURRENT</entry> + <entry>501105</entry> + </row> + <row> + <entry>增加内核级 Coda 6.x 支持之后的 5.1-CURRENT</entry> + <entry>501106</entry> + </row> + <row> + <entry>将 16550 UART 常量从 + <filename><dev/sio/sioreg.h></filename> 挪到 + <filename><dev/ic/ns16550.h></filename> 之后的 + 5.1-CURRENT。 此外， rtld 也从此无条件支持 libmap 功能</entry> + <entry>501107</entry> + </row> + <row> + <entry>更新 PFIL_HOOKS API 之后的 5.1-CURRENT</entry> + <entry>501108</entry> + </row> + <row> + <entry>增加 kiconv(3) 之后的 5.1-CURRENT</entry> + <entry>501109</entry> + </row> + <row> + <entry>默认的 cdevsw open 和 close 操作变化之后的 5.1-CURRENT</entry> + <entry>501110</entry> + </row> + <row> + <entry>cdevsw 的布局变化之后的 5.1-CURRENT</entry> + <entry>501111</entry> + </row> + <row> + <entry>增加 kobj 多继承之后的 5.1-CURRENT</entry> + <entry>501112</entry> + </row> + <row> + <entry>修改 struct ifnet 中的 if_xname 之后的 5.1-CURRENT</entry> + <entry>501113</entry> + </row> + <row> + <entry>将 /bin 和 /sbin 改为动态连接之后的 5.1-CURRENT</entry> + <entry>501114</entry> + </row> + <row> + <entry>5.2-RELEASE</entry> + <entry>502000</entry> + </row> + <row> + <entry>5.2.1-RELEASE</entry> + <entry>502010</entry> + </row> + <row> + <entry>创建 RELENG_5_2 分支之后的 5.2-CURRENT</entry> + <entry>502100</entry> + </row> + <row> + <entry>libc 中加入了 __cxa_atexit/__cxa_finalize + 两个函数之后的 5.2-CURRENT</entry> + <entry>502101</entry> + </row> + <row> + <entry>默认线程库从 libc_r 改为 libpthread 之后的 + 5.2-CURRENT</entry> + <entry>502102</entry> + </row> + <row> + <entry>设备驱动 API 大规模翻修之后的 5.2-CURRENT</entry> + <entry>502103</entry> + </row> + <row> + <entry>增加 getopt_long_only() 之后的 5.2-CURRENT</entry> + <entry>502104</entry> + </row> + <row> + <entry>C 的 NULL 定义改为 ((void *)0) 之后的 5.2-CURRENT， + 这会产生更多的编译警告</entry> + <entry>502105</entry> + </row> + <row> + <entry>pf 连入构建和安装过程之后的 5.2-CURRENT + </entry> + <entry>502106</entry> + </row> + <row> + <entry>在 sparc64 上将 time_t 改为 64-位 值之后的 5.2-CURRENT + </entry> + <entry>502107</entry> + </row> + <row> + <entry>在一些头文件修改以支持 Intel C/C++ 编译器， + 以及让 execve(2) 更严格地符合 POSIX 之后的 + 5.2-CURRENT</entry> + <entry>502108</entry> + </row> + <row> + <entry>引入 bus_alloc_resource_any API 之后的 5.2-CURRENT + </entry> + <entry>502109</entry> + </row> + <row> + <entry>加入 UTF-8 locale 之后的 5.2-CURRENT</entry> + <entry>502110</entry> + </row> + <row> + <entry>删去 getvfsent(3) API 之后的 5.2-CURRENT</entry> + <entry>502111</entry> + </row> + <row> + <entry>为 make(1) 增加 .warning 语句之后的 5.2-CURRENT</entry> + <entry>502112</entry> + </row> + <row> + <entry>所有串口设备都强制使用 ttyioctl() 之后的 5.2-CURRENT</entry> + <entry>502113</entry> + </row> + <row> + <entry>引入 ALTQ 框架之后的 5.2-CURRENT</entry> + <entry>502114</entry> + </row> + <row> + <entry>修改 sema_timedwait(9) 使其成功时返回 0， + 失败时返回非 0 的错误代码之后的 5.2-CURRENT</entry> + <entry>502115</entry> + </row> + <row> + <entry>将内核 dev_t 改为指向 struct cdev * 的指针之后的 + 5.2-CURRENT</entry> + <entry>502116</entry> + </row> + <row> + <entry>将内核 udev_t 改为 dev_t 之后的 5.2-CURRENT</entry> + <entry>502117</entry> + </row> + <row> + <entry>为 clock_gettime(2) 和 clock_getres(2) 增加 + CLOCK_VIRTUAL 和 CLOCK_PROF 支持之后的 5.2-CURRENT</entry> + <entry>502118</entry> + </row> + <row> + <entry>对网络接口复制进行全面修改之后的 5.2-CURRENT</entry> + <entry>502119</entry> + </row> + <row> + <entry>package 工具升级为 20040629 之后的 5.2-CURRENT</entry> + <entry>502120</entry> + </row> + <row> + <entry>不再将蓝牙代码标记为 i386 专用之后的 5.2-CURRENT</entry> + <entry>502121</entry> + </row> + <row> + <entry>引入 KDB 调试器框架之后的 5.2-CURRENT。 + 同时还引入了 DDB 作为后台， 以及 GDB 后台。</entry> + <entry>502122</entry> + </row> + <row> + <entry>修改 VFS_ROOT 和 vflush 使其使用一个 struct + thread 参数之后的 5.2-CURRENT。 struct kinfo_proc + 增加了一个用户数据指针。 同时， 默认的 X 实现切换为 + <literal>xorg</literal></entry> + <entry>502123</entry> + </row> + <row> + <entry>将使用 rc.d 和传统脚本的 port 分别启动之后的 + 5.2-CURRENT</entry> + <entry>502124</entry> + </row> + <row> + <entry>取消前一修改之后的 5.2-CURRENT</entry> + <entry>502125</entry> + </row> + <row> + <entry>删除 kmem_alloc_pageable() 并引入 gcc 3.4.2 的 + 5.2-CURRENT</entry> + <entry>502126</entry> + </row> + <row> + <entry>修改 UMA 内核 API 允许构建函数和初始化失败之后的 + 5.2-CURRENT</entry> + <entry>502127</entry> + </row> + <row> + <entry>vfs_mount 签名和全局替换 suser(9) API 的 + PRISON_ROOT 为 SUSER_ALLOWJAIL 之后的 5.2-CURRENT</entry> + <entry>502128</entry> + </row> + <row> + <entry>pfil API 修改之前的 5.3-BETA/RC</entry> + <entry>503000</entry> + </row> + <row> + <entry>5.3-RELEASE</entry> + <entry>503001</entry> + </row> + <row> + <entry>创建 RELENG_5_3 分支之后的 5.3-STABLE</entry> + <entry>503100</entry> + </row> + <row> + <entry>加入了 glibc 风格的 + &man.strftime.3; 填充选项的 5.3-STABLE</entry> + <entry>503101</entry> + </row> + <row> + <entry>MFC OpenBSD 的 nc(1) 之后的 5.3-STABLE</entry> + <entry>503102</entry> + </row> + <row> + <entry>在 MFC 了 + <filename><src/include/stdbool.h></filename> 和 + <filename><src/sys/i386/include/_types.h></filename> + 用于兼容 GCC 和 Intel C/C++ 编译器的修正之后的 5.4-PRERELEASE</entry> + <entry>503103</entry> + </row> + <row> + <entry>MFC 了将 ifi_epoch 由 wall 时钟时间改为 uptime + 之后的 5.4-PRERELEASE</entry> + <entry>503104</entry> + </row> + <row> + <entry>MFC 了 vswprintf(3) 中的 EOVERFLOW 检查的 5.4-PRERELEASE</entry> + <entry>503105</entry> + </row> + <row> + <entry>5.4-RELEASE.</entry> + <entry>504000</entry> + </row> + <row> + <entry>创建 RELENG_5_4 分支之后的 5.4-STABLE</entry> + <entry>504100</entry> + </row> + <row> + <entry>加大默认线程堆栈尺寸之后的 5.4-STABLE</entry> + <entry>504101</entry> + </row> + <row> + <entry>加入 sha256 之后的 5.4-STABLE</entry> + <entry>504102</entry> + </row> + <row> + <entry>6.0-CURRENT</entry> + <entry>600000</entry> + </row> + <row> + <entry>内核中永久性启用 PFIL_HOOKS 之后的 6.0-CURRENT</entry> + <entry>600001</entry> + </row> + <row> + <entry>最初将 ifi_epoch 加入 if_data 结构之后的 6.0-CURRENT。 + 此后不久即被撤销。 请不要使用这个值。</entry> + <entry>600002</entry> + </row> + <row> + <entry>if_data 中再次加入 ifi_epoch 成员之后的 6.0-CURRENT</entry> + <entry>600003</entry> + </row> + <row> + <entry>将 struct inpcb 参数加入 pfil API 之后的 6.0-CURRENT</entry> + <entry>600004</entry> + </row> + <row> + <entry>newsyslog 加入了 "-d + DESTDIR" 参数之后的 6.0-CURRENT</entry> + <entry>600005</entry> + </row> + <row> + <entry>加入了 glibc 风格的 + &man.strftime.3; 填充选项之后的 6.0-CURRENT</entry> + <entry>600006</entry> + </row> + <row> + <entry>加入了 802.11 框架更新之后的 6.0-CURRENT</entry> + <entry>600007</entry> + </row> + <row> + <entry>修改 VOP_*VOBJECT() 并为无全局锁的文件系统引入 + MNTK_MPSAFE 标志之后的 6.0-CURRENT</entry> + <entry>600008</entry> + </row> + <row> + <entry>加入 cpufreq 框架和驱动之后的 6.0-CURRENT</entry> + <entry>600009</entry> + </row> + <row> + <entry>引入 OpenBSD 的 nc(1) 之后的 6.0-CURRENT</entry> + <entry>600010</entry> + </row> + <row> + <entry>删去并不存在的 SVID2 + <literal>matherr()</literal> 支持之后的 6.0-CURRENT</entry> + <entry>600011</entry> + </row> + <row> + <entry>增大默认线程堆栈尺寸之后的 6.0-CURRENT</entry> + <entry>600012</entry> + </row> + <row> + <entry>增加了针对 + <filename><src/include/stdbool.h></filename> 和 + <filename><src/sys/i386/include/_types.h></filename> + 的用于 Intel C/C++ 编译器的 GCC-兼容性修正。</entry> + <entry>600013</entry> + </row> + <row> + <entry>修正了 vswprintf(3) 的 EOVERFLOW 检查之后的 6.0-CURRENT</entry> + <entry>600014</entry> + </row> + <row> + <entry>将 struct if_data 成员 ifi_epoch 从 wall 时钟时间改为 uptime + 之后的 6.0-CURRENT</entry> + <entry>600015</entry> + </row> + <row> + <entry>修改 LC_CTYPE 磁盘格式之后的 6.0-CURRENT</entry> + <entry>600016</entry> + </row> + <row> + <entry>修改 NLS 编录磁盘格式之后的 6.0-CURRENT</entry> + <entry>600017</entry> + </row> + <row> + <entry>修改 LC_COLLATE 磁盘格式之后的 6.0-CURRENT</entry> + <entry>600018</entry> + </row> + <row> + <entry>将 acpica 头文件安装到 /usr/include</entry> + <entry>600019</entry> + </row> + <row> + <entry>为 send(2) API 加入了 MSG_NOSIGNAL</entry> + <entry>600020</entry> + </row> + <row> + <entry>在 cdevsw 上增加了一些字段</entry> + <entry>600021</entry> + </row> + <row> + <entry>基本系统中删去了 gtar</entry> + <entry>600022</entry> + </row> + <row> + <entry>unix(4) 中加入了 LOCAL_CREDS, LOCAL_CONNWAIT 两个 socket 选项</entry> + <entry>600023</entry> + </row> + <row> + <entry>加入了 &man.hwpmc.4; 及其相关工具之后的 6.0-CURRENT</entry> + <entry>600024</entry> + </row> + <row> + <entry>加入 struct icmphdr 之后的 6.0-CURRENT</entry> + <entry>600025</entry> + </row> + <row> + <entry>pf 更新到了 3.7</entry> + <entry>600026</entry> + </row> + <row> + <entry>引入了内核 libalias 和 ng_nat</entry> + <entry>600027</entry> + </row> + <row> + <entry>将 ttyname_r(3) 接口改为符合 POSIX 标准， + 并通过 unistd.h 和 libc</entry> + <entry>600028</entry> + </row> + <row> + <entry>将 libpcap 升级为 v0.9.1 alpha 096 之后的 6.0-CURRENT</entry> + <entry>600029</entry> + </row> + <row> + <entry>引入 NetBSD 的 if_bridge(4) 之后的 6.0-CURRENT</entry> + <entry>600030</entry> + </row> + <row> + <entry>将 struct ifnet 从驱动的 softc 中拆出之后的 6.0-CURRENT。</entry> + <entry>600031</entry> + </row> + <row> + <entry>引入了 libpcap v0.9.1 之后的 6.0-CURRENT。</entry> + <entry>600032</entry> + </row> + <row> + <entry>7.0-CURRENT。</entry> + <entry>700000</entry> + </row> + </tbody> + </tgroup> + </table> + + <note> + <para>请注意， 2.2.5-RELEASE 之后有一段时间的 2.2-STABLE 会声称自己是 + <quote>2.2.5-STABLE</quote>。 这种模式的版本号表示的是年月。 + 但随后， 我们决定， 从 2.2 开始， 将它改为更为简洁的 主/次 + 版本号的形式来命名版本。 这是因为并行地在多个分支上进行开发， + 使得通过实际的发布日期来区分不同的版本变得不再显示。 + 如果您正在做新的 port， 应该不需要担心较早的 -CURRENT； + 在此列出仅供参考。</para> + </note> + </sect1> + + <sect1 id="dads-after-port-mk"> + <title>在 <filename>bsd.port.mk</filename> 之后写一些内容</title> + + <para>不要在 <literal>.include + <bsd.port.mk></literal> 这行之后增加任何内容。 + 这通常可以通过在您的 <filename>Makefile</filename> + 中间的某处引用 <filename>bsd.port.pre.mk</filename>， + 并在结尾的地方引用 + <filename>bsd.port.post.mk</filename> 来避免。</para> + + <note> + <para>只能够采用 + <filename>bsd.port.pre.mk</filename>/<filename>bsd.port.post.mk</filename> 或 + <filename>bsd.port.mk</filename> 两种写法之一； + 任何时候都不要同时使用两种写法。</para> + </note> + + <para><filename>bsd.port.pre.mk</filename> 只定义了很少的变量， + 它们可以在 <filename>Makefile</filename> + 中用于进行一些测试， 而 <filename>bsd.port.post.mk</filename> + 则定义了所有其他的变量。</para> + + <para>下面是一些由 <filename>bsd.port.pre.mk</filename> + 定义的比较重要的变量 (这并不是一份完整的列表， + 您可以阅读 <filename>bsd.port.mk</filename> 以获得全部变量的名字)。</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>变量</entry> + <entry>描述</entry> + </row> + </thead> + + <tbody> + <row> + <entry><makevar>ARCH</makevar></entry> + <entry>由 <command>uname + -m</command> 输出得到的硬件架构的名字 + (例如， <literal>i386</literal>)</entry> + </row> + + <row> + <entry><makevar>OPSYS</makevar></entry> + <entry>由 <command>uname -s</command> 返回的操作系统类型 (例如， + <literal>FreeBSD</literal>)</entry> + </row> + + <row> + <entry><makevar>OSREL</makevar></entry> + <entry>操作系统的版本号 (例如 + <literal>2.1.5</literal> 或 + <literal>2.2.7</literal>)</entry> + </row> + + <row> + <entry><makevar>OSVERSION</makevar></entry> + <entry>操作系统的版本号的数值形式； 它等于 + <link + linkend="freebsd-versions"><literal>__FreeBSD_version</literal></link>。</entry> + </row> + + <row> + <entry><makevar>PORTOBJFORMAT</makevar></entry> + <entry>系统默认的执行文件格式 + (<literal>elf</literal> 或 <literal>aout</literal>； + 请注意， <quote>现代的</quote> FreeBSD 版本中， + <literal>aout</literal> 已在淘汰之列。)</entry> + </row> + + <row> + <entry><makevar>LOCALBASE</makevar></entry> + <entry><quote>local</quote> 目录的根 (例如， + <literal>/usr/local/</literal>)</entry> + </row> + + <row> + <entry><makevar>X11BASE</makevar></entry> + <entry><quote>X11</quote> 目录的根 (例如， + <literal>/usr/X11R6</literal>)</entry> + </row> + + <row> + <entry><makevar>PREFIX</makevar></entry> + <entry>port 应被安装到哪里 (参见 <link + linkend="porting-prefix">关于 + <makevar>PREFIX</makevar> 的更多说明</link>)。</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <note> + <para>如果您需要定义 + <makevar>USE_IMAKE</makevar>， <makevar>USE_X_PREFIX</makevar>， 或 + <makevar>MASTERDIR</makevar> 这些变量， 则应在引用 + <filename>bsd.port.pre.mk</filename> 之前完成。</para> + </note> + + <para>下面是一些在引用 + <filename>bsd.port.pre.mk</filename> 之后可以进行的判断：</para> + + <programlisting># 如果 perl5 已经在系统中提供， 则不必编译 lang/perl5 +.if ${OSVERSION} > 300003 +BROKEN= perl is in system +.endif + +# ELF 只使用一个 shlib 版本 +.if ${PORTOBJFORMAT} == "elf" +TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR} +.else +TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}.${SHLIB_MINOR} +.endif + +# 软件会自动为 ELF 创建符号链接， 但 a.out 则需要另行创建 +post-install: +.if ${PORTOBJFORMAT} == "aout" + ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so +.endif</programlisting> + + <para>您还记得应该在 + <literal>BROKEN=</literal> 和 + <literal>TCL_LIB_FILE=</literal> 后面使用制表符， + 而不是空格， 对吧？ <!-- smiley -->:-)</para> + </sect1> + + <sect1 id="dads-documentation"> + <title>安装附加的文档</title> + + <para>如果您的软件包含了标准的联机手册和 info 手册以外的文档， + 而且您认为它们对用户会有用， 请把这些文档安装到 + <filename><makevar>PREFIX</makevar>/share/doc</filename> 下。 + 和前面类似， 这也可以在 + <maketarget>post-install</maketarget> target 中完成。</para> + + <para>为您的 port 建立一个新的目录。 + 这个目录的名字应该反映它是属于哪个 port 的。 通常建议使用 + <makevar>PORTNAME</makevar>。 不过， 如果您认为不同版本的 port + 可能会同时安装， 也可以用完整的 + <makevar>PKGNAME</makevar>。</para> + + <para>另外， 应该让是否安装取决于变量 + <makevar>NOPORTDOCS</makevar> 的设置， 这样用户就能够在 + <filename>/etc/make.conf</filename> 中禁止安装它。 例如：</para> + + <programlisting>post-install: +.if !defined(NOPORTDOCS) + ${MKDIR} ${DOCSDIR} + ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${DOCSDIR} +.endif</programlisting> + + <para>这里是一些便于使用的变量， 以及它们在 + <filename>Makefile</filename> 中默认的展开方式：</para> + + <itemizedlist> + <listitem> + <para><makevar>DATADIR</makevar> 会展开成 + <filename><makevar>PREFIX</makevar>/share/<makevar>PORTNAME</makevar></filename>。</para> + </listitem> + + <listitem> + <para><makevar>DOCSDIR</makevar> 会展开成 + <filename><makevar>PREFIX</makevar>/share/doc/<makevar>PORTNAME</makevar></filename>。</para> + </listitem> + + <listitem> + <para><makevar>EXAMPLESDIR</makevar> 会展开成 + <filename><makevar>PREFIX</makevar>/share/examples/<makevar>PORTNAME</makevar></filename>。</para> + </listitem> + </itemizedlist> + + <para>这些变量也会被导出到 <makevar>PLIST_SUB</makevar> 中。 + 只要可能， 它们的值就将在那里以相对于 + <filename><makevar>PREFIX</makevar></filename> 的路径形式出现。 + 也就是说， <filename>share/doc/<makevar>PORTNAME</makevar></filename> + 在装箱单中默认情况下会替换掉 <literal>%%DOCSDIR%%</literal>， 等等。 + (更多的 <filename>pkg-plist</filename> 代换可以在 + <link linkend="porting-plist">这里</link> 找到。)</para> + + <para>所有的安装的文档文件和目录， + 都应在 <filename>pkg-plist</filename> 出现， 并且使用 + <literal>%%PORTDOCS%%</literal> 前缀， 例如：</para> + + <programlisting>%%PORTDOCS%%%%DOCSDIR%%/AUTHORS +%%PORTDOCS%%%%DOCSDIR%%/CONTACT +%%PORTDOCS%%@dirrm %%DOCSDIR%%</programlisting> + + <para>如果不想在 <filename>pkg-plist</filename> 中一一列举文档， port + 也可以设置 <makevar>PORTDOCS</makevar> 来列出所需要的那些文件的名称， + 以及希望加入到最终的装箱单中的 shell glob 模式。 + 这些名字应该是相对于 <makevar>DOCSDIR</makevar> 路径的。 + 因此， 使用了 <makevar>PORTDOCS</makevar> + 并且使用了非默认的位置来存放文档的 port， 应该相应地设置 + <makevar>DOCSDIR</makevar>。 如果目录被列到了 <makevar>PORTDOCS</makevar> + 中， 或和这个变量的 glob 模式匹配， 则其所有子目录下的文件和目录， + 也都会注册到最终的装箱单中。 如果指定了 <makevar>NOPORTDOCS</makevar>， + 则不应设置 <makevar>PORTDOCS</makevar>。 按照上面的方式， + 将文档安装到 <makevar>PORTDOCS</makevar> 中， 仍需由 port 本身来完成。 + 使用 <makevar>PORTDOCS</makevar> 的典型例子是：</para> + + <programlisting>.if !defined(NOPORTDOCS) + PORTDOCS= * +.endif</programlisting> + + <note> + <para>您也可以使用 <filename>pkg-message</filename> 这个文件， + 来在安装时显示一些信息。 参见 <link + linkend="porting-message">关于使用 + <filename>pkg-message</filename> 的这一节</link> 以了解进一步的详情。 + 需要说明的是， 并不需要把 <filename>pkg-message</filename> 加到 + <filename>pkg-plist</filename> 中。</para> + </note> + </sect1> + + <sect1 id="dads-subdirs"> + <title>子目录</title> + + <para>尽可能让 port 将它创建的文件， 放置到 + <makevar>PREFIX</makevar> 中正确的位置。 一些 port + 会把各式各样的东西混在一起， 并放到一个同名的目录中， 这是不对的。 + 另外， 许多 port 会把除了可执行文件、 头文件和联机手册之外的所有文件， + 全都一股脑地放到 <filename>lib</filename> 中， 这在和 BSD + 配合使用时会有问题。 多数文件， + 应被放到下列位置之一： <filename>etc</filename> + (安装/配置文件)、 <filename>libexec</filename> + (由系统内部调用的可执行文件)、 <filename>sbin</filename> + (为超级用户/管理员提供的可执行文件)、 <filename>info</filename> + (用于 info 浏览器的文档) 或 <filename>share</filename> + (平台无关的其他文件)。 请参见 &man.hier.7; 以了解进一步的详情； 针对 + <filename>/usr</filename> 的那些规则， 同样也适用于 + <filename>/usr/local</filename>。 例外情况是那些需要和 USENET + <quote>news</quote> 打交道的 port， 它们可以选择采用 + <filename><makevar>PREFIX</makevar>/news</filename> + 作为文件的目的地。</para> + </sect1> + + <sect1 id="porting-cleaning"> + <title>清理空目录</title> + + <para>一定要让您的 port 在卸载时进行清理。 + 这通常是通过为所有由 port 创建的目录增加一行 + <literal>@dirrm</literal> 来完成的。 请注意， 在删除父目录之前， + 需要首先删除子目录。</para> + + <programlisting> : +lib/X11/oneko/pixmaps/cat.xpm +lib/X11/oneko/sounds/cat.au + : +@dirrm lib/X11/oneko/pixmaps +@dirrm lib/X11/oneko/sounds +@dirrm lib/X11/oneko</programlisting> + + <para>然而， 有时 <literal>@dirrm</literal> 会在其他 port + 共用同一个子目录时给出错误。 您可以通过使用 <literal>@unexec</literal> + 来调用 <command>rmdir</command> 来达到删除空目录， + 而不给出警告的目的。</para> + + <programlisting>@unexec rmdir %D/share/doc/gimp 2>/dev/null || true</programlisting> + + <para>这样做既不会显示出错错误信息， 也不会导致 + &man.pkg.delete.1; 异常退出， 即使由于安装了其他 port 并使用 + <filename><makevar>PREFIX</makevar>/share/doc/gimp</filename> + 而导致它非空的时候也是如此。</para> + </sect1> + + <sect1 id="dads-uid-and-gids"> + <title>UID 和 GID</title> + + <para>如果您的 port 安装到系统上之前需要一些用户， + 请使用 <filename>pkg-install</filename> 脚本来调用 + <command>pw</command> 以便自动地创建它们。 请参见 + <filename role="package">net/cvsup-mirror</filename> 提供的例子。</para> + + <para>如果您的 port 需要与其编译成安装包时同样的用户/组 ID， + 则必须在 50 到 999 之间选择一个未用的 UID。 请参见 + <filename role="package">japanese/Wnn6</filename> 提供的例子。</para> + + <para>一定不要使用系统或其他 port 已经使用的 UID。</para> + + <para>下面是目前预留的 50 到 999 之间的 UID。</para> + + <!-- Please keep this list sorted by uid --> + <programlisting>bind:*:53:53:Bind Sandbox:/:/sbin/nologin +majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent +rdfdb:*:55:55:rdfDB Daemon:/var/db/rdfdb:/bin/sh +spamd:*:58:58:SpamAssassin user:/var/spool/spamd:/sbin/nologin +cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent +gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh +proxy:*:62:62:Packet Filter pseudo-user:/nonexistent:/nonexistent +uucp:*:66:66:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico +xten:*:67:67:X-10 daemon:/usr/local/xten:/nonexistent +pop:*:68:6:Post Office Owner (popper):/nonexistent:/sbin/nologin +wnn:*:69:7:Wnn:/nonexistent:/nonexistent +pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh +oracle:*:71:71::0:0:Oracle:/usr/local/oracle7:/sbin/nologin +ircd:*:72:72:IRC daemon:/nonexistent:/nonexistent +ircservices:*:73:73:IRC services:/nonexistent:/nonexistent +ifmail:*:75:66:Ifmail user:/nonexistent:/nonexistent +www:*:80:80:World Wide Web Owner:/nonexistent:/sbin/nologin +alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent +qmaild:*:82:81:QMail user:/var/qmail:/nonexistent +qmaill:*:83:81:QMail user:/var/qmail:/nonexistent +qmailp:*:84:81:QMail user:/var/qmail:/nonexistent +qmailq:*:85:82:QMail user:/var/qmail:/nonexistent +qmailr:*:86:82:QMail user:/var/qmail:/nonexistent +qmails:*:87:82:QMail user:/var/qmail:/nonexistent +mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin +vpopmail:*:89:89:VPop Mail User:/usr/local/vpopmail:/nonexistent +firebird:*:90:90:Firebird Database Administrator:/usr/local/firebird:/bin/sh +mailman:*:91:91:Mailman User:/usr/local/mailman:/sbin/nologin +gdm:*:92:92:GDM Sandbox:/:/sbin/nologin +jabber:*:93:93:Jabber Daemon:/nonexistent:/nonexistent +p4admin:*:94:94:Perforce admin:/usr/local/perforce:/sbin/nologin +interch:*:95:95:Interchange user:/usr/local/interchange:/sbin/nologin +squeuer:*:96:96:SQueuer Owner:/nonexistent:/bin/sh +mud:*:97:97:MUD Owner:/nonexistent:/bin/sh +msql:*:98:98:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh +rscsi:*:99:99:Remote SCSI:/usr/local/rscsi:/usr/local/sbin/rscsi +squid:*:100:100:squid caching-proxy pseudo user:/usr/local/squid:/sbin/nologin +quagga:*:101:101:Quagga route daemon pseudo user:/usr/local/etc/quagga:/sbin/nologin +ganglia:*:102:102:Ganglia User:/nonexistent:/sbin/nologin +sgeadmin:*:103:103:Sun Grid Engine Admin:/nonexistent:/sbin/nologin +slimserv:*:104:104:Slim Devices SlimServer pseudo-user:/nonexistent:/sbin/nologin +dnetc:*:105:105:distributed.net client and proxy pseudo-user:/nonexistent:/sbin/nologin +clamav:*:106:106:Clamav Antivirus:/nonexistent:/sbin/nologin +cacti:*:107:107:Cacti Sandbox:/nonexistent:/sbin/nologin +webkit:*:108:108:WebKit Default User:/usr/local/www/webkit:/bin/sh +quickml:*:109:109:quickml Server:/nonexistent:/sbin/nologin +vscan:*:110:110:Scanning Virus Account:/var/amavis:/bin/sh +fido:*:111:111:Fido System:/usr/local/fido:/bin/sh +dcc:*:112:112:Distributed Checksum Clearinghouse:/nonexistent:/sbin/nologin +amavis:*:113:113:Amavis-stats Account:/nonexistent:/sbin/nologin +dhis:*:114:114:DHIS Daemon:/nonexistent:/sbin/nologin +_symon:*:115:115:Symon Account:/var/empty:/sbin/nologin +postfix:*:125:125:Postfix Mail System:/var/spool/postfix:/sbin/nologin +rbldns:*:153:153:rbldnsd pseudo-user:/nonexistent:/sbin/nologin +sfs:*:171:171:Self-Certifying File System:/nonexistent:/sbin/nologin +agk:*:172:172:AquaGateKeeper:/nonexistent:/nonexistent +polipo:*:173:173:polipo web cache:/nonexistent:/sbin/nologin +bogomilter:*:174:174:milter-bogom:/nonexistent:/sbin/nologin +moinmoin:*:192:192:MoinMoin User:/nonexistent:/sbin/nologin +sympa:*:200:200:Sympa Owner:/nonexistent:/sbin/nologin +dspam:*:202:202:Dspam:/nonexistent:/sbin/nologin +_tor:*:256:256:Tor anonymising router:/var/db/tor:/bin/sh +ldap:*:389:389:OpenLDAP Server:/nonexistent:/sbin/nologin +drweb:*:426:426:Dr.Web Mail Scanner:/nonexistent:/sbin/nologin +courier:*:465:465:Courier Mail Server:/nonexistent:/sbin/nologin +_bbstored:*:505:505::0:0:BoxBackup Store Daemon:/nonexistent:/bin/sh +qtss:*:554:554:Darwin Streaming Server:/nonexistent:/sbin/nologin +ircdru:*:555:555:Russian hybrid IRC server:/nonexistent:/bin/sh +messagebus:*:556:556:D-BUS Daemon User:/nonexistent:/sbin/nologin +bnetd:*:700:700:Bnetd user:/nonexistent:/sbin/nologin +bopm:*:717:717:Blitzed Open Proxy Monitor:/nonexistent:/bin/sh +bacula:*:910:910:Bacula Daemon:/var/db/bacula:/sbin/nologin</programlisting> + + <para>下面是目前预留的 GID。</para> + + <!-- Please keep this list sorted by gid --> + <!-- XXX incomplete! --> + <programlisting>bind:*:53: +rdfdb:*:55: +spamd:*:58: +cyrus:*:60: +proxy:*:62: +authpf:*:63: +uucp:*:66: +xten:*:67: +dialer:*:68: +network:*:69: +pgsql:*:70: +www:*:80: +qnofiles:*:81: +qmail:*:82: +mysql:*:88: +vpopmail:*:89: +firebird:*:90: +mailman:*:91: +gdm:*:92: +jabber:*:93: +p4admin:*:94: +interch:*:95: +squeuer:*:96: +mud:*:97: +msql:*:98: +rscsi:*:99: +squid:*:100: +quagga:*:101: +ganglia:*:102: +sgeadmin:*:103: +slimserv:*:104: +dnetc:*:105: +clamav:*:106: +cacti:*:107: +webkit:*:108: +quickml:*:109: +vscan:*:110: +fido:*:111: +dcc:*:112: +amavis:*:113: +dhis:*:114: +_symon:*:115: +postfix:*:125: +maildrop:*:126: +rbldns:*:153: +sfs:*:171: +agk:*:172: +polipo:*:173: +moinmoin:*:192: +sympa:*:200: +dspam:*:202: +_tor:*:256: +ldap:*:389: +drweb:*:426: +courier:*:465: +_bbstored:*:505: +qtss:*:554: +ircdru:*:555: +messagebus:*:556: +realtime:*:557: +bnetd:*:700: +bopm:*:717: +bacula:*:910:</programlisting> + + <para>如果您的 port 需要在这一范围内预留新的 UID 或 GID 的话， + 请在提交 (或升级) 时予以说明。 + 这样我们就能够让这份列表中的保留 ID 与现实同步了。</para> + </sect1> + + <sect1 id="dads-rational"> + <title>理性行事</title> + + <para>任何 <filename>Makefile</filename> 都应该简单并理性地行事。 + 如果您能让其中的条目更为简单和易读， 一定要这样做。 + 例如， 使用 make 提供的 + <literal>.if</literal> 结构， 而不要使用 shell 的 + <literal>if</literal>， 只要能重定义 + <makevar>EXTRACT*</makevar> 就不要重载 + <maketarget>do-extract</maketarget>， 尽量使用 + <makevar>GNU_CONFIGURE</makevar> 而不是 <literal>CONFIGURE_ARGS + += --prefix=${PREFIX}</literal>。</para> + + <para>如果您在尝试做什么事情的时候发现不得不写大量的代码， + 请回过头来复审一下 + <filename>bsd.port.mk</filename>， 看看是否有您正打算做的事情的现成实现。 + 尽管读起来可能很费劲， 但有很多貌似很难的问题， + 在 <filename>bsd.port.mk</filename> 中都给出了十分简便的解决方案。</para> + </sect1> + + <sect1 id="dads-cc"> + <title>遵循 <makevar>CC</makevar> 和 + <makevar>CXX</makevar> 设置</title> + + <para>port 应遵循 <makevar>CC</makevar> + 和 <makevar>CXX</makevar> 变量的设置。 + 这也就是说， port 不应使用绝对的方式来设置这个变量的值， + 而罔顾已经存在的设置； 与此相反， 它应该在其值后加入需要的其他值。 + 这样， 就可以设置全局的构建选项， 令其影响所有的 port 构建过程了。</para> + + <para>如果实在无法这样做， 请在 <filename>Makefile</filename> + 中加入 <literal>NO_PACKAGE=ignores + cflags</literal>。</para> + + <para>下面的 <filename>Makefile</filename> + 实例给出了如何遵循 <makevar>CC</makevar> 和 <makevar>CXX</makevar> + 变量的设置。 注意这里用到的 <makevar>?=</makevar>：</para> + + <programlisting>CC?= gcc</programlisting> + <programlisting>CXX?= g++</programlisting> + + <para>下面则是没有遵循 + <makevar>CC</makevar> 和 <makevar>CXX</makevar> + 的例子：</para> + + <programlisting>CC= gcc</programlisting> + <programlisting>CXX= g++</programlisting> + + <para>在 FreeBSD 系统中， + <makevar>CC</makevar> 和 <makevar>CXX</makevar> + 这两个变量都可以在 + <filename>/etc/make.conf</filename> 中自行定义。 + 第一个例子只有在 + <filename>/etc/make.conf</filename> 中没有定义时才对这两个变量进行定义， + 从而保持了系统范围的配置。 而第二个例子则会覆盖任何现有的配置。</para> + </sect1> + + <sect1 id="dads-cflags"> + <title>遵循 <makevar>CFLAGS</makevar></title> + + <para>您的 port 应遵循 <makevar>CFLAGS</makevar> 变量的设置。 + 这也就是说， port 不应使用绝对的方式来设置这个变量的值， + 而罔顾已经存在的设置； 与此相反， 它应该在其值后加入需要的其他值， + 这样， 就可以设置全局的构建选项， 令其影响所有的 port 构建过程了。</para> + + <para>如果实在无法这样做， 请在 <filename>Makefile</filename> + 中加入 <literal>NO_PACKAGE=ignores + cflags</literal>。</para> + + <para>下面的 <filename>Makefile</filename> 例子， + 可以帮助我们理解如何遵循 <makevar>CFLAGS</makevar> 的设置。 注意所用的 + <makevar>+=</makevar>：</para> + + <programlisting>CFLAGS+= -Wall -Werror</programlisting> + + <para>下面是一个未能遵循 + <makevar>CFLAGS</makevar> 设置的例子：</para> + + <programlisting>CFLAGS= -Wall -Werror</programlisting> + + <para>一般来说， <makevar>CFLAGS</makevar> 在 + FreeBSD 系统中是在 <filename>/etc/make.conf</filename> 里配置的。 + 第一个例子在 + <makevar>CFLAGS</makevar> 变量中增加了一些参数， + 并保持了所有系统预定义的标志。 而第二个例子， + 则会覆盖掉任何先前定义的参数。</para> + + <para>您应从第三方软件的 + <filename>Makefile</filename> 中去掉特殊的优化设置。 + 系统的 <makevar>CFLAGS</makevar> 给出了全系统范围内的优化设置参数。 + 下面是一个未经修改的 <filename>Makefile</filename> + 实例：</para> + + <programlisting>CFLAGS= -O3 -funroll-loops -DHAVE_SOUND</programlisting> + + <para>如果使用系统的优化参数， 则 + <filename>Makefile</filename> 中的设置应该类似下面这样：</para> + + <programlisting>CFLAGS+= -DHAVE_SOUND</programlisting> + + </sect1> + + <sect1 id="dads-config"> + <title>配置文件</title> + + <para>如果您的 port 需要在 + <filename><makevar>PREFIX</makevar>/etc</filename> 中保存配置文件， + <emphasis>不要</emphasis> 简单地安装它们并将其列入 + <filename>pkg-plist</filename>。 这将导致 + &man.pkg.delete.1; 删除用户精心编写的配置文件， + 而且新的安装也会把这些文件清除掉。</para> + + <para>因此， 您应把配置文件的例子按其他的后缀来安装 + (例如 <filename><replaceable>filename</replaceable>.sample</filename> + 就是一个不错的选择) 并显示一条 <link + linkend="porting-message">消息</link> + 告诉用户如何复制并编辑这个配置文件， 以便让软件能够正确工作。</para> + </sect1> + + <sect1 id="dads-freedback"> + <title>反馈</title> + + <para>如果进行了一些很好的修改和补丁， 一定要把它们发回给原作者， + 或维护者， 以便在下一版本的代码中包含它们。 + 这会让您在软件发布新版本的时候变得轻松一些。</para> + </sect1> + + <sect1 id="dads-readme"> + <title><filename>README.html</filename></title> + + <para>不要包含 <filename>README.html</filename> 文件。 + 这个文件并非 CVS 代码库中的一部分， 它是由 + <command>make readme</command> 命令生成的。 + </para> + </sect1> + + <sect1 id="dads-noinstall"> + <title>将 port 标记为 <makevar>BROKEN</makevar>， + <makevar>FORBIDDEN</makevar>， 或以其它方式阻止安装</title> + + <para>某些时候， 需要阻止用户安装某个 port。 + 例如， 有时可能某个 port 包含了某些安全漏洞， + 或彻底无法使用， 或基本上过时了， + 但由于某种原因仍然在代码库中 (以便有人能修好它们， 对吗？)。 + 想要告诉用户某个 port 不应被安装， 有许多可以在 port 的 + <filename>Makefile</filename> 中使用的 + <command>make</command> 变量。 下列 + <command>make</command> 的值， 将是在用户试图安装时得到的提示信息。 + 务请使用正确的 <command>make</command> 变量， + 因为每一个都表达了截然不同的意义， 而且许多自动化系统， 例如 + <link linkend="build-cluster">port 构建集群</link>、 + <link linkend="freshports">FreshPorts</link>， 以及 + <link linkend="portsmon">portsmon</link>， 都依赖于 + <filename>Makefile</filename> 的正确性。</para> + + <itemizedlist> + <listitem> + <para><makevar>BROKEN</makevar> 用来表示 port 无法编译或安装。 + 这将防止用户把时间浪费在安装这些 port 上。 + 构建集群仍然会尝试构建， + 以确认是否导致其无法编译的问题已经被解决。</para> + </listitem> + + <listitem> + <para><makevar>FORBIDDEN</makevar> 用于表示 ports 中包含安全漏洞， + 或者可能会给安装了这个 port 的 FreeBSD + 系统带来严重的安全隐患 (例如： 一个很不安全的程序， + 或包含了能够被轻易攻陷的服务的软件)。 如果发现了安全漏洞， + 而其作者没有发布升级版本， 则应立即把那个 + port 标记为 <makevar>FORBIDDEN</makevar>。 + 理想情况下， 包含安全漏洞的 port 应被尽快升级， + 以便减少包含漏洞的 FreeBSD 主机的数量 + (我们希望保持良好的安全记录)， 然而， + 有时在安全漏洞的披露和软件更新之间可能会有一个间隔， + 此时应予以说明。 除了安全之外， 请不要以任何其他理由将 port 标记为 + <makevar>FORBIDDEN</makevar>。</para> + </listitem> + + <listitem> + <para><makevar>IGNORE</makevar> 用来表示 port + 由于某些其他原因不应予以构建。 任何情况下， + 构建集群都不会构建标记为 + <makevar>IGNORE</makevar> 的 port。 以下是使用 + <makevar>IGNORE</makevar> 的一些例子：</para> + + <itemizedlist> + <listitem> + <para>能够编译但无法正常运行</para> + </listitem> + + <listitem> + <para>无法与运行的 &os; 版本一同工作</para> + </listitem> + + <listitem> + <para>构建时需要 &os; 内核的源代码， + 但用户没有安装它们</para> + </listitem> + + <listitem> + <para>由于授权原因， 必须手工下载 distfile</para> + </listitem> + + <listitem> + <para>无法与已经安装的某个 port 一同工作</para> + </listitem> + </itemizedlist> + + <note> + <para>如果 port 与某个已经安装的 + port 冲突， 则应 <link linkend="conflicts">使用 + <makevar>CONFLICTS</makevar> 来标记它</link>。 + <makevar>CONFLICTS</makevar> 将自动地设置 + <makevar>IGNORE</makevar>。</para> + </note> + + <para>如果 port 只应在某些平台上标记为 <makevar>IGNORE</makevar>， + 还有另外两个方便使用的 + <makevar>IGNORE</makevar> 变量可供选择： + <makevar>ONLY_FOR_ARCHS</makevar> 和 + <makevar>NOT_FOR_ARCHS</makevar>。 例如：</para> + + <programlisting>ONLY_FOR_ARCHS= i386 amd64</programlisting> + + <programlisting>NOT_FOR_ARCHS= alpha ia64 sparc64</programlisting> + </listitem> + + </itemizedlist> + + <para>一定要记得 <makevar>BROKEN</makevar> 和 + <makevar>FORBIDDEN</makevar> 只应作为当某个 port + 无法升级时的最终解决方案。 永久性地坏掉了的 port 应被从 ports tree + 中完全删除。</para> + + <para>需要时还可以使用 <makevar>DEPRECATED</makevar> + 和 <makevar>EXPIRATION_DATE</makevar> 来通知用户某个 port + 不应被使用， 并即将被删除。 前一个变量用来表达为什么计划删除 port； + 而后一个是则是一个 ISO 8601 格式的日期 (YYYY-MM-DD)。 + 两者都会向用户呈现。</para> + + <para>也可以设置 <makevar>DEPRECATED</makevar> + 而不给出 <makevar>EXPIRATION_DATE</makevar> (例如， + 建议使用某个新版本的 port)， 但反之则没有意义。</para> + + <para>目前还没有确切的关于需要给出多少通知的政策。 + 当前的实践是， 对于与安全有关的问题为一个月， + 而与构建有关的问题则为两个月。 这也让有兴趣的 committer + 能够有一点时间来修正问题。</para> + </sect1> + + <sect1 id="dads-workarounds"> + <title>一些必要的 workaround</title> + + <para>有时， 需要绕过一些较早版本的 &os; 中包含软件中的 bug。</para> + + <itemizedlist> + <listitem> + <para>某些版本的 &man.make.1; 在处理 <makevar>OSVERSION</makevar> + 的比较时存在问题， 至少对 4.8 和 5.0 是这样。 这经常会导致在 + <command>make describe</command> 时发生问题 (因而， + ports <command>make index</command> 也会无法正常工作)。 + 绕过这个问题的方法， 是在判断语句周围增加空格， 例如： + <programlisting>if ( ${OSVERSION} > 500023 )</programlisting> + 请小心， 在 4.9 或 5.2 上测试安装， + 是 <emphasis>不能</emphasis> 检测到这个问题的。</para> + </listitem> + + </itemizedlist> + + </sect1> + + <sect1 id="dads-misc"> + <title>杂记</title> + + <para>需要仔细地反复检查 + <filename>pkg-descr</filename> 和 <filename>pkg-plist</filename> + 这两个文件。 如果您正在复审一个 port， + 并认为这两个文件应该改进， 请一定要这样做。</para> + + <para>请不要在系统中复制多份 GNU General Public License。</para> + + <para>一定要非常小心地处理法律问题！ + 不要让我们发布没有得到合法授权的软件！</para> + </sect1> + + <sect1 id="dads-stuck"> + <title>如果遇到了问题…</title> + + <para>看一看现有的范例， 以及 + <filename>bsd.port.mk</filename> 文件， + 然后再考虑提问！ + <!-- smiley --><emphasis>;-)</emphasis></para> + + <para>如果遇到了麻烦一定要提问！ + 不要只是拿自己的头去撞墙！ <!-- smiley + --><emphasis>:-)</emphasis></para> + </sect1> + </chapter> + + <chapter id="porting-samplem"> + <title>示范的 <filename>Makefile</filename></title> + + <para>这里是一个您可以在建立新 port 时参考的 + <filename>Makefile</filename>。 请务必删除不需要的那些注释 + (方括号中间的文字)！</para> + + <para>建议您按照下面这样的格式 (变量顺序， 小节之间的空行等) 来编写。 + 这个格式的作用是便于查找重要的信息。 我们建议您使用 <link + linkend="porting-portlint">portlint</link> 来检查 + <filename>Makefile</filename>。</para> + + <programlisting>[头部... 主要是让我们更容易地分辨不同的 port。] +# New ports collection makefile for: xdvi +[版本这行， 只有在 PORTVERSION 变量不足以描述 port 时才需要] +# Date created: 26 May 1995 +[这是最初将软件移植到 FreeBSD 上的日期， 一般来说是建立这份 Makefile 的日期。 +请注意不要在之后再次修改这个日期。] +# Whom: Satoshi Asami <asami@FreeBSD.org> +# +# $FreeBSD$ +[ ^^^^^^^^^ 这是 CVS 在文件 commit 到我们的代码库时， 自动进行替换的 RCS ID。 +如果您正在升级 port， 不要把它改回 "$FreeBSD$"。 +CVS 会自动进行处理。] +# + +[这个小节描述 port 本身以及主要下载站点 - PORTNAME 和 PORTVERSION + 应放在最前面， 随后是 CATEGORIES， 然后是 MASTER_SITES， 接下来是 + MASTER_SITE_SUBDIR。 如果需要的话， 接下来应指定 + PKGNAMEPREFIX 和 PKGNAMESUFFIX。 随后是 DISTNAME， EXTRACT_SUFX， + 以及 DISTFILES， EXTRACT_ONLY， 如果需要的话。] +PORTNAME= xdvi +PORTVERSION= 18.2 +CATEGORIES= print +[如果不想使用 MASTER_SITE_* 宏， 一定不要忘记结尾的斜线 ("/")！] +MASTER_SITES= ${MASTER_SITE_XCONTRIB} +MASTER_SITE_SUBDIR= applications +PKGNAMEPREFIX= ja- +DISTNAME= xdvi-pl18 +[如果源代码包不是标准的 ".tar.gz" 形式， 就需要设置这个] +EXTRACT_SUFX= .tar.Z + +[分散的补丁 -- 可以为空] +PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/ +PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz + +[维护者(maintainer); *必须有*！ 这是某个用户在发现问题或报告 bug + 时可以联络的人 (最好有 commit 权限) - 这个人应该是 port， + 或某个可以把问题转发给最初 port 的那个人的人。 + 如果您真的不想在这里写自己的地址， 可以设置为 "ports@FreeBSD.org"。] +MAINTAINER= asami@FreeBSD.org +COMMENT= A DVI Previewer for the X Window System + +[依赖的其他软件包 -- 可以为空] +RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript +LIB_DEPENDS= Xpm.5:${PORTSDIR}/graphics/xpm + +[这节是其它不适合上几节的标准 bsd.port.mk 变量] +[如果需要在 configure、 build 或 install 过程中提问...] +IS_INTERACTIVE= yes +[如果解压缩到 ${DISTNAME} 以外的目录...] +WRKSRC= ${WRKDIR}/xdvi-new +[如果作者发布的补丁不是相对于 ${WRKSRC} 的， 可能需要调整这个] +PATCH_DIST_STRIP= -p1 +[如果需要运行由 GNU autoconf 生成的 "configure" 脚本] +GNU_CONFIGURE= yes +[如果需要使用 GNU make， 而不是 /usr/bin/make 来完成构建...] +USE_GMAKE= yes +[如果是一个 X 应用程序， 并使用 "xmkmf -a" 来运行...] +USE_IMAKE= yes +[et cetera.] + +[将在接下来的部分使用的非标准的变量] +MY_FAVORITE_RESPONSE= "yeah, right" + +[接下来是特殊规则， 按调用顺序排列] +pre-fetch: + i go fetch something, yeah + +post-patch: + i need to do something after patch, great + +pre-install: + and then some more stuff before installing, wow + +[结语] +.include <bsd.port.mk></programlisting> + </chapter> + + <chapter id="porting-autoplist"> + <title>装箱单 (package list) 的自动化制作</title> + + <para>首先， 请确认已经基本上完成了 port 的工作， 仅缺 + <filename>pkg-plist</filename>。</para> + + <para>接下来， 建立一个临时的目录， 以便于安装您的 port， + 首先在其中安装所有依赖的 port。 对于非 X 的 port， + <replaceable>port-type</replaceable> 应该是 <literal>local</literal>， + 而如果是一个 XFree86 4 或更早的 XFree 86 版本的 port， + 则应相应选择 <literal>x11-4</literal> 或 <literal>x11</literal>。</para> + + <screen>&prompt.root; <userinput>mkdir /var/tmp/<replaceable>port-name</replaceable></userinput> +&prompt.root; <userinput>mtree -U -f /etc/mtree/BSD.<replaceable>port-type</replaceable>.dist -d -e -p /var/tmp/<replaceable>port-name</replaceable></userinput> +&prompt.root; <userinput>make depends PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput></screen> + + <para>将目录结构保存到一个新文件中。</para> + + <screen>&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name</replaceable> && find -d * -type d) | sort > OLD-DIRS</userinput></screen> + + <para>建立一个空的 <filename>pkg-plist</filename> 文件：</para> + + <screen>&prompt.root; <userinput>touch pkg-plist</userinput></screen> + + <para>如果您的 port 依据 <makevar>PREFIX</makevar> 安装 (本应如此) + 则可以安装它并创建 package list。</para> + + <screen>&prompt.root; <userinput>make install PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput> +&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name</replaceable> && find -d * \! -type d) | sort > pkg-plist</userinput></screen> + + <para>您也可以把新增的目录加入到 packing list 中。</para> + + <screen>&prompt.root; <userinput>(cd /var/tmp/<replaceable>port-name</replaceable> && find -d * -type d) | sort | comm -13 OLD-DIRS - | sort -r | sed -e 's#^#@dirrm #' >> pkg-plist</userinput></screen> + + <para>最后， 需要手工整理 packing list； 这一过程不是 + <emphasis>完全</emphasis> 自动的。 联机手册应列入 port + 的 <filename>Makefile</filename> 的 + <makevar>MAN<replaceable>n</replaceable></makevar>， 而不是 + package list。 用户配置文件应被删除， 或以 + <filename><replaceable>filename</replaceable>.sample</filename> + 的名字来安装。 <filename>info/dir</filename> 文件， + 也不应列入， 同时应按照 <link linkend="porting-info">info + 文件</link> 的说明来增加一些 <filename>install-info</filename> 行。 + 所有由 port 安装的库， 应按照 + <link linkend="porting-shlibs">动态连接库</link> + 小节中介绍的方法处理。</para> + + <para>另外， 也可以使用 + <filename>/usr/ports/Tools/scripts/</filename> 中的 + <command>plist</command> 脚本来自动创建 + package list。 第一步和上面一样， 也就是 + <command>mkdir</command>， <command>mtree</command> 并 + <command>make depends</command>。 然后构建和安装 + port：</para> + + <screen>&prompt.root; <userinput>make install PREFIX=/var/tmp/<replaceable>port-name</replaceable></userinput></screen> + + <para>之后就可以用 <command>plist</command> 来建立 + <filename>pkg-plist</filename> 文件了：</para> + + <screen>&prompt.root; <userinput>/usr/ports/Tools/scripts/plist -Md -m /etc/mtree/BSD.<replaceable>port-type</replaceable>.dist /var/tmp/<replaceable>port-name</replaceable> > pkg-plist</userinput></screen> + + <para>同样地， 如此创建的 packing list 也需要手工地整理一下。</para> + + </chapter> + + <chapter id="keeping-up"> + <title>保持同步</title> + + <para>&os; 的 Ports Collection 在持续地进行修改。 + 这里提供了一些关于如何保持同步的信息。</para> + + <sect1 id="freshports"> + <title>FreshPorts</title> + + <para>最简单的了解已经被 commit 到 ports 中的更新的方法， 是订阅 + <ulink url="http://www.FreshPorts.org/">FreshPorts</ulink>。 + 您可以选择多个 ports 并对其进行监视。 强烈建议维护人员订阅它， + 这样就不仅能接收到他们自己所做的修改， 而且能看到其他 &os; + committer 所做的改动。 (保持与所依赖的 + ports 框架同步是必要的—虽然一般来说您会在这样的 commit + 之前收到一个礼貌性的通知， 但有时可能会有人没有注意到需要这样做， + 或者这样做很困难。 另外， 有些时候通知的修改也可能是微不足道的。 + 我们希望每一个人能够正确地进行判断。)</para> + + <para>如果想使用 FreshPorts， 之需要建立一个账号。 如果您注册的邮件地址是 + <literal>@FreeBSD.org</literal>， 您会看到 web 页面右侧的 opt-in + 连接。 如果您已经注册了 FreshPorts 账号， + 但没有使用 <literal>@FreeBSD.org</literal> 邮件地址， + 则只需把邮件地址改为 <literal>@FreeBSD.org</literal>， 重新订阅， + 并将其改回。</para> + + <para>FreshPorts 也会对每一个 FreeBSD ports tree 上的 commit + 进行自动的合法性检查。 如果您订阅了这项服务， 则如果发现了错误， + 就会收到来自 FreshPorts 的检测报告。</para> + </sect1> + + <sect1 id="cvsweb"> + <title>代码库的 Web 访问界面</title> + + <para>可以通过 web 界面来浏览源代码库中的文件。 + 影响整个 ports 系统的修改， 现在都会在 + <ulink url="http://cvsweb.FreeBSD.org/ports/CHANGES"> + CHANGES</ulink> 文件中说明。 影响某一个 port 的变动， 则在 + <ulink url="http://cvsweb.FreeBSD.org/ports/UPDATING"> + UPDATING</ulink> 文件中说明。 尽管如此， 所有问题最为权威的答案， + 毫无疑问应该是 <ulink + url="http://cvsweb.FreeBSD.org/ports/Mk/bsd.port.mk"> + bsd.port.mk</ulink> 的源代码， 以及相关的文件。</para> + + </sect1> + + <sect1 id="ports-mailling-list"> + <title>&os; Ports 邮件列表</title> + + <para>如果您维护了某个或某一些 ports， 则应该考虑订阅 + &a.ports;。 对于 ports 工作方式的重要修改都会在此宣示， + 并提交到 <filename>CHANGES</filename>。</para> + + </sect1> + + <sect1 id="build-cluster"> + <title>位于 <hostid role="hostname">pointyhat.FreeBSD.org</hostid> + 的 &os; Port 构建集群</title> + + <para>&os; 的一个最不为人所知的强项是， + 它拥有一个专用于持续构建 Ports Collection 的集群， + 这个集群会构建所有主要的 OS 版本在每一个 Tier-1 架构上的 package。 + 您可以在 + <ulink url="http://pointyhat.FreeBSD.org/">package + 构建和错误日志</ulink> 找到其结果。</para> + + <para>每一个 port 都会被构建， + 除非标记为 <makevar>IGNORE</makevar>。 + 标记了 <makevar>BROKEN</makevar> 的 port 仍然会被继续尝试， + 以了解是否某些依赖关系的变动解决了其问题 + (这是通过给 port 的 <filename>Makefile</filename> 传 + <makevar>TRYBROKEN</makevar> 参数来完成的)。</para> + + </sect1> + + <sect1 id="distfile-survey"> + <title>&os; 的 Port Distfile 普查</title> + + <para>构建集群是一组专门用于构建所有 ports 的最新的版本的机器， + 其上已经下载所有的 distfile。 然而， 由于 Internet 在持续地发生变化， + distfile 可能很快就消失了。 <ulink + url="http://people.FreeBSD.org/~fenner/portsurvey/">FreeBSD + Ports distfiles 普查</ulink> 试图查询每一个 port 的所有下载站点， + 以期找出这些文件是否依然存在。 维护者应规律性地检查这些报告， + 这不仅会提高用户构建的速度， 同时也避免了浪费那些镜像了全部 + distfile 的志愿者的带宽。</para> + + </sect1> + + <sect1 id="portsmon"> + + <title>&os; 的 Ports 追踪系统</title> + + <para>另一个非常方便的资源， 就是 + <ulink url="http://portsmon.firepipe.net"> + FreeBSD Ports 追踪系统</ulink> (也被称作 + <literal>portsmon</literal>)。 + 这个系统包含了一个处理若干信息来源的数据库， + 并提供了一个可以通过 web 方式浏览的界面。 目前， + 它利用到了和 ports 有关的问题报告 (PR)、 来自构建集群的错误日志， + 以及来自 Ports Collection 的文件所提供的信息。 + 未来， 还会对它进行进一步的扩展， 从而提供包括 distfile 普查， + 以及其他来源在内的更多信息。</para> + + <para>要使用这个工具， 可以从查看关于某一个 port 的全部资料的 + <ulink url="http://portsmon.firepipe.net/portoverview.py"> + Port 的纵览</ulink> 开始。</para> + + <para>本文撰写时, 这是唯一一个能够将 GNATS PR 项， + 同对应的 port 名字映射起来的资源。 (提交 PR 的用户， + 有时并不在 Synopsis (概要) 中指明 port 的名字， + 尽管我们希望他们这样做)。 因此， <literal>portsmon</literal> + 在您想要查找是否有人提交某个现存的 port 的 PR， + 以及它的构建是否出现了错误； 或在您创建新的 port + 之前想要查找一下是否已经有人提交过时， 就非常有用了。</para> + </sect1> + + </chapter> +</book> + +<!-- + Local Variables: + mode: sgml + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + End: +--> diff --git a/zh_CN.GB2312/books/porters-handbook/freebsd.dsl b/zh_CN.GB2312/books/porters-handbook/freebsd.dsl new file mode 100644 index 0000000000..6af6d357aa --- /dev/null +++ b/zh_CN.GB2312/books/porters-handbook/freebsd.dsl @@ -0,0 +1,45 @@ +<!-- + The FreeBSD Simplified Chinese Project + + Original Revision: 1.5 + $FreeBSD$ +--> + +<!-- Local DSSSL file for the Porter's Handbook. This is so we can include + a link to the -ports mailing list at the bottom of the HTML files, + rather than the -questions mailing list. --> + +<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [ +<!ENTITY freebsd.dsl SYSTEM "../../share/sgml/freebsd.dsl" CDATA DSSSL> +<!ENTITY % output.html "IGNORE"> +]> + +<style-sheet> + <style-specification use="docbook"> + <style-specification-body> + + <![ %output.html; [ + (define ($email-footer$) + (make sequence + (literal "若您有关于 FreeBSD ports 系统的问题， 请发送电子邮件至 <") + (create-link (list (list "HREF" "mailto:ports@FreeBSD.org")) + (literal "ports@FreeBSD.org")) + (literal ">。") + (make empty-element gi: "br") + (literal "关于此文档的人和问题， 请致函 <") + (create-link (list (list "HREF" "mailto:doc@FreeBSD.org")) + (literal "doc@FreeBSD.org")) + (literal ">。"))) + + <!-- Convert " ... " to `` ... '' in the HTML output. --> + (element quote + (make sequence + (literal "``") + (process-children) + (literal "''"))) + ]]> + </style-specification-body> + </style-specification> + + <external-specification id="docbook" document="freebsd.dsl"> +</style-sheet> |