diff --git a/en/handbook/advanced-networking/chapter.sgml b/en/handbook/advanced-networking/chapter.sgml
index 4fbe1987b1..4f00275b26 100644
--- a/en/handbook/advanced-networking/chapter.sgml
+++ b/en/handbook/advanced-networking/chapter.sgml
@@ -976,9 +976,7 @@ ISDN BRI line</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/authors.ent b/en/handbook/authors.ent
index a8c95c2ac6..80e0daca31 100644
--- a/en/handbook/authors.ent
+++ b/en/handbook/authors.ent
@@ -7,7 +7,7 @@
Please keep this list in alphabetical order by entity names.
- $Id: authors.ent,v 1.3 1998-11-12 01:26:17 nik Exp $
+ $Id: authors.ent,v 1.4 1998-12-10 20:43:39 nik Exp $
-->
<!ENTITY a.abial "Andrzej Bialecki <email>abial@FreeBSD.ORG</email>">
@@ -30,10 +30,12 @@
<!ENTITY a.awebster "Andrew Webster <email>awebster@pubnix.net</email>">
-<!ENTITY a.brandon "Brandon Gillespie <email>brandon@FreeBSD.ORG</email>">
-
<!ENTITY a.bde "Bruce Evans <email>bde@FreeBSD.ORG</email>">
+<!ENTITY a.billf "Bill Fumerola <email>billf@FreeBSD.ORG</email>">
+
+<!ENTITY a.brandon "Brandon Gillespie <email>brandon@FreeBSD.ORG</email>">
+
<!ENTITY a.brian "Brian Somers <email>brian@FreeBSD.ORG</email>">
<!ENTITY a.cawimm "Charles A. Wimmer <email>cawimm@FreeBSD.ORG</email>">
@@ -88,6 +90,8 @@
<!ENTITY a.fenner "Bill Fenner <email>fenner@FreeBSD.ORG</email>">
+<!ENTITY a.flathill "Seiichirou Hiraoka <email>flathill@FreeBSD.ORG</email>">
+
<!ENTITY a.fsmp "Steve Passe <email>fsmp@FreeBSD.ORG</email>">
<!ENTITY a.gclarkii "Gary Clark II <email>gclarkii@FreeBSD.ORG</email>">
@@ -98,6 +102,8 @@
<!ENTITY a.gibbs "Justin T. Gibbs <email>gibbs@FreeBSD.ORG</email>">
+<!ENTITY a.mjacob "Matthew Jacob <email>mjacob@FreeBSD.ORG</email>">
+
<!ENTITY a.gj "Gary Jennejohn <email>gj@FreeBSD.ORG</email>">
<!ENTITY a.gpalmer "Gary Palmer <email>gpalmer@FreeBSD.ORG</email>">
@@ -218,6 +224,8 @@
<!ENTITY a.nectar "Jacques Vidrine <email>nectar@FreeBSD.ORG</email>">
+<!ENTITY a.nhibma "Nick Hibma <email>n_hibma@FreeBSD.ORG</email>">
+
<!ENTITY a.nik "Nik Clayton <email>nik@FreeBSD.ORG</email>">
<!ENTITY a.nsj "Nate Johnson <email>nsj@FreeBSD.ORG</email>">
@@ -258,6 +266,8 @@
<!ENTITY a.rse "Ralf S. Engelschall <email>rse@FreeBSD.ORG</email>">
+<!ENTITY a.sada "Kenji SADA <email>sada@FreeBSD.ORG</email>">
+
<!ENTITY a.scrappy "Marc G. Fournier <email>scrappy@FreeBSD.ORG</email>">
<!ENTITY a.se "Stefan Esser <email>se@FreeBSD.ORG</email>">
@@ -288,6 +298,8 @@
<!ENTITY a.torstenb "Torsten Blum <email>torstenb@FreeBSD.ORG</email>">
+<!ENTITY a.truckman "Don “Truck” Lewis <email>truckman@FreeBSD.ORG</email>">
+
<!ENTITY a.ugen "Ugen J.S.Antsilevich <email>ugen@FreeBSD.ORG</email>">
<!ENTITY a.uhclem "Frank Durda IV <email>uhclem@FreeBSD.ORG</email>">
@@ -296,6 +308,8 @@
<!ENTITY a.vanilla "Vanilla I. Shu <email>vanilla@FreeBSD.ORG</email>">
+<!ENTITY a.wes "Wes Peters <email>wes@FreeBSD.ORG</email>">
+
<!ENTITY a.whiteside "Don Whiteside <email>whiteside@acm.org</email>">
<!ENTITY a.wilko "Wilko Bulte <email>wilko@yedi.iaf.nl</email>">
diff --git a/en/handbook/basics/chapter.sgml b/en/handbook/basics/chapter.sgml
index 574ee8a3f7..761f1146f4 100644
--- a/en/handbook/basics/chapter.sgml
+++ b/en/handbook/basics/chapter.sgml
@@ -141,9 +141,7 @@
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/bibliography/chapter.sgml b/en/handbook/bibliography/chapter.sgml
index 429b519caf..a549e0ca67 100644
--- a/en/handbook/bibliography/chapter.sgml
+++ b/en/handbook/bibliography/chapter.sgml
@@ -499,9 +499,7 @@ url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/boothelp.sgml b/en/handbook/boothelp.sgml
new file mode 100644
index 0000000000..f148c86296
--- /dev/null
+++ b/en/handbook/boothelp.sgml
@@ -0,0 +1,46 @@
+<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN" [
+<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters;
+<!ENTITY % authors SYSTEM "authors.ent"> %authors;
+<!ENTITY % mailing-lists SYSTEM "mailing-lists.ent"> %mailing-lists;
+
+<!ENTITY % boothelp.only "INCLUDE">
+<!ENTITY % handbook.only "IGNORE">
+
+<!ENTITY rel.current CDATA "3.0">
+]>
+
+<book>
+ <bookinfo>
+ <title>FreeBSD Installation</title>
+
+ <abstract>
+ <para>Welcome to FreeBSD! This guide describes the FreeBSD installation
+ process. To navigate through through the section in this guide using
+ the <emphasis>up</emphasis> and <emphasis>down</emphasis> arrow keys
+ to select the section you wish to read. THen use the <emphasis>right
+ arrow</emphasis> or the <emphasis>enter key</emphasis> to view the
+ section. You can backtract through section you have read by using the
+ <emphasis>left arrow</emphasis>.</abstract>
+ </abstract>
+ </bookinfo>
+
+ <part>
+ <title>General information</title>
+
+ &chap.introduction;
+ &chap.install;
+ &chap.basics;
+ &chap.eresources;
+ &chap.hw;
+ &chap.contrib;
+ </part>
+</book>
+
+<!--
+ Local Variables:
+ mode: sgml
+ sgml-indent-data: t
+ sgml-omittag: nil
+ sgml-always-quote-attributes: t
+ End:
+-->
diff --git a/en/handbook/contrib/chapter.sgml b/en/handbook/contrib/chapter.sgml
index c04d625c12..2dffa913a2 100644
--- a/en/handbook/contrib/chapter.sgml
+++ b/en/handbook/contrib/chapter.sgml
@@ -1,5 +1,4 @@
-
- <chapter id="contrib">
+<chapter id="contrib">
<title>Contributing to FreeBSD</title>
<para><emphasis>Contributed by &a.jkh;.</emphasis></para>
@@ -724,2529 +723,7 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</sect2>
- <sect2 id="porting">
- <title>Porting an existing piece of free software</title>
-
- <para><emphasis>Contributed by &a.jkh;, &a.gpalmer;, &a.asami; and
- &a.obrien;.<!-- <br> -->28 August 1996.</emphasis></para>
-
- <para>The porting of freely available software, while perhaps not as
- gratifying as developing your own from scratch, is still a vital
- part of FreeBSD's growth and of great usefulness to those who
- would not otherwise know where to turn for it. All ported
- software is organized into a carefully organized hierarchy known
- as “the ports collection”. The collection enables a new user to
- get a quick and complete overview of what is available for FreeBSD
- in an easy-to-compile form. It also saves considerable space by
- not actually containing the majority of the sources being ported,
- but merely those differences required for running under FreeBSD.</para>
-
- <para>What follows are some guidelines for creating a new port for
- FreeBSD. The bulk of the work is done by
- <filename>/usr/share/mk/bsd.port.mk</filename>, which all port
- Makefiles include. Please refer to that file for more details on
- the inner workings of the ports collection. Even if you don't
- hack Makefiles daily, it is well commented, and you will still
- gain much knowledge from it.</para>
-
-
- <sect3 id="porting-starting">
- <title>Before Starting the Port</title>
- <note>
- <para>Only a fraction of the overridable variables
- are mentioned in
- this document. Most (if not all) are documented at the start
- of <filename>bsd.port.mk</filename>. This file uses a
- non-standard tab setting. <command>Emacs</command> and
- <command>Vim</command> should recognize the setting on loading
- the file. <command>vi</command> or <command>ex</command> can
- be set to using the correct value by typing <literal>:set
- tabstop=4</literal> once the file has been loaded.</para>
- </note>
-
- <para>You may come across code that needs modifications or
- conditional compilation based upon what version of UNIX it is
- running under. If you need to make such changes to the code for
- conditional compilation, make sure you make the changes as
- general as possible so that we can back-port code to FreeBSD 1.x
- systems and cross-port to other BSD systems such as 4.4BSD from
- CSRG, BSD/386, 386BSD, NetBSD, and OpenBSD.</para>
-
- <para>The preferred way to tell 4.3BSD/Reno (1990) and newer
- versions of the BSD code apart is by using the
- <acronym>BSD</acronym> macro defined in
- <filename><sys/param.h></filename>. Hopefully that file
- is already included; if not, add the code:</para>
-
- <programlisting>
-#if (defined(__unix__) || defined(unix)) && !defined(USG)
-#include <sys/param.h>
-#endif</programlisting>
-
- <para>to the proper place in the <filename>.c</filename> file. We
- believe that every system that defines these to symbols has
- <filename>sys/param.h</filename>. If you find a system that
- doesn't, we would like to know. Please send mail to
- &a.ports;.</para>
-
- <para>Another way is to use the GNU Autoconf style of doing
- this:</para>
-
- <programlisting>
-#ifdef HAVE_SYS_PARAM_H
-#include <sys/param.h>
-#endif</programlisting>
-
- <para>Don't forget to add <literal>-DHAVE_SYS_PARAM_H</literal> to
- the <makevar>CFLAGS</makevar> in the Makefile for this
- method.</para>
-
- <para>Once you have <filename>sys/param.h</filename>
- included, you may use:</para>
-
- <programlisting>
-#if (defined(BSD) && (BSD >= 199103))</programlisting>
-
- <para>to detect if the code is being compiled on a 4.3 Net2 code
- base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD,
- BSD/386 1.1 and below).</para>
-
- <para>Use:</para>
-
- <programlisting>
-#if (defined(BSD) && (BSD >= 199306))</programlisting>
-
- <para>to detect if the code is being compiled on a 4.4 code base
- or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or
- above).</para>
-
- <para>The value of the BSD macro is 199506 for the 4.4BSD-Lite2
- code base. This is stated for informational purposes only. It
- should not be used to distinguish between version of FreeBSD
- based only on 4.4-Lite vs. versions that have merged in changes
- from 4.4-Lite2. The __FreeBSD__ macro should be used
- instead.</para>
-
- <para>Use sparingly:</para>
-
-
- <itemizedlist>
-
- <listitem>
- <para><literal>__FreeBSD__</literal> is defined in all
- versions of FreeBSD. Use it if the change you are making
- ONLY affects FreeBSD. Porting gotchas like the use of
- <literal>sys_errlist[]</literal> vs
- <function>strerror()</function> are Berkeleyisms, not
- FreeBSD changes.</para>
- </listitem>
-
- <listitem>
- <para>In FreeBSD 2.x, <literal>__FreeBSD__</literal> is
- defined to be <literal>2</literal>. In earlier
- versions, it is <literal>1</literal>. Later
- versions will bump it to match their major version number.</para>
- </listitem>
-
- <listitem>
- <para>If you need to tell the difference between a FreeBSD
- 1.x system and a FreeBSD 2.x or 3.x system, usually the
- right answer is to use the <acronym>BSD</acronym> macros
- described above. If there actually is a FreeBSD specific
- change (such as special shared library options when using
- <command>ld</command>) then it is OK to use
- <literal>__FreeBSD__</literal> and <literal>#if
- __FreeBSD__ > 1</literal> to detect a FreeBSD 2.x
- and later system. If you need more granularity in
- detecting FreeBSD systems since 2.0-RELEASE you can use
- the following:</para>
-
- <programlisting>
-#if __FreeBSD__ >= 2
-#include <osreldate.h>
-# if __FreeBSD_version >= 199504
- /* 2.0.5+ release specific code here */
-# endif
-#endif</programlisting>
-
- <informaltable frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Release</entry>
- <entry><literal>_FreeBSD_version</literal></entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>2.0-RELEASE</entry>
- <entry>119411</entry>
- </row>
-
- <row>
- <entry>2.1-currents</entry>
- <entry>199501, 199503</entry>
- </row>
-
- <row>
- <entry>2.0.5-RELEASE</entry>
- <entry>199504</entry>
- </row>
-
- <row>
- <entry>2.2-current before 2.1</entry>
- <entry>199508</entry>
- </row>
-
- <row>
- <entry>2.1.0-RELEASE</entry>
- <entry>199511</entry>
- </row>
-
- <row>
- <entry>2.2-current before 2.1.5</entry>
- <entry>199512</entry>
- </row>
-
- <row>
- <entry>2.1.5-RELEASE</entry>
- <entry>199607</entry>
- </row>
-
- <row>
- <entry>2.2-current before 2.1.6</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 (no change)</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after 2.2.1-RELEASE</entry>
- <entry>220000 (no change)</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after texinfo-3.9</entry>
- <entry>221001</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after top</entry>
- <entry>221002</entry>
- </row>
-
- <row>
- <entry>2.2.2-RELEASE</entry>
- <entry>222000</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after 2.2.2-RELEASE</entry>
- <entry>222001</entry>
- </row>
-
- <row>
- <entry>2.2.5-RELEASE</entry>
- <entry>225000</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after 2.2.5-RELEASE</entry>
- <entry>225001</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after ldconfig -R merge</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-STABLE after 2.2.7-RELEASE</entry>
- <entry>227001</entry>
- </row>
-
- <row>
- <entry>3.0-current before mount(2) change</entry>
- <entry>300000</entry>
- </row>
-
- <row>
- <entry>3.0-current as of November 1996</entry>
- <entry>300001</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </listitem>
- </itemizedlist>
-
- <note>
- <para>Note that 2.2-STABLE sometimes identifies itself as
- “2.2.5-STABLE” after the 2.2.5-RELEASE. The pattern used to
- be year followed by the month, but we decided to change it
- to a more straightforward major/minor system starting from
- 2.2. This is because the parallel development on several
- branches made it infeasible to classify the releases simply
- by their real release dates. If you are making a port now,
- you don't have to worry about old -current's; they are
- listed here just for your reference.</para>
- </note>
-
-
- <para>In the hundreds of ports that have been done, there have
- only been one or two cases where <literal>__FreeBSD__</literal>
- should have been used. Just because an earlier port screwed up
- and used it in the wrong place does not mean you should do so
- too.</para>
-
- </sect3>
-
- <sect3>
- <title>Quick Porting</title>
-
- <para>This section tells you how to do a quick port. In many
- cases, it is not enough, but we will see.</para>
-
- <para>First, get the original tarball and put it into <makevar>DISTDIR</makevar>, which defaults to
- <filename>/usr/ports/distfiles</filename>.</para>
-
- <note>
- <para>The following assumes that the software compiled
- out-of-the-box, i.e., there was absolutely no change required
- for the port to work on your FreeBSD box. If you needed to
- change something, you will have to refer to the next section
- too.</para>
- </note>
-
- <sect4>
- <title>Writing the <filename>Makefile</filename></title>
-
- <para>The minimal <filename>Makefile</filename> would
- look something like this:</para>
-
- <programlisting>
-# New ports collection makefile for: oneko
-# Version required: 1.1b
-# Date created: 5 December 1994
-# Whom: asami
-#
-# $Id$
-#
-
-DISTNAME= oneko-1.1b
-CATEGORIES= games
-MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
-
-MAINTAINER= asami@FreeBSD.ORG
-
-MAN1= oneko.1
-MANCOMPRESSED= yes
-USE_IMAKE= yes
-
-.include <bsd.port.mk></programlisting>
-
- <para>See if you can figure it out. Do not worry about the
- contents of the <literal>$Id$</literal>
- line, it will be filled in automatically by CVS when the port
- is imported to our main ports tree. You can find a more
- detailed example in the <link
- linkend="porting-samplem">sample Makefile</link>
- section.</para>
-
- </sect4>
-
- <sect4>
- <title>Writing the description files</title>
-
- <para>There are three required description files that are
- required for any port, whether they actually package or not.
- They are <filename>COMMENT</filename>,
- <filename>DESCR</filename>, and <filename>PLIST</filename>,
- and reside in the <filename>pkg</filename>
- subdirectory.</para>
-
-
- <sect5>
- <title><filename>COMMENT</filename></title>
-
- <para>This is the one-line description of the port.
- <emphasis>Please</emphasis> do not include the package name (or version
- number of the software) in the comment. Here is
- an example:</para>
-
- <programlisting>
-A cat chasing a mouse all over the screen.</programlisting>
-
- </sect5>
-
- <sect5>
- <title><filename>DESCR</filename></title>
-
- <para>This is a longer description of the port. One to a few
- paragraphs concisely explaining what the port does is
- sufficient.</para>
-
- <note>
- <para>This is <emphasis>not</emphasis> a manual or an
- in-depth description on how to use or compile the port!
- <emphasis>Please be careful if you are copying from the
- <filename>README</filename> or manpage</emphasis>; too often
- they are not a concise description of the port or are in an
- awkward format (e.g., manpages have justified spacing). If the
- ported software has an official WWW homepage, you should list
- it here.</para>
- </note>
-
- <para>It is recommended that you sign the name at the end of
- this file, as in:</para>
-
- <programlisting>
-This is a port of oneko, in which a cat chases a poor mouse all over
-the screen.
- :
-(etc.)
-
-http://www.oneko.org/
-
-- Satoshi
-asami@cs.berkeley.edu</programlisting>
-
- </sect5>
-
- <sect5>
- <title><filename>PLIST</filename></title>
-
- <para>This file lists all the files installed by the port. It
- is also called the `packing list' because the package is
- generated by packing the files listed here. The pathnames
- are relative to the installation prefix (usually
- <filename>/usr/local</filename> or
- <filename>/usr/X11R6</filename>). If you are using the
- <makevar>MAN<replaceable>n</replaceable></makevar> variables (as
- you should be), do not list any manpages here.</para>
-
- <para>Here is a small example:</para>
-
- <programlisting>
-bin/oneko
-lib/X11/app-defaults/Oneko
-lib/X11/oneko/cat1.xpm
-lib/X11/oneko/cat2.xpm
-lib/X11/oneko/mouse.xpm</programlisting>
-
- <para>Refer to the <citerefentry><refentrytitle>pkg_create</refentrytitle><manvolnum>1</manvolnum></citerefentry> man page
- for details on the packing list.</para>
-
- </sect5>
- </sect4>
-
- <sect4>
- <title>Creating the checksum file</title>
-
- <para>Just type <command>make makesum</command>.
- The ports make rules will automatically generate the file
- <filename>files/md5</filename>.</para>
-
- </sect4>
-
- <sect4>
- <title>Testing the port</title>
-
- <para>You should make sure that the port rules do exactly what
- you want it to do, including packaging up the port. Try doing
- <command>make install</command>, <command>make package</command> and then <command>make deinstall</command> and see if all the files
- and directories are correctly deleted. Then do a <command>pkg_add `make package-name`.tgz</command> and see
- if everything re-appears and works correctly. Then do another
- <command>make deinstall</command> and then
- <command>make reinstall; make package</command>
- to make sure you haven't included in the packing list any
- files that are not installed by your port.</para>
-
- </sect4>
-
- <sect4 id="porting-submitting">
- <title>Submitting the port</title>
-
- <para>First, make sure you have read the <link
- linkend="porting-dads">Do's and Dont's</link> section.</para>
-
- <para>Now that you are happy with your port, the only thing
- remaining is to put it in the main FreeBSD ports tree and make
- everybody else happy about it too. We do not need your
- <filename>work</filename> directory or the
- <filename>pkgname.tgz</filename> package, so delete them
- now. Next, simply include the output of <command>shar `find
- port_dir`</command> in a bug report and send it with the
- <citerefentry>
- <refentrytitle>send-pr</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> program. If the uncompressed port is larger than
- 20KB, you should compress it into a tarfile and use <citerefentry>
- <refentrytitle>uuencode</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> before including it in the bug report (uuencoded
- tarfiles are acceptable even if the bug report is smaller than
- 20KB but are not preferred). Be sure to classify the bug report as
- category <literal>ports</literal> and class
- <literal>change-request</literal>.</para>
-
- <para>One more time, <emphasis>do not include the original source
- distfile, the <filename>work</filename> directory, or the
- package you built with <command>make
- package</command></emphasis>.</para>
-
- <para>See <link linkend="contrib-general">Bug Reports and General
- Commentary</link> for more information.</para>
-
- <para>We will look at your port,
- get back to you if necessary, and put it in the
- tree. Your name will also appear in the list of “Additional
- FreeBSD contributors” on the FreeBSD Handbook and other files.
- Isn't that great?!? <!-- smiley -->:)</para>
-
- </sect4>
- </sect3>
-
- <sect3>
- <title>Slow Porting</title>
-
- <para>Ok, so it was not that simple, and the port required some
- modifications to get it to work. In this section, we will
- explain, step by step, how to modify it to get it to work with
- the ports paradigm.</para>
-
-
- <sect4>
- <title>How things work</title>
-
- <para>First, this is the sequence of events which occurs when
- the user first types <command>make</command> in
- your port's directory, and you may find that having
- <filename>bsd.port.mk</filename> in another window while you
- read this really helps to understand it.</para>
-
- <para>But do not worry if you do not really understand what
- <filename>bsd.port.mk</filename> is doing, not many people
- do... <!-- smiley --><emphasis>:></emphasis></para>
-
-
- <procedure>
-
- <step>
- <para>The <maketarget>fetch</maketarget> target is run. The <maketarget>fetch</maketarget> target is
- responsible for making sure that the tarball exists
- locally in <makevar>DISTDIR</makevar>.
- If <maketarget>fetch</maketarget> cannot find the required files in <makevar>DISTDIR</makevar> it will look up the
- URL <makevar>MASTER_SITES</makevar>,
- which is set in the Makefile, as well as our main ftp
- site at <ulink
- URL="ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/">ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/,</ulink> where we put sanctioned distfiles as backup. It will then attempt to fetch the named distribution file with <makevar>FETCH</makevar>, assuming that the requesting site has direct access to the Internet. If that succeeds, it will save the file in <makevar>DISTDIR</makevar> for future use and proceed.</para>
- </step>
-
- <step>
- <para>The <maketarget>extract</maketarget> target is run. It looks for your port's
- distribution file in <makevar>DISTDIR</makevar> (typically a gzip'd
- tarball) and unpacks it into a temporary subdirectory
- specified by <makevar>WRKDIR</makevar>
- (defaults to <filename>work</filename>).</para>
- </step>
-
- <step>
- <para>The <maketarget>patch</maketarget> target is run. First, any patches defined
- in <makevar>PATCHFILES</makevar> are
- applied. Second, if any patches are found in <makevar>PATCHDIR</makevar> (defaults to the
- <filename>patches</filename> subdirectory), they are
- applied at this time in alphabetical order.</para>
- </step>
-
- <step>
- <para>The <maketarget>configure</maketarget> target is run. This can do any one of
- many different things.</para>
-
- <orderedlist>
-
- <listitem>
- <para>If it exists,
- <filename>scripts/configure</filename> is run.</para>
- </listitem>
-
- <listitem>
- <para>If <makevar>HAS_CONFIGURE</makevar> or
- <makevar>GNU_CONFIGURE</makevar>
- is set,
- <filename><makevar>WRKSRC</makevar>/configure</filename> is
- run.</para>
- </listitem>
-
- <listitem>
- <para>If <makevar>USE_IMAKE</makevar> is set,
- <makevar>XMKMF</makevar>
- (default: <command>xmkmf
- -a</command>) is run.</para>
- </listitem>
-
- </orderedlist>
-
- </step>
-
- <step>
- <para>The <maketarget>build</maketarget> target is run. This is responsible for
- descending into the ports' private working directory
- (<makevar>WRKSRC</makevar>) and
- building it. If <makevar>USE_GMAKE</makevar> is set, GNU
- <command>make</command> will be used,
- otherwise the system <command>make</command>
- will be used.</para>
- </step>
-
- </procedure>
-
-
- <para>The above are the default actions. In addition, you can
- define targets <maketarget>pre-<replaceable>something</replaceable></maketarget> or <maketarget>post-<replaceable>something</replaceable></maketarget>, or put scripts
- with those names, in the <filename>scripts</filename>
- subdirectory, and they will be run before or after the default
- actions are done.</para>
-
- <para>For example, if you have a <maketarget>post-extract</maketarget> target defined in your
- Makefile, and a file <filename>pre-build</filename> in the
- <filename>scripts</filename> subdirectory, the
- <maketarget>post-extract</maketarget> target will be
- called after the regular extraction actions, and the
- <filename>pre-build</filename> script will be executed before
- the default build rules are done. It is recommended that you
- use <filename>Makefile</filename> targets if the actions are
- simple enough, because it will be easier for someone to figure
- out what kind of non-default action the port requires.</para>
-
- <para>The default actions are done by the
- <filename>bsd.port.mk</filename> targets <maketarget>do-<replaceable>something</replaceable></maketarget>. For example, the
- commands to extract a port are in the target <maketarget>do-extract</maketarget>. If you are not happy with
- the default target, you can fix it by redefining the
- <maketarget>do-<replaceable>something</replaceable></maketarget> target in
- your <filename>Makefile</filename>.</para>
-
- <note>
- <para>The “main” targets (e.g., <maketarget>extract</maketarget>, <maketarget>configure</maketarget>, etc.) do nothing more than
- make sure all the stages up to that one is completed and
- call the real targets or scripts, and they are not intended
- to be changed. If you want to fix the extraction, fix
- <maketarget>do-extract</maketarget>, but never ever
- touch <maketarget>extract</maketarget>!</para>
- </note>
-
- <para>Now that you understand what goes on when the user types
- <command>make</command>, let us go through the
- recommended steps to create the perfect port.</para>
-
- </sect4>
-
- <sect4>
- <title>Getting the original sources</title>
-
- <para>Get the original sources (normally) as a compressed
- tarball (<filename><replaceable>foo</replaceable>.tar.gz</filename> or
- <filename><replaceable>foo</replaceable>.tar.Z</filename>) and copy it into
- <makevar>DISTDIR</makevar>. Always use
- <emphasis>mainstream</emphasis> sources when and where you
- can.</para>
-
- <para>If you cannot find a ftp/http site that is well-connected
- to the net, or can only find sites that have irritatingly
- non-standard formats, you might want to put a copy on a
- reliable http or ftp server that you control. If you are a FreeBSD
- committer, your <filename>public_html</filename> directory on
- <hostid>freefall</hostid> is ideal. Make sure you set
- <makevar>MASTER_SITE</makevar> to reflect your choice. If you
- cannot find somewhere convenient and reliable to put the distfile,
- we can “house” it ourselves by putting
- it on <filename>ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/LOCAL_PORTS/</filename> as the last resort. Please refer to this
- location as <makevar>MASTER_SITE_LOCAL</makevar>. Send mail to
- the &a.ports;if you are not sure what to do.</para>
-
- <para>If your port requires some additional `patches' that are
- available on the Internet, fetch them too and put them in
- <makevar>DISTDIR</makevar>. Do not worry if
- they come from site other than where you got the main source
- tarball, we have a way to handle these situations (see the
- description of <link
- linkend="porting-patchfiles">PATCHFILES</link> below).</para>
-
- </sect4>
-
- <sect4>
- <title>Modifying the port</title>
-
- <para>Unpack a copy of the tarball in a private directory and
- make whatever changes are necessary to get the port to compile
- properly under the current version of FreeBSD. Keep
- <emphasis>careful track</emphasis> of everything you do, as
- you will be automating the process shortly. Everything,
- including the deletion, addition or modification of files
- should be doable using an automated script or patch file when
- your port is finished.</para>
-
- <para>If your port requires significant user
- interaction/customization to compile or install, you should
- take a look at one of Larry Wall's classic <application>Configure</application> scripts
- and perhaps do something similar yourself. The goal of the
- new ports collection is to make each port as “plug-and-play”
- as possible for the end-user while using a minimum of disk
- space.</para>
-
- <note>
- <para>Unless explicitly stated, patch files, scripts, and
- other files you have created and contributed to the FreeBSD
- ports collection are assumed to be covered by the standard
- BSD copyright conditions.</para>
- </note>
- </sect4>
-
- <sect4>
- <title>Patching</title>
-
- <para>In the preparation of the port, files that have been added
- or changed can be picked up with a recursive diff for later
- feeding to patch. Each set of patches you wish to apply
- should be collected into a file named
- <filename>patch-<replaceable>xx</replaceable></filename> where
- <replaceable>xx</replaceable> denotes the sequence in which
- the patches will be applied — these are done in
- <emphasis>alphabetical order</emphasis>, thus
- <literal>aa</literal> first, <literal>ab</literal> second and so on. These files
- should be stored in <makevar>PATCHDIR</makevar>, from where they will be
- automatically applied. All patches should be relative to
- <makevar>WRKSRC</makevar> (generally the
- directory your port's tarball unpacks itself into, that being
- where the build is done). To make fixes and upgrades easier
- you should avoid having more than one patch fix the same file
- (e.g., patch-aa and patch-ab both changing <makevar>WRKSRC</makevar>/foobar.c).</para>
-
- </sect4>
-
- <sect4>
- <title>Configuring</title>
-
- <para>Include any additional customization commands to your
- <filename>configure</filename> script and save it in the
- <filename>scripts</filename> subdirectory. As mentioned
- above, you can also do this as <filename>Makefile</filename>
- targets and/or scripts with the name
- <filename>pre-configure</filename> or
- <filename>post-configure</filename>.</para>
-
- </sect4>
-
- <sect4>
- <title>Handling user input</title>
-
- <para>If your port requires user input to build, configure or
- install, then set <makevar>IS_INTERACTIVE</makevar> in your
- Makefile. This will allow “overnight builds” to skip your port
- if the user sets the variable <envar>BATCH</envar> in his
- environment (and if the user sets the variable
- <envar>INTERACTIVE</envar>, then <emphasis>only</emphasis>
- those ports requiring interaction are built).</para>
-
- </sect4>
- </sect3>
-
- <sect3>
- <title>Configuring the Makefile</title>
-
- <para>Configuring the Makefile is pretty simple, and again we
- suggest that you look at existing examples before starting.
- Also, there is a <link linkend="porting-samplem">sample
- Makefile</link> in this handbook, so take a look and please follow
- the ordering of variables and sections in that template to make
- your port easier for others to read.</para>
-
- <para>Now, consider the following problems in sequence as you
- design your new Makefile:</para>
-
-
- <sect4>
- <title>The original source</title>
-
- <para>Does it live in <makevar>DISTDIR</makevar> as a standard gzip'd
- tarball? If so, you can go on to the next step. If not, you
- should look at overriding any of the <makevar>EXTRACT_CMD</makevar>, <makevar>EXTRACT_BEFORE_ARGS</makevar>, <makevar>EXTRACT_AFTER_ARGS</makevar>, <makevar>EXTRACT_SUFX</makevar>, or <makevar>DISTFILES</makevar> variables, depending on
- how alien a format your port's distribution file is. (The
- most common case is <literal>EXTRACT_SUFX=.tar.Z</literal>,
- when the tarball is condensed by regular compress, not
- gzip.)</para>
-
- <para>In the worst case, you can simply create your own
- <maketarget>do-extract</maketarget> target to override
- the default, though this should be rarely, if ever,
- necessary.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>DISTNAME</makevar></title>
-
- <para>You should set <makevar>DISTNAME</makevar> to be the base name of
- your port. The default rules expect the distribution file
- list (<makevar>DISTFILES</makevar>) to be
- named <makevar>DISTNAME</makevar><makevar>EXTRACT_SUFX</makevar> by
- default which, if it is a normal tarball, is going to be
- something like <literal>foozolix-1.0.tar.gz</literal> for a setting of
- <programlisting>
-DISTNAME=foozolix-1.0</programlisting>.</para>
-
- <para>The default rules also expect the tarball(s) to extract
- into a subdirectory called
- <filename>work/<makevar>DISTNAME</makevar></filename>, e.g. <filename>work/foozolix-1.0/</filename>.</para>
-
- <para>All this behavior can be overridden, of course; it simply
- represents the most common time-saving defaults. For a port
- requiring multiple distribution files, simply set <makevar>DISTFILES</makevar> explicitly. If only a
- subset of <makevar>DISTFILES</makevar> are
- actual extractable archives, then set them up in <makevar>EXTRACT_ONLY</makevar>, which will override
- the <makevar>DISTFILES</makevar> list when
- it comes to extraction, and the rest will be just left in
- <makevar>DISTDIR</makevar> for later
- use.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>CATEGORIES</makevar></title>
-
- <para>When a package is created, it is put under
- <filename>/usr/ports/packages/All</filename> and links are
- made from one or more subdirectories of
- <filename>/usr/ports/packages</filename>. The names of these
- subdirectories are specified by the variable <makevar>CATEGORIES</makevar>. It is intended to
- make life easier for the user when he is wading through the
- pile of packages on the ftp site or the CD-ROM. Please take a
- look at the existing categories (you can find them in <ulink
- URL="http://www.freebsd.org/ports/">the ports
- page</ulink>) and pick the ones that are suitable for your
- port. If your port truly belongs to something that is
- different from all the existing ones, you can even create a
- new category name.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>MASTER_SITES</makevar></title>
-
- <para>Record the directory part of the ftp/http-URL pointing at
- the original tarball in <makevar>MASTER_SITES</makevar>. Do not forget the
- trailing slash (<filename>/</filename>)!</para>
-
- <para>The <command>make</command> macros will try to use this specification for
- grabbing the distribution file with <makevar>FETCH</makevar> if they cannot find it
- already on the system.</para>
-
- <para>It is recommended that you put multiple sites on this
- list, preferably from different continents. This will
- safeguard against wide-area network problems, and we are even
- planning to add support for automatically determining the
- closest master site and fetching from there!</para>
-
- <para>If the original tarball is part of one of the following
- popular archives: X-contrib, GNU, Perl CPAN, TeX CTAN, or
- Linux Sunsite, you refer to those sites in an easy compact
- form using <makevar>MASTER_SITE_XCONTRIB</makevar>, <makevar>MASTER_SITE_GNU</makevar>,
- <makevar>MASTER_SITE_PERL_CPAN</makevar>, <makevar>MASTER_SITE_TEX_CTAN</makevar>, and
- <makevar>MASTER_SITE_SUNSITE</makevar>. Simply set <makevar>MASTER_SITE_SUBDIR</makevar> to the
- path with in the archive. Here is an example:</para>
-
- <programlisting>
-MASTER_SITES= ${MASTER_SITE_XCONTRIB}
-MASTER_SITE_SUBDIR= applications</programlisting>
-
- <para>The user can also set the <makevar>MASTER_SITE_*</makevar> variables in
- <filename>/etc/make.conf</filename> to override our choices,
- and use their favorite mirrors of these popular archives
- instead.</para>
-
- </sect4>
-
- <sect4 id="porting-patchfiles">
- <title><makevar>PATCHFILES</makevar></title>
-
- <para>If your port requires some additional patches that are
- available by ftp or http, set <makevar>PATCHFILES</makevar> to the names of the
- files and <makevar>PATCH_SITES</makevar> to
- the URL of the directory that contains them (the format is the
- same as <makevar>MASTER_SITES</makevar>).</para>
-
- <para>If the patch is not relative to the top of the source tree
- (i.e., <makevar>WKRSRC</makevar>) because it
- contains some extra pathnames, set <makevar>PATCH_DIST_STRIP</makevar> accordingly.
- For instance, if all the pathnames in the patch has an extra
- <literal>foozolix-1.0/</literal> in front of the
- filenames, then set
- <literal>PATCH_DIST_STRIP=-p1</literal>.</para>
-
- <para>Do not worry if the patches are compressed, they will be
- decompressed automatically if the filenames end with
- <filename>.gz</filename> or
- <filename>.Z</filename>.</para>
-
- <para>If the patch is distributed with some other files, such as
- documentation, in a gzip'd tarball, you can't just use
- <makevar>PATCHFILES</makevar>. If that is
- the case, add the name and the location of the patch tarball
- to <makevar>DISTFILES</makevar> and
- <makevar>MASTER_SITES</makevar>. Then, from
- the <maketarget>pre-patch</maketarget> target, apply the
- patch either by running the patch command from there, or
- copying the patch file into the <makevar>PATCHDIR</makevar> directory and calling it
- <filename>patch-<replaceable>xx</replaceable></filename>.</para>
-
- <note>
- <para>Note the tarball will have been extracted alongside the
- regular source by then, so there is no need to explicitly
- extract it if it is a regular gzip'd or compress'd tarball.
- If you do the latter, take extra care not to overwrite
- something that already exists in that directory. Also do
- not forget to add a command to remove the copied patch in
- the <maketarget>pre-clean</maketarget> target.</para>
- </note>
-
- </sect4>
-
- <sect4>
- <title><makevar>MAINTAINER</makevar></title>
-
- <para>Set your mail-address here. Please. <!-- smiley --><emphasis>:)</emphasis></para>
-
- <para>For detailed description of the responsibility of
- maintainers, refer to <link
- linkend="policies-maintainer">MAINTAINER
- on Makefiles</link> section.</para>
-
- </sect4>
-
- <sect4>
- <title>Dependencies</title>
-
- <para>Many ports depend on other ports. There are five
- variables that you can use to ensure that all the required
- bits will be on the user's machine.</para>
-
-
- <sect5>
- <title><makevar>LIB_DEPENDS</makevar></title>
-
- <para>This variable specifies the shared libraries this port
- depends on. It is a list of <replaceable>lib</replaceable>:<replaceable>dir</replaceable> pairs where
- <replaceable>lib</replaceable> is the name of the shared library,
- and <replaceable>dir</replaceable> is the directory in which to
- find it in case it is not available. For example,
-
- <programlisting>
-LIB_DEPENDS= jpeg\\.6\\.:${PORTSDIR}/graphics/jpeg</programlisting>
-
- will check for a shared jpeg library with
- major version 6, and descend into the
- <filename>graphics/jpeg</filename> subdirectory of your
- ports tree to build and install it if it is not
- found.</para>
-
- <note>
- <para>The <replaceable>lib</replaceable> part is just an argument
- given to <command>ldconfig -r | grep</command>, so
- periods should be escaped by two backslashes like in the
- example above.</para>
- </note>
-
- <para>The dependency is checked from within the <maketarget>extract</maketarget> target. Also, the name of the
- dependency is put in to the package so that
- <command>pkg_add</command> will automatically install it if it
- is not on the user's system.</para>
-
- </sect5>
-
- <sect5>
- <title><makevar>RUN_DEPENDS</makevar></title>
-
- <para>This variable specifies executables or files this port
- depends on during run-time. It is a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable> pairs where
- <replaceable>path</replaceable> is the name of the executable or
- file, and <replaceable>dir</replaceable> is the directory in which
- to find it in case it is not available. If
- <replaceable>path</replaceable> starts with a slash
- (<literal>/</literal>), it is treated as a file and its
- existence is tested with <command>test -e</command>;
- otherwise, it is assumed to be an executable, and
- <command>which -s</command> is used to determine if the
- program exists in the user's search path.</para>
-
- <para>For example,
-
- <programlisting>
-RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \
- wish:${PORTSDIR}/x11/tk</programlisting>
-
- will check if the file
- <filename>/usr/local/etc/innd</filename> exists, and build
- and install it from the <filename>news/inn</filename>
- subdirectory of the ports tree if it is not found. It will
- also see if an executable called <command>wish</command> is in your search path, and
- descend into the <filename>x11/tk</filename> subdirectory of
- your ports tree to build and install it if it is not
- found.</para>
-
- <note>
- <para>In this case, <command>innd</command> is actually an
- executable; if an executable is in a place that is not
- expected to be in a normal user's search path, you should
- use the full pathname.</para>
- </note>
-
- <para>The dependency is checked from within the <maketarget>install</maketarget> target. Also, the name of the
- dependency is put in to the package so that
- <command>pkg_add</command> will automatically install it if it
- is not on the user's system.</para>
-
- </sect5>
-
- <sect5>
- <title><makevar>BUILD_DEPENDS</makevar></title>
-
- <para>This variable specifies executables or files this port
- requires to build. Like <makevar>RUN_DEPENDS</makevar>, it is
- a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable> pairs.
- For example,
-
- <programlisting>
-BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>
-
- will check for an executable called
- <command>unzip</command>, and descend into the
- <filename>archivers/unzip</filename> subdirectory of your
- ports tree to build and install it if it is not
- found.</para>
-
- <note>
- <para>“build” here means everything from extracting to
- compilation. The dependency is checked from within the
- <maketarget>extract</maketarget> target.</para>
- </note>
- </sect5>
-
- <sect5>
- <title><makevar>FETCH_DEPENDS</makevar></title>
-
- <para>This variable specifies executables or files this port
- requires to fetch. Like the previous two, it is a list of
- <replaceable>path</replaceable>:<replaceable>dir</replaceable> pairs. For
- example,
-
- <programlisting>
-FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting>
-
- will check for an executable called
- <command>ncftp2</command>, and descend into the
- <filename>net/ncftp2</filename> subdirectory of your ports
- tree to build and install it if it is not found.</para>
-
- <para>The dependency is checked from within the <maketarget>fetch</maketarget> target.</para>
-
- </sect5>
-
- <sect5>
- <title><makevar>DEPENDS</makevar></title>
-
- <para>If there is a dependency that does not fall into either
- of the above four categories, or your port requires to have
- the source of the other port extracted (i.e., having them
- installed is not enough), then use this variable. This is
- just a list of directories, as there is nothing to check,
- unlike the previous four.</para>
-
- </sect5>
- </sect4>
-
- <sect4>
- <title>Building mechanisms</title>
-
- <para>If your package uses GNU <command>make</command>, set
- <literal>USE_GMAKE=yes</literal>. If your package uses GNU
- <command>configure</command>, set
- <literal>GNU_CONFIGURE=yes</literal>. If you want to give
- some extra arguments to GNU <command>configure</command> (other than the default
- <literal>--prefix=${PREFIX}</literal>), set those extra
- arguments in <makevar>CONFIGURE_ARGS</makevar>.</para>
-
- <para>If your package is an X application that creates
- <filename>Makefile</filename>s from
- <filename>Imakefile</filename>s using <command>imake</command>, then set
- <literal>USE_IMAKE=yes</literal>. This will cause the
- configure stage to automatically do an <command>xmkmf
- -a</command>. If the <option>-a</option> flag is a
- problem for your port, set
- <literal>XMKMF=xmkmf</literal>.</para>
-
- <para>If your port's source <filename>Makefile</filename> has
- something else than <maketarget>all</maketarget> as the
- main build target, set <makevar>ALL_TARGET</makevar> accordingly. Same
- goes for <maketarget>install</maketarget> and <makevar>INSTALL_TARGET</makevar>.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>NO_INSTALL_MANPAGES</makevar></title>
-
- <para>If the port uses <command>imake</command> but does not understand the
- <filename>install.man</filename> target,
- <literal>NO_INSTALL_MANPAGES=yes</literal> should be set.
- In addition, the author of the original port should be shot.
- <!-- smiley --><emphasis>:></emphasis></para>
-
- </sect4>
- </sect3>
-
- <sect3>
- <title>Ports that require Motif</title>
-
- <para>There are many programs that require a Motif library
- (available from several commercial vendors, while there is (at
- least) one effort to create a free clone) to compile. Since it
- is a popular toolkit and their licenses usually permit
- redistribution of statically linked binaries, we have made
- special provisions for handling ports that require Motif in a
- way that we can easily compile binaries linked either
- dynamically or statically.</para>
-
-
- <sect4>
- <title><makevar>REQUIRES_MOTIF</makevar></title>
-
- <para>If your port requires Motif, define this variable in the
- Makefile. This will prevent people who don't own a copy of
- Motif from even attempting to build it.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>MOTIFLIB</makevar></title>
-
- <para>This variable will be set by
- <filename>bsd.port.mk</filename> to be the appropriate
- reference to the Motif library. Please patch the source to
- use this wherever the Motif library is referenced in the
- Makefile or Imakefile.</para>
-
- <para>There are two common cases:</para>
-
- <orderedlist>
-
- <listitem>
- <para>If the port refers to the Motif library as
- <option>-lXm</option> in its Makefile or Imakefile,
- simply substitute <makevar>MOTIFLIB</makevar> for it.</para>
- </listitem>
-
- <listitem>
- <para>If the port uses <literal>XmClientLibs</literal> in its Imakefile,
- change it to <literal>${MOTIFLIB}
- ${XTOOLLIB} ${XLIB}</literal>.</para>
- </listitem>
-
- </orderedlist>
-
- <note>
- <para><makevar>MOTIFLIB</makevar> (usually)
- expands to <literal>-L/usr/X11R6/lib -lXm</literal> or
- <literal>/usr/X11R6/lib/libXm.a</literal>, so there is
- no need to add <option>-L</option> or
- <option>-l</option> in front.</para>
- </note>
- </sect4>
- </sect3>
-
- <sect3>
- <title>ELF support</title>
-
- <para>Since FreeBSD is moving to ELF from 3.0-release onwards,
- 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 that there will
- be one more release (2.2.8) from the 2.2 branch. 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 awhile for reference
- in case you have come across some old port you wish to
- upgrade.</para>
-
- <sect4>
- <title>Moving a.out libraries out of the way</title>
-
- <para>A.out libraries should be moved out of
- <filename>/usr/local/lib</filename> and similar to an
- <filename>aout</filename> subdirectory. (If you don't move them
- out of the way, ELF ports will happily overwrite a.out libraries.)
- The <maketarget>move-aout-libs</maketarget> target in the -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>
- </sect4>
-
- <sect4>
- <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>
- </sect4>
-
- <sect4>
- <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's always going to be
- <literal>aout</literal> in -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>
- </sect4>
-
- <sect4>
- <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 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>PLIST</filename> too, and it won't 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>
- </sect4>
-
- <sect4>
- <title><makevar>LIB_DEPENDS</makevar></title>
-
- <para>All port Makefiles 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>
- </sect4>
-
- <sect4>
- <title><filename>PLIST</filename></title>
-
- <para><filename>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>PLIST</filename> mentioned in the previous
- paragraph.</para>
- </sect4>
-
- <sect4>
- <title><literal>ldconfig</literal></title>
-
- <para>The <literal>ldconfig/ line in Makefiles should read:</literal></para>
-
- <programlisting>
-${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....</programlisting>
-
- <para>In <filename>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>
- </sect4>
- </sect3>
-
- <sect3>
- <title>Info files</title>
-
- <para>The new version of texinfo (included in 2.2.2-RELEASE and
- onwards) contains a utility called <command>install-info</command> to add and delete entries to
- the <filename>dir</filename> file. If your port installs any
- info documents, please follow these instructions so your
- port/package will correctly update the user's
- <filename>${PREFIX}/info/dir</filename> file. (Sorry for
- the length of this section, but it is imperative to weave all
- the info files together. If done correctly, it will produce a
- <emphasis>beautiful</emphasis> listing, so please bear with me!
- <!-- smiley --><emphasis>:)</emphasis></para>
-
- <para>First, this is what you (as a porter) need to know:</para>
-
- <informalexample>
- <screen>&prompt.user; <userinput>install-info --help</userinput>
-install-info [OPTION]... [INFO-FILE [DIR-FILE]]
- Install INFO-FILE in the Info directory file DIR-FILE.
-
-Options:
---delete Delete existing entries in INFO-FILE;
- don't insert any new entries.
- :
---entry=TEXT Insert TEXT as an Info directory entry.
- :
---section=SEC Put this file's entries in section SEC of the directory. :</screen>
- </informalexample>
-
- <note>
- <para>This program will not actually
- <emphasis>install</emphasis> info files; it merely inserts or
- deletes entries in the <filename>dir</filename> file.</para>
- </note>
-
- <para>Here's a seven-step procedure to convert ports to use
- <command>install-info</command>. I will use
- <filename>editors/emacs</filename> as an example.</para>
-
- <procedure>
- <step>
- <para>Look at the texinfo sources and make a patch to insert
- <literal>@dircategory</literal> and <literal>@direntry</literal>
- statements to files that don't have them. This is part of
- my patch:</para>
-
- <programlisting>
---- ./man/vip.texi.org Fri Jun 16 15:31:11 1995
-+++ ./man/vip.texi Tue May 20 01:28:33 1997
-@@ -2,6 +2,10 @@
-
- @setfilename ../info/vip
- @settitle VIP
-+@dircategory The Emacs editor and associated tools
-+@direntry
-+* VIP: (vip). A VI-emulation for Emacs.
-+@end direntry
-
- @iftex
- @finalout
- :</programlisting>
-
- <para>The format should be self-explanatory. Many authors
- leave a <filename>dir</filename> file in the source tree
- that contains all the entries you need, so look around
- before you try to write your own. Also, make sure you
- look into related ports and make the section names and
- entry indentations consistent (we recommend that all entry
- text start at the 4th tab stop).</para>
-
- <note>
- <para>Note that you can put only one info entry per file
- because of a bug in <command>install-info
- --delete</command> that deletes only the first entry
- if you specify multiple entries in the
- <email>@direntry</email> section.</para>
- </note>
-
- <para>You can give the <literal>dir</literal>
- entries to <command>install-info</command> as
- arguments (<option>--section</option> and
- <option>--entry</option>) instead of patching the texinfo
- sources. I do not think this is a good idea for ports
- because you need to duplicate the same information in
- <emphasis>three</emphasis> places
- (<filename>Makefile</filename> and
- <literal>@exec</literal>/<literal>@unexec</literal> of
- <filename>PLIST</filename>; see below). However, if you
- have a Japanese (or other multibyte encoding) info files,
- you will have to use the extra arguments to <command>install-info</command> because <command>makeinfo</command> can't handle those texinfo
- sources. (See <filename>Makefile</filename> and
- <filename>PLIST</filename> of
- <filename>japanese/skk</filename> for examples on how to
- do this).</para>
- </step>
-
- <step>
- <para>Go back to the port directory and do a <command>make clean; make</command> and verify that
- the info files are regenerated from the texinfo sources.
- Since the texinfo sources are newer than the info files,
- they should be rebuilt when you type <command>make</command>; but many
- <filename>Makefile</filename>s don't include correct
- dependencies for info files. In <command>emacs</command>' case, I had to
- patch the main <filename>Makefile.in</filename> so it will
- descend into the <filename>man</filename>
- subdirectory to rebuild the info pages.</para>
-
- <programlisting>
---- ./Makefile.in.org Mon Aug 19 21:12:19 1996
-+++ ./Makefile.in Tue Apr 15 00:15:28 1997
-@@ -184,7 +184,7 @@
- # Subdirectories to make recursively. `lisp' is not included
- # because the compiled lisp files are part of the distribution
- # and you cannot remake them without installing Emacs first.
--SUBDIR = lib-src src
-+SUBDIR = lib-src src man
-
- # The makefiles of the directories in $SUBDIR.
- SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile lwlib/Makefile
---- ./man/Makefile.in.org Thu Jun 27 15:27:19 1996
-+++ ./man/Makefile.in Tue Apr 15 00:29:52 1997
-@@ -66,6 +66,7 @@
- ${srcdir}/gnu1.texi \
- ${srcdir}/glossary.texi
-
-+all: info
- info: $(INFO_TARGETS)
-
- dvi: $(DVI_TARGETS)</programlisting>
-
- <para>The second hunk was necessary because the default
- target in the <filename>man</filename> subdir is called
- <maketarget>info</maketarget>, while the main
- <filename>Makefile</filename> wants to call <maketarget>all</maketarget>. I also deleted the installation
- of the <filename>info</filename> info file
- because we already have one with the same name in
- <filename>/usr/share/info</filename> (that patch is not
- shown here).</para>
- </step>
-
- <step>
- <para>If there is a place in the
- <filename>Makefile</filename> that is installing the
- <filename>dir</filename> file, delete it. Your
- port may not be doing it. Also, remove any commands that
- are otherwise mucking around with the
- <filename>dir</filename> file.</para>
-
- <programlisting>
---- ./Makefile.in.org Mon Aug 19 21:12:19 1996
-+++ ./Makefile.in Mon Apr 14 23:38:07 1997
-@@ -368,14 +368,8 @@
- if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \
- then \
- (cd ${infodir}; \
-- if [ -f dir ]; then \
-- if [ ! -f dir.old ]; then mv -f dir dir.old; \
-- else mv -f dir dir.bak; fi; \
-- fi; \
- cd ${srcdir}/info ; \
-- (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir); \
-- (cd $${thisdir}; chmod a+r ${infodir}/dir); \
- for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \
- (cd $${thisdir}; \
- ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \
- chmod a+r ${infodir}/$$f); \</programlisting>
- </step>
-
- <step>
- <para>(This step is only necessary if you are modifying an
- existing port.) Take a look at
- <filename>pkg/PLIST</filename> and delete anything that is
- trying to patch up <filename>info/dir</filename>. They
- may be in <filename>pkg/INSTALL</filename> or some other
- file, so search extensively.</para>
-
- <programlisting>
-Index: pkg/PLIST
-===================================================================
-RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v
-retrieving revision 1.15
-diff -u -r1.15 PLIST
---- PLIST 1997/03/04 08:04:00 1.15
-+++ PLIST 1997/04/15 06:32:12
-@@ -15,9 +15,6 @@
- man/man1/emacs.1.gz
- man/man1/etags.1.gz
- man/man1/ctags.1.gz
--@unexec cp %D/info/dir %D/info/dir.bak
--info/dir
--@unexec cp %D/info/dir.bak %D/info/dir
- info/cl
- info/cl-1
- info/cl-2</programlisting>
- </step>
-
- <step>
- <para>Add a <maketarget>post-install</maketarget>
- target to the <filename>Makefile</filename> to create a
- <filename>dir</filename> file if it is not there. Also,
- call <maketarget>install-info</maketarget> with the
- installed info files.</para>
-
- <programlisting>
-Index: Makefile
-===================================================================
-RCS file: /usr/cvs/ports/editors/emacs/Makefile,v
-retrieving revision 1.26
-diff -u -r1.26 Makefile
---- Makefile 1996/11/19 13:14:40 1.26
-+++ Makefile 1997/05/20 10:25:09 1.28
-@@ -20,5 +20,11 @@
- post-install:
- .for file in emacs-19.34 emacsclient etags ctags b2m
- strip ${PREFIX}/bin/${file}
- .endfor
-+ if [ ! -f ${PREFIX}/info/dir ]; then \
-+ ${SED} -ne '1,/Menu:/p' /usr/share/info/dir > ${PREFIX}/info/dir; \
-+ fi
-+.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode
-+ install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir
-+.endfor
-
- .include <bsd.port.mk></programlisting>
-
- <para>Do not use anything other than
- <filename>/usr/share/info/dir</filename> and the above
- command to create a new info file. In fact, I'd add the
- first three lines of the above patch to
- <filename>bsd.port.mk</filename> if you (the porter)
- wouldn't have to do it in <filename>PLIST</filename> by
- yourself anyway.</para>
- </step>
-
- <step>
- <para>Edit <filename>PLIST</filename> and add equivalent
- <literal>@exec</literal> statements and also
- <literal>@unexec</literal> for <command>pkg_delete</command>.
- You do not need to delete <filename>info/dir</filename>
- with <literal>@unexec</literal>.</para>
-
- <programlisting>
-Index: pkg/PLIST
-===================================================================
-RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v
-retrieving revision 1.15
-diff -u -r1.15 PLIST
---- PLIST 1997/03/04 08:04:00 1.15
-+++ PLIST 1997/05/20 10:25:12 1.17
-@@ -16,7 +14,15 @@
- man/man1/etags.1.gz
- man/man1/ctags.1.gz
-+@unexec install-info --delete %D/info/emacs %D/info/dir
- :
-+@unexec install-info --delete %D/info/ccmode %D/info/dir
- info/cl
- info/cl-1
-@@ -87,6 +94,18 @@
- info/viper-3
- info/viper-4
-+@exec [ -f %D/info/dir ] || sed -ne '1,/Menu:/p' /usr/share/info/dir > %D/info/dir
-+@exec install-info %D/info/emacs %D/info/dir
- :
-+@exec install-info %D/info/ccmode %D/info/dir
- libexec/emacs/19.34/i386--freebsd/cvtmail
- libexec/emacs/19.34/i386--freebsd/digest-doc</programlisting>
-
- <note>
- <para>The <literal>@unexec install-info
- --delete</literal> commands have to be listed before
- the info files themselves so they can read the files.
- Also, the <literal>@exec install-info</literal> commands
- have to be after the info files and the
- <literal>@exec</literal> command that creates the the
- <filename>dir</filename> file.</para>
- </note>
- </step>
-
- <step>
- <para>Test and admire your work. <!-- smiley --><emphasis>:)</emphasis> The sequence I recommend is:
- <command>make package</command>,
- <command>pkg_delete</command>, then
- <command>pkg_add</command>. Check the <filename>dir</filename> file before and after each
- step.</para>
- </step>
-
- </procedure>
-
-
- </sect3>
-
- <sect3>
- <title>Changing the <filename>PLIST</filename> based on <citerefentry>
- <refentrytitle>make</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> variables</title>
-
- <para>Some ports, particularly the <filename>p5-</filename> ports,
- need to change their <filename>PLIST</filename> depending on what
- options they are configured with (or version of perl, in the case of
- <filename>p5-</filename> ports). To make this easy, any instances in
- the <filename>PLIST</filename> of <literal>%%OSREL%%</literal>,
- <literal>%%PERL_VER%%</literal>, and
- <literal>%%PERL_VERSION%%</literal> will be substituted for
- appropriately. If you need to make other substitutions, you can set
- the <makevar>PLIST_SUB</makevar> variable with a list of
- <literal><replaceable>VAR</replaceable>=<replaceable>VALUE</replaceable></literal> pairs and instances of <literal>%%<replaceable>VAR</replaceable>%%</literal> will be substituted with <replaceable>VALUE</replaceable> in the <filename>PLIST</filename>.</para>
- </sect3>
-
- <sect3>
- <title>Licensing Problems</title>
-
- <para>Some software packages have restrictive licenses or can be
- in violation to the law (PKP's patent on public key crypto, ITAR
- (export of crypto software) to name just two of them). What we
- can do with them vary a lot, depending on the exact wordings of
- the respective licenses.</para>
-
- <note>
- <para>It is your responsibility as a porter to read the
- licensing terms of the software and make sure that the FreeBSD
- project will not be held accountable of violating them by
- redistributing the source or compiled binaries either via ftp
- or CD-ROM. If in doubt, please contact the &a.ports;.</para>
- </note>
-
- <para>There are two variables you can set in the Makefile to
- handle the situations that arise frequently:</para>
-
-
- <orderedlist>
-
- <listitem>
- <para>If the port has a “do not sell for profit” type of
- license, set the variable <makevar>NO_CDROM</makevar>. We
- will make sure such ports won't go into the CD-ROM come
- release time. The distfile and package will still be
- available via ftp.</para>
- </listitem>
-
- <listitem>
- <para>If the resulting package needs to be built uniquely
- for each site, or the resulting binary package can't be
- distributed due to licensing; set the variable
- <makevar>NO_PACKAGE</makevar>. We will make sure such
- packages won't go on the ftp site, nor into the CD-ROM
- come release time. The distfile will still be included on
- both however.</para>
- </listitem>
-
- <listitem>
- <para>If the port has legal restrictions on who can use it
- (e.g., crypto stuff) or has a “no commercial use” license,
- set the variable <makevar>RESTRICTED</makevar> to be the
- string describing the reason why. For such ports, the
- distfiles/packages will not be available even from our ftp
- sites.</para>
- </listitem>
-
- </orderedlist>
-
-
- <note>
- <para>The GNU General Public License (GPL), both version 1
- and 2, should not be a problem for ports.</para>
- </note>
-
- <note>
- <para>If you are a committer, make sure you update the
- <filename>ports/LEGAL</filename> file too.</para>
- </note>
- </sect3>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>When you notice that a port is out of date compared to the
- latest version from the original authors, first make sure you
- have the latest port. You can find them in the
- <filename>ports-current</filename> directory of the ftp mirror
- sites.</para>
-
- <para>The next step is to send a mail to the maintainer, if one is
- listed in the port's <filename>Makefile</filename>. That person may already be
- working on an upgrade, or have a reason to not upgrade the port
- right now (because of, for example, stability problems of the
- new version).</para>
-
- <para>If the maintainer asks you to do the upgrade or there isn't
- any such person to begin with, please make the upgrade and send
- the recursive diff (either unified or context diff is fine, but
- port committers appear to prefer unified diff more) of the new
- and old ports directories to us (e.g., if your modified port
- directory is called <filename>superedit</filename>
- and the original as in our tree is
- <filename>superedit.bak</filename>, then send us the result of
- <command>diff -ruN superedit.bak
- superedit</command>). Please examine the output to make
- sure all the changes make sense. The best way to send us the
- diff is by including it to <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- (category <literal>ports</literal>). Please mention any added or deleted files
- in the message, as they have to be explicitly specified to CVS
- when doing a commit. If the diff is more than about 20KB, please
- compress and uuencode it; otherwise, just include it in as is in
- the PR.</para>
-
- </sect3>
-
- <sect3>
- <title><anchor id="porting-dads">Do's and Dont's</title>
-
- <para>Here is a list of common do's and dont's that you encounter
- during the porting process.You should check your own port
- against this list, but you can also check ports in the PR
- database that others have submitted. Submit any comments on
- ports you check as described in <link linkend="contrib-general">Bug
- Reports and General Commentary</link>. Checking ports in
- the PR database will both make it faster for us to commit them,
- and prove that you know what you are doing.</para>
-
-
- <sect4>
- <title><makevar>WRKDIR</makevar></title>
-
- <para>Do not leave anything valuable lying around in the
- <filename>work</filename> subdirectory, <command>make clean</command> will
- <emphasis>nuke</emphasis> it completely! If you need
- auxiliary files that are not scripts or patches, put them in
- the <makevar>FILESDIR</makevar> subdirectory
- (<filename>files</filename> by default) and use the
- <maketarget>post-extract</maketarget> target to copy them
- to the <filename>work</filename> subdirectory.</para>
-
- </sect4>
-
- <sect4>
- <title>Portlint Clean</title>
-
- <para>Do use <command>portlint</command>! The <ulink
- url="http://www.freebsd.org/cgi/ports.cgi?portlint">portlint</ulink> program is part of the ports collection.</para>
- </sect4>
-
- <sect4>
- <title>Strip Binaries</title>
-
- <para>Do strip binaries. If the original source already strips the
- binaries, fine; otherwise you should add a
- <literal>post-install</literal> rule to to it yourself. Here is an
- example;</para>
-
- <programlisting>
-post-install:
- strip ${PREFIX}/bin/xdl</programlisting>
-
- <para>Use the <citerefentry>
- <refentrytitle>file</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> command on the installed executable to check
- whether the binary is stripped or not. If it does not say
- <literal>not stripped</literal>, it is stripped.</para>
- </sect4>
-
- <sect4>
- <title>Correctly Install Manpages</title>
-
- <para>Do use the <makevar>MAN<replaceable>n</replaceable></makevar>
- variables. These variables, will automatically add any manpages
- to <filename>pkg/PLIST</filename> (this means you must
- <emphasis>not</emphasis> list manpages in the
- <filename>PLIST</filename>) and automatically compress manpages
- (unless <makevar>NOMANCOMPRESS</makevar> is set in
- <filename>/etc/make.conf</filename>). If your port installs
- pre-compressed manpages, you must define the
- <makevar>MANCOMPRESSED</makevar> variable.</para>
-
- <programlisting>
-MAN1= foo.1 bar.1
-MAN5= foo.conf.5
-MAN8= baz.8</programlisting>
-
- <note>
- <para>This is not usually necessary with ports that are X
- applications and use <command>Imake</command> to build.</para>
- </note>
-
- <para>If your port anchors its man tree somewhere other than
- <makevar>PREFIX</makevar>, you can use the
- <makevar>MANPREFIX</makevar> to set it. Also, if only manpages in
- certain section go in a non-standard place, such as many Perl
- modules ports, you can set individual man paths using
- <makevar>MAN<replaceable>sect</replaceable>PREFIX</makevar> (where
- <replaceable>sect</replaceable> is one of <literal>1-9</literal>,
- <literal>L</literal> or <literal>N</literal>).</para>
- </sect4>
-
- <sect4>
- <title>INSTALL_* macros</title>
-
- <para>Do use the macros provided in <filename>bsd.port.mk</filename>
- to ensure correct modes and ownership of files in your own
- <maketarget>*-install</maketarget> targets. They are:</para>
-
- <itemizedlist>
- <listitem>
- <para><makevar>INSTALL_PROGRAM</makevar> is a command to install
- binary executables.</para>
- </listitem>
-
- <listitem>
- <para><makevar>INSTALL_SCRIPT</makevar> is a command to install
- executable scripts.</para>
- </listitem>
-
- <listitem>
- <para><makevar>INSTALL_DATA</makevar> is a command to install
- sharable data.</para>
- </listitem>
-
- <listitem>
- <para><makevar>INSTALL_MAN</makevar> is a command to install
- manpages and other documentation (it doesn't compress
- anything).</para>
- </listitem>
- </itemizedlist>
-
- <para>These are basically the <command>install</command> command
- with all the appropriate flags. See below for an example on how
- to use them.</para>
- </sect4>
-
- <sect4>
- <title><filename>INSTALL</filename> package script</title>
-
- <para>If your port needs execute commands when the binary package is
- installed with pkg_add you can do with via the
- <filename>pkg/INSTALL</filename> script. This script will
- automatically be added to the package, and will be run twice by
- <command>pkg_add</command>. The first time will as
- <command>INSTALL ${PKGNAME} PRE-INSTALL</command> and the second
- time as <command>INSTALL ${PKGNAME} POST-INSTALL</command>.
- <literal>$2</literal> can be tested to determine which mode
- the script is being run in.</para>
-
- <para>The <envar>PKG_PREFIX</envar> environmental variable will be
- set to the package installation directory. See <citerefentry>
- <refentrytitle>pkg_add</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> for additional information.</para>
-
- <note>
- <para>This script is not run automatically if you install the port
- with <command>make install</command>. If you are depending on it
- being run, you will have to explicitly call it on your port's
- <filename>Makefile</filename>.</para>
- </note>
- </sect4>
-
- <sect4>
- <title><filename>REQ</filename> package script</title>
-
- <para>If your port needs to determine if it should install or
- not, you can create a <filename>pkg/REQ</filename>
- “requirements” script. It will be invoked automatically at
- installation/deinstallation time to determine whether or not
- installation/deinstallation should proceed. See man
- <citerefentry><refentrytitle>pkg_create</refentrytitle><manvolnum>1</manvolnum></citerefentry> and man
- <citerefentry><refentrytitle>pkg_add</refentrytitle><manvolnum>1</manvolnum></citerefentry> for more information.</para>
-
- </sect4>
-
- <sect4>
- <title>Install additional documentation</title>
-
- <para>If your software has some documentation other than the
- standard man and info pages that you think is useful for the
- user, install it under
- <filename><makevar>PREFIX</makevar>/share/doc</filename>. This can be
- done, like the previous item, in the <maketarget>post-install</maketarget> target.</para>
-
- <para>Create a new directory for your port. The directory name
- should reflect what the port is. This usually means <makevar>PKGNAME</makevar> minus the version part.
- However, if you think the user might want different versions
- of the port to be installed at the same time, you can use the
- whole <makevar>PKGNAME</makevar>.</para>
-
- <para>Make the installation dependent to the variable
- <makevar>NOPORTDOCS</makevar> so that users can disable it in
- <filename>/etc/make.conf</filename>, like this:</para>
-
- <programlisting>
-post-install:
-.if !defined(NOPORTDOCS)
- ${MKDIR}${PREFIX}/share/doc/xv
- ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
-.endif</programlisting>
-
- <para>Do not forget to add them to
- <filename>pkg/PLIST</filename> too! (Do not worry about
- <makevar>NOPORTDOCS</makevar> here; there is currently no way
- for the packages to read variables from
- <filename>/etc/make.conf</filename>.)</para>
-
- <para>If you need to display a message to the installer, you may
- place the message in <filename>pkg/MESSAGE</filename>. This
- capibility is often useful to display additional installation
- steps to be taken after a pkg_add, or to display licensing
- information.</para>
-
- <note>
- <para><filename>MESSAGE</filename> does not need to be added
- to <filename>pkg/PLIST</filename>).</para>
- </note>
- </sect4>
-
- <sect4>
- <title><makevar>DIST_SUBDIR</makevar></title>
-
- <para>Do not let your port clutter
- <filename>/usr/ports/distfiles</filename>. If your port
- requires a lot of files to be fetched, or contains a file that
- has a name that might conflict with other ports (e.g.,
- <filename>Makefile</filename>), set <makevar>DIST_SUBDIR</makevar> to the name of the
- port (<makevar>PKGNAME</makevar> without the
- version part should work fine). This will change <makevar>DISTDIR</makevar> from the default
- <filename>/usr/ports/distfiles</filename> to
- <filename>/usr/ports/distfiles/<makevar>DIST_SUBDIR</makevar></filename>,
- and in effect puts everything that is required for your port
- into that subdirectory.</para>
-
- <para>It will also look at the subdirectory with the same name
- on the backup master site at
- <filename>ftp.freebsd.org</filename>. (Setting <makevar>DISTDIR</makevar> explicitly in your
- <makevar>Makefile</makevar> will not accomplish this, so please use <makevar>DIST_SUBDIR</makevar>.)</para>
-
- <note>
- <para>This does not affect the <makevar>MASTER_SITES</makevar> you define in your
- Makefile.</para>
- </note>
- </sect4>
-
- <sect4>
- <title>Package information</title>
-
- <para>Do include package information, i.e.
- <filename>COMMENT</filename>, <filename>DESCR</filename>, and
- <filename>PLIST</filename>, in <filename>pkg</filename>.</para>
-
- <note>
- <para>Note that these files are not used only for packaging
- anymore, and are <emphasis>mandatory</emphasis> now, even if
- <makevar>NO_PACKAGE</makevar> is
- set.</para>
- </note>
- </sect4>
-
- <sect4>
- <title>Feedback</title>
-
- <para>Do send applicable changes/patches to the original
- author/maintainer for inclusion in next release of the code.
- This will only make your job that much easier for the next
- release.</para>
-
- </sect4>
-
- <sect4>
- <title>RCS strings</title>
-
- <para>Do not put RCS strings in patches. CVS will mangle them
- when we put the files into the ports tree, and when we check
- them out again, they will come out different and the patch
- will fail. RCS strings are surrounded by dollar (<literal>$</literal>) signs, and typically start with
- <literal>$Id</literal> or <literal>$RCS</literal>.</para>
-
- </sect4>
-
- <sect4>
- <title>Recursive diff</title>
-
- <para>Using the recurse (<option>-r</option>) option to
- <command>diff</command> to generate patches is
- fine, but please take a look at the resulting patches to make
- sure you don't have any unnecessary junk in there. In
- particular, diffs between two backup files, <filename>Makefiles</filename> when the
- port uses <command>Imake</command> or GNU <command>configure</command>, etc., are unnecessary and
- should be deleted. Also, if you had to delete a file, then you
- can do it in the <maketarget>post-extract</maketarget>
- target rather than as part of the patch. Once you are happy
- with the resulting diff, please split it up into one source
- file per patch file.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>PREFIX</makevar></title>
-
- <para>Do try to make your port install relative to <makevar>PREFIX</makevar>. (The value of this
- variable will be set to <makevar>LOCALBASE</makevar> (default
- <filename>/usr/local</filename>), unless <makevar>USE_X_PREFIX</makevar> or <makevar>USE_IMAKE</makevar> is set, in which case it
- will be <makevar>X11BASE</makevar> (default
- <filename>/usr/X11R6</filename>).)</para>
-
- <para>Not hard-coding <filename>/usr/local</filename> or
- <filename>/usr/X11R6</filename> anywhere in the source will
- make the port much more flexible and able to cater to the
- needs of other sites. For X ports that use <command>imake</command>, this is
- automatic; otherwise, this can often be done by simply
- replacing the occurrences of <filename>/usr/local</filename>
- (or <filename>/usr/X11R6</filename> for X ports that do not
- use imake) in the various scripts/Makefiles in the port to
- read <makevar>PREFIX</makevar>, as this
- variable is automatically passed down to every stage of the
- build and install processes.</para>
-
- <para>Do not set <makevar>USE_X_PREFIX</makevar> unless your port
- truly require it (i.e., it links against X libs or it needs to
- reference files in <makevar>X11BASE</makevar>.</para>
-
- <para>The variable <makevar>PREFIX</makevar>
- can be reassigned in your <filename>Makefile</filename> or in the user's
- environment. However, it is strongly discouraged for
- individual ports to set this variable explicitly in the
- <filename>Makefiles</filename>.</para>
-
- <para>Also, refer to programs/files from other ports with the
- variables mentioned above, not explicit pathnames. For
- instance, if your port requires a macro
- <literal>PAGER</literal> to be the full pathname of <command>less</command>, use the compiler flag:
-
- <programlisting>
--DPAGER=\"${PREFIX}/bin/less\"</programlisting>
-
- or
-
- <programlisting>
--DPAGER=\"${LOCALBASE}/bin/less\"</programlisting>
-
- if this is an X port, instead of <literal>-DPAGER=\"/usr/local/bin/less\".</literal> This way it will have a better chance of working if the system administrator has moved the whole `/usr/local' tree somewhere else.</para>
-
- </sect4>
-
- <sect4>
- <title>Subdirectories</title>
-
- <para>Try to let the port put things in the right subdirectories
- of <makevar>PREFIX</makevar>. Some ports
- lump everything and put it in the subdirectory with the port's
- name, which is incorrect. Also, many ports put everything
- except binaries, header files and manual pages in the a
- subdirectory of <filename>lib</filename>, which does not
- bode well with the BSD paradigm. Many of the files should be
- moved to one of the following: <filename>etc</filename>
- (setup/configuration files), <filename>libexec</filename>
- (executables started internally), <filename>sbin</filename>
- (executables for superusers/managers),
- <filename>info</filename> (documentation for info browser)
- or <filename>share</filename> (architecture independent
- files). See man <citerefentry><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
- details, the rule governing <filename>/usr</filename> pretty
- much applies to <filename>/usr/local</filename> too. The
- exception are ports dealing with USENET “news”. They may use
- <filename><makevar>PREFIX</makevar>/news</filename> as a destination for
- their files.</para>
-
- </sect4>
-
- <sect4>
- <title>ldconfig</title>
-
- <para>If your port installs a shared library, add a <maketarget>post-install</maketarget> target to your Makefile
- that runs <command>/sbin/ldconfig -m</command> on
- the directory where the new library is installed (usually
- <filename><makevar>PREFIX</makevar>/lib</filename>) to register it into
- the shared library cache.</para>
-
- <para>Also, add an <literal>@exec</literal> line to your
- <filename>pkg/PLIST</filename> file so that a user who
- installed the package can start using the shared library
- immediately. This line should immediately follow the line
- for the shared library itself, as in:</para>
-
- <programlisting>
-lib/libtcl80.so.1.0
-@exec /sbin/ldconfig -m %D/lib</programlisting>
-
- <para>Never, ever, <emphasis>ever</emphasis> add a line that
- says <command>ldconfig</command> without any
- arguments to your <filename>Makefile</filename> or <filename>pkg/PLIST</filename>. This will reset the
- shared library cache to the contents of
- <filename>/usr/lib</filename> only, and will royally screw up
- the user's machine (“Help, xinit does not run anymore after I
- install this port!”). Anybody who does this will be shot and
- cut into 65,536 pieces by a rusty knife and have his liver
- chopped out by a bunch of crows and will eternally rot to
- death in the deepest bowels of hell (not necessarily in that
- order)....</para>
-
- </sect4>
-
- <sect4>
- <title>UIDs</title>
-
- <para>If your port requires a certain user to be on the
- installed system, let the <filename>pkg/INSTALL</filename>
- script call <command>pw</command> to create it
- automatically. Look at <filename>net/cvsup-mirror</filename>
- for an example.</para>
-
- <para>If your port must use the same user/group ID number when it is
- installed a binarypackage as when it was compiled, then you mus
- choose a free UID from 50 to 99 and register it below. Look at
- <filename>japanese/Wnn</filename> for an example.</para>
-
- <para>Make sure you don't use a UID already used by the system
- or other ports. This is the current list of UIDs between 50
- and 99.</para>
-
- <programlisting>
-majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent
-cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent
-gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh
-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:/nonexistent
-wnn:*:69:7:Wnn:/nonexistent:/nonexistent
-ifmail:*:70:66:Ifmail user:/nonexistent:/nonexistent
-pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh
-ircd:*:72:72:IRCd hybrid:/nonexistent:/nonexistent
-alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent
-qmaill:*:83:81:QMail user:/var/qmail:/nonexistent
-qmaild:*:82:81:QMail user:/var/qmail:/nonexistent
-qmailq:*:85:82:QMail user:/var/qmail:/nonexistent
-qmails:*:87:82:QMail user:/var/qmail:/nonexistent
-qmailp:*:84:81:QMail user:/var/qmail:/nonexistent
-qmailr:*:86:82:QMail user:/var/qmail:/nonexistent
-msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh</programlisting>
-
- <para>Please include a notice when you submit a port (or an
- upgrade) that reserves a new UID or GID in this range. This allows
- us to keep the list of reserved IDs up to date.</para>
-
- </sect4>
-
- <sect4>
- <title>Doing things rationally</title>
-
- <para>The <filename>Makefile</filename> should do things simply and
- reasonably. If you can make it a couple of lines shorter or more
- readable, then do so. Examples include using a make
- <literal>.if</literal> construct instead of a shell
- <literal>if</literal> construct, not redefining
- <maketarget>do-extract</maketarget> if you can redefine
- <makevar>EXTRACT*</makevar> instead, and using
- <makevar>GNU_CONFIGURE</makevar> instead of
- <literal>CONFIGURE_ARGS +=
- --prefix=${PREFIX}</literal>.</para>
- </sect4>
-
- <sect4>
- <title>Respect <makevar>CFLAGS</makevar></title>
-
- <para>The port should respect the <makevar>CFLAGS</makevar>
- variable. If it doesn't, please add <literal>NO_PACKAGE=ignores
- cflags</literal> to the <filename>Makefile</filename>.</para>
- </sect4>
-
- <sect4>
- <title>Miscellanea</title>
-
- <para>The files <filename>pkg/DESCR</filename>,
- <filename>pkg/COMMENT</filename>, and
- <filename>pkg/PLIST</filename> should each be double-checked. If
- you are reviewing a port and feel they can be worded better, do
- so.</para>
-
- <para>Don't copy more copies of the GNU General Public License into
- our system, please.</para>
-
- <para>Please be careful to note any legal issues! Don't let us
- illegally distribute software!</para>
- </sect4>
-
- <sect4>
- <title>If you are stuck....</title>
-
- <para>Do look at existing examples and the
- <filename>bsd.port.mk</filename> file before asking us
- questions! <!-- smiley --><emphasis>;)</emphasis></para>
-
- <para>Do ask us questions if you have any trouble! Do not just
- beat your head against a wall! <!-- smiley --><emphasis>:)</emphasis></para>
-
- </sect4>
- </sect3>
-
- <sect3 id="porting-samplem">
- <title>A Sample <filename>Makefile</filename></title>
-
- <para>Here is a sample <filename>Makefile</filename> that you can
- use to create a new port. Make sure you remove all the extra
- comments (ones between brackets)!</para>
-
- <para>It is recommended that you follow this format (ordering of
- variables, empty lines between sections, etc.). Not all of the
- existing <filename>Makefile</filename>s are in this format
- (mostly old ones), but we are trying to uniformize how they
- look. This format is designed so that the most important
- information is easy to locate.</para>
-
- <programlisting>
-[the header...just to make it easier for us to identify the ports.]
-# New ports collection makefile for: xdvi
-[the version required header should updated when upgrading a port.]
-# Version required: pl18 [things like "1.5alpha" are fine here too]
-[this is the date when the first version of this Makefile was created.
-Never change this when doing an update of the port.]
-# Date created: 26 May 1995
-[this is the person who did the original port to FreeBSD, in particular, the
-person who wrote the first version of this Makefile. Remember, this should
-not be changed when upgrading the port later.]
-# Whom: Satoshi Asami <asami@FreeBSD.ORG>
-#
-# $Id$
-[ ^^^^ This will be automatically replaced with RCS ID string by CVS
-when it is committed to our repository.]
-#
-
-[section to describe the port itself and the master site - DISTNAME
- is always first, followed by PKGNAME (if necessary), CATEGORIES,
- and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR.
- After those, one of EXTRACT_SUFX or DISTFILES can be specified too.]
-DISTNAME= xdvi
-PKGNAME= xdvi-pl18
-CATEGORIES= print
-[do not forget the trailing slash ("/")!
- if you aren't using MASTER_SITE_* macros]
-MASTER_SITES= ${MASTER_SITE_XCONTRIB}
-MASTER_SITE_SUBDIR= applications
-[set this if the source is not in the standard ".tar.gz" form]
-EXTRACT_SUFX= .tar.Z
-
-[section for distributed patches -- can be empty]
-PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/
-PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz
-
-[maintainer; *mandatory*! This is the person (preferably with commit
- privileges) who a user can contact for questions and bug reports - this
- person should be the porter or someone who can forward questions to the
- original porter reasonably promptly. If you really do not want to have
- your address here, set it to "ports@FreeBSD.ORG".]
-MAINTAINER= asami@FreeBSD.ORG
-
-[dependencies -- can be empty]
-RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript
-LIB_DEPENDS= Xpm\\.4\\.:${PORTSDIR}/graphics/xpm
-
-[this section is for other standard bsd.port.mk variables that do not
- belong to any of the above]
-[If it asks questions during configure, build, install...]
-IS_INTERACTIVE= yes
-[If it extracts to a directory other than ${DISTNAME}...]
-WRKSRC= ${WRKDIR}/xdvi-new
-[If the distributed patches were not made relative to ${WRKSRC}, you
- may need to tweak this]
-PATCH_DIST_STRIP= -p1
-[If it requires a "configure" script generated by GNU autoconf to be run]
-GNU_CONFIGURE= yes
-[If it requires GNU make, not /usr/bin/make, to build...]
-USE_GMAKE= yes
-[If it is an X application and requires "xmkmf -a" to be run...]
-USE_IMAKE= yes
-[et cetera.]
-
-[non-standard variables to be used in the rules below]
-MY_FAVORITE_RESPONSE= "yeah, right"
-
-[then the special rules, in the order they are called]
-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
-
-[and then the epilogue]
-.include <bsd.port.mk></programlisting>
-
- </sect3>
-
- <sect3>
- <title>Package Names</title>
-
- <para>The following are the conventions you should follow in
- naming your packages. This is to have our package directory
- easy to scan, as there are already lots and lots of packages and
- users are going to turn away if they hurt their eyes!</para>
-
- <para>The package name should look like <filename><replaceable>language-</replaceable>name<replaceable>-compiled.specifics</replaceable><replaceable>-version.numbers</replaceable></filename>.</para>
-
- <para>If your <makevar>DISTNAME</makevar>
- doesn't look like that, set <makevar>PKGNAME</makevar> to something in that
- format.</para>
-
-
- <orderedlist>
-
- <listitem>
- <para>FreeBSD strives to support the native language of its
- users. The <replaceable>language-</replaceable> part should be a two letter
- abbreviation of the natural language defined by ISO-639 if
- the port is specific to a certain language. Examples are
- <literal>ja</literal> for Japanese, <literal>ru</literal> for Russian, <literal>vi</literal> for Vietnamese,
- <literal>zh</literal> for Chinese, <literal>ko</literal> for Korean and <literal>de</literal> for German.</para>
- </listitem>
-
- <listitem>
- <para>The <filename>name</filename> part
- should be all lowercases, except for a really large
- package (with lots of programs in it). Things like
- XFree86 (yes there really is a package of it, check it
- out) and ImageMagick fall into this category. Otherwise,
- convert the name (or at least the first letter) to
- lowercase. If the capital letters are
- important to the name (for example, with one-letter names
- like <literal>R</literal> or <literal>V</literal>) you may use capital letters at your discretion.
- There is a tradition of naming Perl 5 modules by prepending
- <literal>p5-</literal> and converting the double-colon separator to a hyphen;
- for example, the <literal>Data::Dumper</literal> module becomes
- <literal>p5-Data-Dumper</literal>. If the software in question has numbers,
- hyphens, or underscores in its name, you may include them as
- well (like <literal>kinput2</literal>).</para>
- </listitem>
-
- <listitem>
- <para>If the port can be built with different hardcoded
- defaults (usually specified as environment variables or on
- the <command>make</command> command line), the
- <replaceable>-compiled.specifics</replaceable> part should state the
- compiled-in defaults (the hyphen is optional). Examples
- are papersize and font units.</para>
- </listitem>
-
- <listitem>
- <para>The version string should be a period-separated list
- of integers and single lowercase alphabetics. The only
- exception is the string <literal>pl</literal> (meaning `patchlevel'), which
- can be used <emphasis>only</emphasis> when there are no
- major and minor version numbers in the software.</para>
- </listitem>
-
- </orderedlist>
-
-
- <para>Here are some (real) examples on how to convert a <makevar>DISTNAME</makevar> into a suitable <makevar>PKGNAME</makevar>:</para>
-
- <informaltable frame="none">
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Distribution Name</entry>
- <entry>Package Name</entry>
- <entry>Reason</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>mule-2.2.2.</entry>
- <entry>mule-2.2.2</entry>
- <entry>No changes required</entry>
- </row>
-
- <row>
- <entry>XFree86-3.1.2</entry>
- <entry>XFree86-3.1.2</entry>
- <entry>No changes required</entry>
- </row>
-
- <row>
- <entry>EmiClock-1.0.2</entry>
- <entry>emiclock-1.0.2</entry>
- <entry>No uppercase names for single programs</entry>
- </row>
-
- <row>
- <entry>gmod1.4</entry>
- <entry>gmod-1.4</entry>
- <entry>Need a hyphen before version numbers</entry>
- </row>
-
- <row>
- <entry>xmris.4.0.2</entry>
- <entry>xmris-4.0.2</entry>
- <entry>Need a hyphen before version numbers</entry>
- </row>
-
- <row>
- <entry>rdist-1.3alpha</entry>
- <entry>rdist-1.3a</entry>
- <entry>No strings like <literal>alpha</literal>
- allowed</entry>
- </row>
-
- <row>
- <entry>es-0.9-beta1</entry>
- <entry>es-0.9b1</entry>
- <entry>No strings like <literal>beta</literal>
- allowed</entry>
- </row>
-
- <row>
- <entry>v3.3beta021.src</entry>
- <entry>tiff-3.3</entry>
- <entry>What the heck was that anyway?</entry>
- </row>
-
- <row>
- <entry>tvtwm</entry>
- <entry>tvtwm-pl11</entry>
- <entry>Version string always required</entry>
- </row>
-
- <row>
- <entry>piewm</entry>
- <entry>piewm-1.0</entry>
- <entry>Version string always required</entry>
- </row>
-
- <row>
- <entry>xvgr-2.10pl1</entry>
- <entry>xvgr-2.10.1</entry>
- <entry><literal>pl</literal> allowed only when no
- major/minor version numbers</entry>
- </row>
-
- <row>
- <entry>gawk-2.15.6</entry>
- <entry>ja-gawk-2.15.6</entry>
- <entry>Japanese language version</entry>
- </row>
-
- <row>
- <entry>psutils-1.13</entry>
- <entry>psutils-letter-1.13</entry>
- <entry>Papersize hardcoded at package build time</entry>
- </row>
-
- <row>
- <entry>pkfonts</entry>
- <entry>pkfonts300-1.0</entry>
- <entry>Package for 300dpi fonts</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>If there is absolutely no trace of version information in
- the original source and it is unlikely that the original author
- will ever release another version, just set the version string
- to <literal>1.0</literal> (like the piewm example above). Otherwise, ask the
- original author or use the date string (<literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>) as the
- version.</para>
-
- </sect3>
-
- <sect3>
- <title>Changes to this document and the ports system</title>
-
- <para>If you maintain a lot of ports, you should consider following
- the <email>ports@FreeBSD.ORG</email> mailing-list. Important changes to
- the way ports work will be announced there. You can always
- find more detailed information on the latest changes by
- looking at <ulink
- url="http://www.FreeBSD.ORG/cgi/cvsweb.cgi/src/share/mk/bsd.port.mk">
- the bsd.port.mk CVS log</ulink>.</para>
- </sect3>
-
- <sect3>
- <title>That is It, Folks!</title>
-
- <para>Boy, this sure was a long tutorial, wasn't it? Thanks for
- following us to here, really.</para>
-
- <para>Well, now that you know how to do a port, let us go at it
- and convert everything in the world into ports! That is the
- easiest way to start contributing to the FreeBSD Project!
- <!-- smiley --><emphasis>:)</emphasis></para>
-
- </sect3>
- </sect2>
-
<sect2>
<title>Money, Hardware or Internet access</title>
@@ -3763,18 +1240,14 @@ box can be opened)</para>
<para>Ari Suutari <email>ari@suutari.iki.fi</email></para>
</listitem>
- <listitem>
- <para>Brent J. Nordquist <email>bjn@visi.com</email></para>
- </listitem>
-
+ <listitem>
+ <para>Ben Hutchinson <email>benhutch@xfiles.org.uk</email></para>
+ </listitem>
+
<listitem>
<para>Bernd Rosauer <email>br@schiele-ct.de</email></para>
</listitem>
- <listitem>
- <para>Bill Fumerola <email>billf@jade.chc-chimes.com</email></para>
- </listitem>
-
<listitem>
<para>Bill Kish <email>kish@osf.org</email></para>
</listitem>
@@ -3899,7 +1372,11 @@ box can be opened)</para>
<listitem>
<para>Chuck Hein <email>chein@cisco.com</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Clive Lin <email>clive@CiRX.ORG</email></para>
+ </listitem>
+
<listitem>
<para>Conrad Sabatier <email>conrads@neosoft.com</email></para>
</listitem>
@@ -4102,6 +1579,10 @@ box can be opened)</para>
<email>ginga@amalthea.phys.s.u-tokyo.ac.jp</email></para>
</listitem>
+ <listitem>
+ <para>Glenn Johnson <email>gljohns@bellsouth.net</email></para>
+ </listitem>
+
<listitem>
<para>Greg Ungerer <email>gerg@stallion.oz.au</email></para>
</listitem>
@@ -4141,7 +1622,11 @@ box can be opened)</para>
<listitem>
<para>Hironori Ikura <email>hikura@kaisei.org</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Hiroyuki NAKAJI <email>nakaji@zeisei3.dpri.kyoto-u.ac.jp</email></para>
+ </listitem>
+
<listitem>
<para>Holger Veit <email>Holger.Veit@gmd.de</email></para>
</listitem>
@@ -4182,10 +1667,6 @@ box can be opened)</para>
<para>Ishii Masahiro</para>
</listitem>
- <listitem>
- <para>Issei Suzuki <email>issei@t-cnet.or.jp</email></para>
- </listitem>
-
<listitem>
<para>Iseei Suzuki <email>issei@jp.FreeBSD.ORG</email></para>
</listitem>
@@ -4242,6 +1723,10 @@ box can be opened)</para>
<para>Jeffrey Wheat <email>jeff@cetlink.net</email></para>
</listitem>
+ <listitem>
+ <para>Jeremy Lea <email>reg@shale.csir.co.za</email></para>
+ </listitem>
+
<listitem>
<para>Jerry Hicks <email>jhicks@glenatl.glenayre.com</email></para>
</listitem>
@@ -4686,7 +2171,11 @@ box can be opened)</para>
<listitem>
<para>Randall Hopper <email>rhh@stealth.ct.picker.com</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Ricardas Cepas <email>rch@richard.eu.org</email></para>
+ </listitem>
+
<listitem>
<para>Richard Hwang <email>rhwang@bigpanda.com</email></para>
</listitem>
@@ -4739,10 +2228,6 @@ box can be opened)</para>
<para>Ruslan Shevchenko <email>rssh@cki.ipri.kiev.ua</email></para>
</listitem>
- <listitem>
- <para>SADA Kenji <email>sada@e-mail.ne.jp</email></para>
- </listitem>
-
<listitem>
<para>SURANYI Peter <email>suranyip@jks.is.tsukuba.ac.jp</email></para>
</listitem>
@@ -4986,7 +2471,11 @@ box can be opened)</para>
<listitem>
<para>Yen-Shuo Su <email>yssu@CCCA.NCTU.edu.tw</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Ying-Chieh Liao <email>ijliao@csie.NCTU.edu.tw</email></para>
+ </listitem>
+
<listitem>
<para>Yoshiaki Uchikawa <email>yoshiaki@kt.rim.or.jp</email></para>
</listitem>
@@ -4998,7 +2487,11 @@ box can be opened)</para>
<listitem>
<para>Yukihiro Nakai <email>nakai@technologist.com</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Yusuke Nawano <email>azuki@azkey.org</email></para>
+ </listitem>
+
<listitem>
<para>Yuval Yarom <email>yval@cs.huji.ac.il</email></para>
</listitem>
@@ -5133,7 +2626,7 @@ box can be opened)</para>
</listitem>
<listitem>
- <para>Guido van Rooij <email>guido@gvr.win.tue.nl</email></para>
+ <para>Guido van Rooij <email>guido@gvr.org</email></para>
</listitem>
<listitem>
@@ -5216,7 +2709,11 @@ box can be opened)</para>
<listitem>
<para>Julian Stacey <email>jhs@freebsd.org</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Karl Dietz <email>Karl.Dietz@triplan.com</email></para>
+ </listitem>
+
<listitem>
<para>Karl Lehenbauer <email>karl@NeoSoft.com</email> <email>karl@one.neosoft.com</email></para>
</listitem>
@@ -5391,9 +2888,7 @@ box can be opened)</para>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/cutting-edge/chapter.sgml b/en/handbook/cutting-edge/chapter.sgml
index 51cb7a5561..93ceb6062b 100644
--- a/en/handbook/cutting-edge/chapter.sgml
+++ b/en/handbook/cutting-edge/chapter.sgml
@@ -275,14 +275,21 @@ subscribe cvs-all</programlisting>
<programlisting>
subscribe freebsd-stable</programlisting> In the body of your
- message. Optionally, you can also say `help' and Majordomo
+ message. Optionally, you can also say <literal>help</literal> and Majordomo
will send you full help on how to subscribe and unsubscribe
to the various other mailing lists we support.</para>
</listitem>
<listitem>
- <para>Grab the sources from <hostid role="fqdn">ftp.FreeBSD.ORG</hostid>. You can do
- this in three ways:</para>
+ <para>If you are installing a new system and want it to be as stable
+ as possible, you can simply grab the latest dated branch snapshot
+ from <ulink
+ url="ftp://releng22.freebsd.org/pub/FreeBSD/">ftp://releng22.freebsd.org/pub/FreeBSD/</ulink> and install it like any other release.</para>
+
+ <para>If you are already running a previous release of 2.2 and wish
+ to upgrade via sources then you can easily do so from <hostid
+ role="fqdn">ftp.FreeBSD.ORG</hostid>. This can be done in one of
+ three ways:</para>
<orderedlist>
@@ -295,7 +302,11 @@ subscribe freebsd-stable</programlisting> In the body of your
<listitem>
<para>Use the <link linkend="cvsup">cvsup</link>
program with <ulink
- URL="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/stable-supfile">this supfile</ulink>. This is the second most recommended method, since it allows you to grab the entire collection once and then only what has changed from then on. Many people run cvsup from cron to keep their sources up-to-date automatically.</para>
+ URL="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/stable-supfile">this supfile</ulink>. This is the second most recommended method, since it allows you to grab the entire collection once and then only what has changed from then on. Many people run cvsup from cron to keep their sources up-to-date automatically. For a fairly easy interface to this, simply type;</para>
+
+ <informalexample>
+ <screen>&prompt.root; <userinput>pkg_add -f ftp://ftp.freebsd.org/pub/FreeBSD/CVSup/cvsupit.tgz</userinput></screen>
+ </informalexample>
</listitem>
<listitem>
@@ -2479,9 +2490,7 @@ cvs-crypto</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/eresources/chapter.sgml b/en/handbook/eresources/chapter.sgml
index 65f8af855a..c1fcd45ce2 100644
--- a/en/handbook/eresources/chapter.sgml
+++ b/en/handbook/eresources/chapter.sgml
@@ -320,101 +320,11 @@
</thead>
<tbody>
- <row>
- <entry>cvs-CVSROOT</entry>
- <entry>/usr/src/[A-Z]*</entry>
- <entry>Top level /usr/src file changes</entry>
- </row>
-
<row>
<entry>cvs-all</entry>
<entry>/usr/src</entry>
<entry>All changes to the tree (superset)</entry>
</row>
-
- <row>
- <entry>cvs-bin</entry>
- <entry>/usr/src/bin</entry>
- <entry>System binaries</entry>
- </row>
-
- <row>
- <entry>cvs-etc</entry>
- <entry>/usr/src/etc</entry>
- <entry>System files</entry>
- </row>
-
- <row>
- <entry>cvs-games</entry>
- <entry>/usr/src/games</entry>
- <entry>Games</entry>
- </row>
-
- <row>
- <entry>cvs-gnu</entry>
- <entry>/usr/src/gnu</entry>
- <entry>GPL'd utilities</entry>
- </row>
-
- <row>
- <entry>cvs-include</entry>
- <entry>/usr/src/include</entry>
- <entry>Include files</entry>
- </row>
-
- <row>
- <entry>cvs-kerberosIV</entry>
- <entry>/usr/src/kerberosIV</entry>
- <entry>Kerberos encryption code</entry>
- </row>
-
- <row>
- <entry>cvs-lib</entry>
- <entry>/usr/src/lib</entry>
- <entry>System libraries</entry>
- </row>
-
- <row>
- <entry>cvs-libexec</entry>
- <entry>/usr/src/libexec</entry>
- <entry>System binaries</entry>
- </row>
-
- <row>
- <entry>cvs-ports</entry>
- <entry>/usr/ports</entry>
- <entry>Ported software</entry>
- </row>
-
- <row>
- <entry>cvs-sbin</entry>
- <entry>/usr/src/sbin</entry>
- <entry>System binaries</entry>
- </row>
-
- <row>
- <entry>cvs-share</entry>
- <entry>/usr/src/share</entry>
- <entry>System shared files</entry>
- </row>
-
- <row>
- <entry>cvs-sys</entry>
- <entry>/usr/src/sys</entry>
- <entry>Kernel</entry>
- </row>
-
- <row>
- <entry>cvs-usrbin</entry>
- <entry>/usr/src/usr.bin</entry>
- <entry>Use binaries</entry>
- </row>
-
- <row>
- <entry>cvs-usrsbin</entry>
- <entry>/usr/src/usr.sbin</entry>
- <entry>System binaries</entry>
- </row>
</tbody>
</tgroup>
</informaltable>
@@ -1226,9 +1136,7 @@ help
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/handbook.sgml b/en/handbook/handbook.sgml
index 78ff7e72ca..a4c9c067df 100644
--- a/en/handbook/handbook.sgml
+++ b/en/handbook/handbook.sgml
@@ -3,7 +3,10 @@
<!ENTITY % authors SYSTEM "authors.ent"> %authors;
<!ENTITY % mailing-lists SYSTEM "mailing-lists.ent"> %mailing-lists;
-<!ENTITY rel.current CDATA "3.0">
+<!-- The currently released version of FreeBSD. This value is used to
+ create some links on web sites and such, so do NOT change it until
+ it's really release time -->
+<!ENTITY rel.current CDATA "2.2.8">
]>
<book>
@@ -103,8 +106,6 @@ url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/docs/">FreeBSD FTP server</ulink> or one
mode: sgml
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
End:
-->
diff --git a/en/handbook/hw/chapter.sgml b/en/handbook/hw/chapter.sgml
index 111cde9410..867deea2f8 100644
--- a/en/handbook/hw/chapter.sgml
+++ b/en/handbook/hw/chapter.sgml
@@ -5677,9 +5677,7 @@ scsi -f $2 -s 100 -c "1b 0 0 $cdb3 $cdb4 $cdb5"</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/install/chapter.sgml b/en/handbook/install/chapter.sgml
index 52485fd470..b11bbc33d0 100644
--- a/en/handbook/install/chapter.sgml
+++ b/en/handbook/install/chapter.sgml
@@ -1225,9 +1225,7 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/internals/chapter.sgml b/en/handbook/internals/chapter.sgml
index e29013c26f..fe94901ffc 100644
--- a/en/handbook/internals/chapter.sgml
+++ b/en/handbook/internals/chapter.sgml
@@ -1657,9 +1657,7 @@
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/introduction/chapter.sgml b/en/handbook/introduction/chapter.sgml
index a65b2bd0a8..163e13428a 100644
--- a/en/handbook/introduction/chapter.sgml
+++ b/en/handbook/introduction/chapter.sgml
@@ -615,9 +615,7 @@
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/kernelconfig/chapter.sgml b/en/handbook/kernelconfig/chapter.sgml
index 42ce6deda9..94265ff68d 100644
--- a/en/handbook/kernelconfig/chapter.sgml
+++ b/en/handbook/kernelconfig/chapter.sgml
@@ -1695,9 +1695,7 @@ controller wcd0</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/kerneldebug/chapter.sgml b/en/handbook/kerneldebug/chapter.sgml
index f4d06bba3a..796252e1d3 100644
--- a/en/handbook/kerneldebug/chapter.sgml
+++ b/en/handbook/kerneldebug/chapter.sgml
@@ -660,9 +660,7 @@ text_addr = 0xf5109020? (y or n) <userinput>y</userinput>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/kernelopts/chapter.sgml b/en/handbook/kernelopts/chapter.sgml
index 30f5e9f461..0e6defe0cb 100644
--- a/en/handbook/kernelopts/chapter.sgml
+++ b/en/handbook/kernelopts/chapter.sgml
@@ -166,9 +166,7 @@ options notyet,notdef</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/l10n/chapter.sgml b/en/handbook/l10n/chapter.sgml
index 4fda3de2f8..7ab182a604 100644
--- a/en/handbook/l10n/chapter.sgml
+++ b/en/handbook/l10n/chapter.sgml
@@ -357,9 +357,7 @@ XkbKeymap "xfree86(ru)"</programlisting> line into
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/linuxemu/chapter.sgml b/en/handbook/linuxemu/chapter.sgml
index 187301676e..0e2bc3b76d 100644
--- a/en/handbook/linuxemu/chapter.sgml
+++ b/en/handbook/linuxemu/chapter.sgml
@@ -853,9 +853,7 @@ richc.isdn.bcm.tmc.edu 9845-03452-90255</screen>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/mail/chapter.sgml b/en/handbook/mail/chapter.sgml
index e4c2d14f9e..18b2d73610 100644
--- a/en/handbook/mail/chapter.sgml
+++ b/en/handbook/mail/chapter.sgml
@@ -586,9 +586,7 @@ an A record in the DNS for "customer.com".</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/mirrors/chapter.sgml b/en/handbook/mirrors/chapter.sgml
index bfef299630..0f4423b959 100644
--- a/en/handbook/mirrors/chapter.sgml
+++ b/en/handbook/mirrors/chapter.sgml
@@ -29,7 +29,13 @@
<para><ulink
URL="ftp://ftp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.FreeBSD.ORG/pub/FreeBSD</ulink>.</para>
</blockquote></para>
-
+
+ <para>The <ulink
+ url="http://www.itworks.com.au/~gavin/FBSDsites.php3">FreeBSD mirror
+ sites database</ulink> is more accurate than the mirror listing in the
+ handbook, as it gets its information form the DNS rather than relying
+ on static lists of hosts.</para>
+
<para>Additionally, FreeBSD is available via anonymous FTP from the
following mirror sites. If you choose to obtain FreeBSD via
anonymous FTP, please try to use a site near you.</para>
@@ -76,7 +82,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ar.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ar.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.ar.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ar.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -95,22 +101,22 @@
<listitem>
<para><ulink
- URL="ftp://ftp.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.au.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.au.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.au.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.au.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.au.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.au.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp4.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.au.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp4.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.au.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -129,37 +135,37 @@
<listitem>
<para><ulink
- URL="ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp4.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp4.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp5.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp5.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp6.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp6.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp7.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp7.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp7.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp7.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -178,7 +184,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ca.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ca.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.ca.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ca.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -194,7 +200,7 @@
<listitem>
<para><ulink
- URL="ftp://sunsite.mff.cuni.cz/OS/FreeBSD">ftp://sunsite.mff.cuni.cz/OS/FreeBSD</ulink><!-- <br> --> Contact: <email>jj@sunsite.mff.cuni.cz</email>.</para>
+ URL="ftp://sunsite.mff.cuni.cz/OS/FreeBSD">ftp://sunsite.mff.cuni.cz/OS/FreeBSD</ulink> Contact: <email>jj@sunsite.mff.cuni.cz</email>.</para>
</listitem>
</itemizedlist>
@@ -213,7 +219,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.dk.freeBSD.ORG/pub/FreeBSD">ftp://ftp.dk.freeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.dk.freeBSD.ORG/pub/FreeBSD">ftp://ftp.dk.freeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -232,7 +238,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ee.freebsd.ORG/pub/FreeBSD">ftp://ftp.ee.freebsd.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.ee.freebsd.ORG/pub/FreeBSD">ftp://ftp.ee.freebsd.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -251,7 +257,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.fi.freebsd.ORG/pub/FreeBSD">ftp://ftp.fi.freebsd.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.fi.freebsd.ORG/pub/FreeBSD">ftp://ftp.fi.freebsd.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -267,7 +273,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ibp.fr/pub/FreeBSD">ftp://ftp.ibp.fr/pub/FreeBSD</ulink><!-- <br> --> Contact: <email>Remy.Card@ibp.fr</email>.</para>
+ URL="ftp://ftp.ibp.fr/pub/FreeBSD">ftp://ftp.ibp.fr/pub/FreeBSD</ulink> Contact: <email>Remy.Card@ibp.fr</email>.</para>
</listitem>
</itemizedlist>
@@ -286,37 +292,37 @@
<listitem>
<para><ulink
- URL="ftp://ftp.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp4.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp4.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp5.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp5.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp6.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp6.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp7.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp7.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp7.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp7.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -332,7 +338,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.hk.super.net/pub/FreeBSD">ftp://ftp.hk.super.net/pub/FreeBSD</ulink><!-- <br> --> Contact: <email>ftp-admin@HK.Super.NET</email>.</para>
+ URL="ftp://ftp.hk.super.net/pub/FreeBSD">ftp://ftp.hk.super.net/pub/FreeBSD</ulink> Contact: <email>ftp-admin@HK.Super.NET</email>.</para>
</listitem>
</itemizedlist>
@@ -351,7 +357,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ie.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ie.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.ie.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ie.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -370,12 +376,12 @@
<listitem>
<para><ulink
- URL="ftp://ftp.il.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.il.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.il.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.il.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.il.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.il.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.il.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.il.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -394,32 +400,32 @@
<listitem>
<para><ulink
- URL="ftp://ftp.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.jp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.jp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.jp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.jp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.jp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.jp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp4.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.jp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp4.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.jp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp5.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.jp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp5.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.jp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp6.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.jp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp6.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.jp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -438,14 +444,25 @@
<listitem>
<para><ulink
- URL="ftp://ftp.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.kr.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.kr.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.kr.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.kr.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
-
+
+ <listitem>
+ <para><ulink url="ftp://ftp3.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.kr.FreeBSD.ORG/pub/FreeBSD</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="ftp://ftp4.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.kr.FreeBSD.ORG/pub/FreeBSD</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="ftp://ftp5.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.kr.FreeBSD.ORG/pub/FreeBSD</ulink></para>
+ </listitem>
</itemizedlist>
</listitem>
@@ -462,7 +479,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.nl.freebsd.ORG/pub/FreeBSD">ftp://ftp.nl.freebsd.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.nl.freebsd.ORG/pub/FreeBSD">ftp://ftp.nl.freebsd.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -481,7 +498,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.pl.freebsd.ORG/pub/FreeBSD">ftp://ftp.pl.freebsd.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.pl.freebsd.ORG/pub/FreeBSD">ftp://ftp.pl.freebsd.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -500,12 +517,12 @@
<listitem>
<para><ulink
- URL="ftp://ftp.pt.freebsd.org/pub/FreeBSD">ftp://ftp.pt.freebsd.org/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.pt.freebsd.org/pub/FreeBSD">ftp://ftp.pt.freebsd.org/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.pt.freebsd.org/pub/FreeBSD">ftp://ftp2.pt.freebsd.org/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.pt.freebsd.org/pub/FreeBSD">ftp://ftp2.pt.freebsd.org/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -524,17 +541,17 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ru.freebsd.org/pub/FreeBSD">ftp://ftp.ru.freebsd.org/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.ru.freebsd.org/pub/FreeBSD">ftp://ftp.ru.freebsd.org/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.ru.freebsd.org/pub/FreeBSD">ftp://ftp2.ru.freebsd.org/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.ru.freebsd.org/pub/FreeBSD">ftp://ftp2.ru.freebsd.org/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.ru.freebsd.org/pub/FreeBSD">ftp://ftp3.ru.freebsd.org/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.ru.freebsd.org/pub/FreeBSD">ftp://ftp3.ru.freebsd.org/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
@@ -556,17 +573,17 @@
<listitem>
<para><ulink
- URL="ftp://ftp.za.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.za.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.za.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.za.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.za.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.za.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.za.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.za.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.za.FreeBSD.ORG/FreeBSD">ftp://ftp3.za.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.za.FreeBSD.ORG/FreeBSD">ftp://ftp3.za.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -600,7 +617,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.si.freebsd.ORG/pub/FreeBSD">ftp://ftp.si.freebsd.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.si.freebsd.ORG/pub/FreeBSD">ftp://ftp.si.freebsd.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -634,9 +651,19 @@
<listitem>
<para><ulink
- URL="ftp://ftp.se.freebsd.ORG/pub/FreeBSD">ftp://ftp.se.freebsd.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.se.freebsd.ORG/pub/FreeBSD">ftp://ftp.se.freebsd.ORG/pub/FreeBSD</ulink></para>
</listitem>
-
+
+ <listitem>
+ <para><ulink
+ URL="ftp://ftp2.se.freebsd.ORG/pub/FreeBSD">ftp://ftp2.se.freebsd.ORG/pub/FreeBSD</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ URL="ftp://ftp3.se.freebsd.ORG/pub/FreeBSD">ftp://ftp3.se.freebsd.ORG/pub/FreeBSD</ulink></para>
+ </listitem>
+
</itemizedlist>
</listitem>
@@ -653,17 +680,17 @@
<listitem>
<para><ulink
- URL="ftp://ftp.tw.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.tw.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.tw.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.tw.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.tw.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.tw.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.tw.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.tw.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.tw.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.tw.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.tw.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.tw.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -679,7 +706,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.nectec.or.th/pub/FreeBSD">ftp://ftp.nectec.or.th/pub/FreeBSD</ulink><!-- <br> --> Contact: <email>ftpadmin@ftp.nectec.or.th</email>.</para>
+ URL="ftp://ftp.nectec.or.th/pub/FreeBSD">ftp://ftp.nectec.or.th/pub/FreeBSD</ulink> Contact: <email>ftpadmin@ftp.nectec.or.th</email>.</para>
</listitem>
</itemizedlist>
@@ -695,7 +722,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ua.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ua.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --> Contact: <email>archer@lucky.net</email>.</para>
+ URL="ftp://ftp.ua.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ua.FreeBSD.ORG/pub/FreeBSD</ulink> Contact: <email>archer@lucky.net</email>.</para>
</listitem>
</itemizedlist>
@@ -714,22 +741,22 @@
<listitem>
<para><ulink
- URL="ftp://ftp.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.uk.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.uk.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.uk.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.uk.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.uk.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.uk.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp4.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.uk.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp4.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.uk.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -748,32 +775,32 @@
<listitem>
<para><ulink
- URL="ftp://ftp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp4.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp4.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp5.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp5.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp6.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp6.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -800,12 +827,12 @@
<listitem>
<para><ulink
- URL="ftp://ftp.internat.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.internat.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.internat.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.internat.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.internat.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.internat.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.internat.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.internat.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -824,7 +851,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -840,7 +867,7 @@
<listitem>
<para><ulink
- URL="ftp://nic.funet.fi/pub/unix/FreeBSD/eurocrypt">ftp://nic.funet.fi/pub/unix/FreeBSD/eurocrypt</ulink><!-- <br> --> Contact: <email>count@nic.funet.fi</email>.</para>
+ URL="ftp://nic.funet.fi/pub/unix/FreeBSD/eurocrypt">ftp://nic.funet.fi/pub/unix/FreeBSD/eurocrypt</ulink> Contact: <email>count@nic.funet.fi</email>.</para>
</listitem>
</itemizedlist>
@@ -871,7 +898,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.freebsd.org/pub/FreeBSD/CTM">ftp://ftp.freebsd.org/pub/FreeBSD/CTM</ulink><!-- <br> --></para>
+ URL="ftp://ftp.freebsd.org/pub/FreeBSD/CTM">ftp://ftp.freebsd.org/pub/FreeBSD/CTM</ulink></para>
</listitem>
</itemizedlist>
@@ -887,7 +914,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.uni-trier.de/pub/unix/systems/BSD/FreeBSD/CTM">ftp://ftp.uni-trier.de/pub/unix/systems/BSD/FreeBSD/CTM</ulink><!-- <br> --></para>
+ URL="ftp://ftp.uni-trier.de/pub/unix/systems/BSD/FreeBSD/CTM">ftp://ftp.uni-trier.de/pub/unix/systems/BSD/FreeBSD/CTM</ulink></para>
</listitem>
</itemizedlist>
@@ -904,7 +931,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.internat.freebsd.org/pub/FreeBSD/CTM">ftp://ftp.internat.freebsd.org/pub/FreeBSD/CTM</ulink><!-- <br> --></para>
+ URL="ftp://ftp.internat.freebsd.org/pub/FreeBSD/CTM">ftp://ftp.internat.freebsd.org/pub/FreeBSD/CTM</ulink></para>
</listitem>
</itemizedlist>
@@ -920,17 +947,17 @@
<listitem>
<para><ulink
- URL="ftp://ctm.tw.freebsd.org/pub/FreeBSD/CTM">ftp://ctm.tw.freebsd.org/pub/FreeBSD/CTM</ulink><!-- <br> --></para>
+ URL="ftp://ctm.tw.freebsd.org/pub/FreeBSD/CTM">ftp://ctm.tw.freebsd.org/pub/FreeBSD/CTM</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ctm2.tw.freebsd.org/pub/FreeBSD/CTM">ftp://ctm2.tw.freebsd.org/pub/FreeBSD/CTM</ulink><!-- <br> --></para>
+ URL="ftp://ctm2.tw.freebsd.org/pub/FreeBSD/CTM">ftp://ctm2.tw.freebsd.org/pub/FreeBSD/CTM</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ctm3.tw.freebsd.org/pub/freebsd/CTM">ftp://ctm3.tw.freebsd.org/pub/freebsd/CTM</ulink><!-- <br> --></para>
+ URL="ftp://ctm3.tw.freebsd.org/pub/freebsd/CTM">ftp://ctm3.tw.freebsd.org/pub/freebsd/CTM</ulink></para>
</listitem>
</itemizedlist>
@@ -1147,7 +1174,19 @@
</listitem>
</varlistentry>
-
+
+ <varlistentry>
+ <term>Poland</term>
+
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para>cvsup.pl.FreeBSD.ORG (maintainer <email>Mariusz@kam.pl</email>)</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
<varlistentry><term>Russia</term>
<listitem>
@@ -1163,6 +1202,14 @@
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>Sweden</term>
+
+ <listitem>
+ <para>cvsup.se.FreeBSD.ORG (maintainer <email>pantzer@ludd.luth.se</email>)</para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>Slovak Republic</term>
@@ -1338,6 +1385,45 @@
</sect1>
+
+ <sect1 id="mirrors-afs">
+ <title>AFS Sites</title>
+
+ <para>AFS servers for FreeBSD are running at the following sites;</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Sweden</term>
+
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para><hostid role="fqdn">stacken.kth.se</hostid>, Stacken
+ Computer Club, KTH, Sweden</para>
+ </listitem>
+
+ <listitem>
+ <para><hostid role="ipaddr">130.237.234.3</hostid>, <hostid
+ role="fqdn">milko.stacken.kth.se</hostid></para>
+ </listitem>
+
+ <listitem>
+ <para><hostid role="ipaddr">130.237.234.43</hostid>, <hostid
+ role="fqdn">hot.stacken.kth.se</hostid></para>
+ </listitem>
+
+ <listitem>
+ <para><hostid role="ipaddr">130.237.234.44</hostid>, <hostid role="fqdn">dog.stacken.kth.se</hostid></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Maintainer <email>ftp@stacken.kth.se</email></para>
+ </listitem>
+
+
+ </varlistentry>
+ </variablelist>
+ </sect1>
</chapter>
@@ -1347,9 +1433,7 @@
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/pgpkeys/chapter.sgml b/en/handbook/pgpkeys/chapter.sgml
index bb512fb1bc..cb1b9b9d1f 100644
--- a/en/handbook/pgpkeys/chapter.sgml
+++ b/en/handbook/pgpkeys/chapter.sgml
@@ -503,9 +503,7 @@ vvlVQ0UbcR0N2+5F6Mb5GqrXZpIesn7jFJpkQKPU
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/policies/chapter.sgml b/en/handbook/policies/chapter.sgml
index cd77ca0ba2..500b2b1d46 100644
--- a/en/handbook/policies/chapter.sgml
+++ b/en/handbook/policies/chapter.sgml
@@ -301,9 +301,7 @@ obrien@freebsd.org - 30 March 1997</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/ports/chapter.sgml b/en/handbook/ports/chapter.sgml
index aa5d962c4a..092d021ad9 100644
--- a/en/handbook/ports/chapter.sgml
+++ b/en/handbook/ports/chapter.sgml
@@ -88,7 +88,7 @@
<title>How Does the Ports Collection Work?</title>
<para>Programs are typically distributed on the Internet as a
- <xref linkend="ports-tarball" remap="tarball"> consisting of a
+ <link linkend="ports-tarball">tarball</link> consisting of a
Makefile and the source code for the program and usually some
instructions (which are unfortunately not always as instructive as
they could be), with perhaps a configuration script.</para>
@@ -100,18 +100,18 @@
from the source.</para>
<para>FreeBSD ports still use the tarball mechanism, but use a
- <xref linkend="ports-skeleton" remap="skeleton"> to hold the
+ <link linkend="ports-skeleton">skeleton</link> to hold the
"knowledge" of how to get the program working on FreeBSD,
rather than expecting the user to be able to work it out. They also
supply their own customised
- <xref linkend="ports-makefile" remap="Makefile">, so that almost
+ <link linkend="ports-makefile">Makefile</link>, so that almost
every port can be built in the same way.</para>
<para>If you look at a port skeleton (either on <ulink
URL="file://localhost/usr/ports/devel/ElectricFence">your FreeBSD
system</ulink> or <ulink
- URL="ftp://ftp.freebsd.org/pub/FreeBSD/ports/devel/ElectricFence">the FTP site</ulink>) and expect to find all sorts of pointy-headed rocket science lurking there, you may be disappointed by the one or two rather unexciting-looking files and directories you find there. (We will discuss in a minute how to go about <xref
- linkend="ports-getting" remap="Getting a port">).</para>
+ URL="ftp://ftp.freebsd.org/pub/FreeBSD/ports/devel/ElectricFence">the FTP site</ulink>) and expect to find all sorts of pointy-headed rocket science lurking there, you may be disappointed by the one or two rather unexciting-looking files and directories you find there. (We will discuss in a minute how to go about <link
+ linkend="ports-getting">Getting a port</link>).</para>
<para>“How on earth can this do anything?” I hear you cry. “There
is no source code there!”</para>
@@ -171,13 +171,12 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<procedure>
<step>
- <para>Locate the source code <xref linkend="ports-tarball"
- remap="tarball."> If it is not available locally, try to
+ <para>Locate the source code <link linkend="ports-tarball">tarball.</link> If it is not available locally, try to
grab it from an FTP site.</para>
</step>
<step>
- <para>Run a <xref linkend="ports-checksum" remap="checksum">
+ <para>Run a <link linkend="ports-checksum">checksum</link>
test on the tarball to make sure it has not been tampered
with, accidentally truncated, downloaded in ASCII mode, struck
by neutrinos while in transit, etc.</para>
@@ -188,7 +187,7 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
</step>
<step>
- <para>Apply any <xref linkend="ports-patch" remap="patches">
+ <para>Apply any <link linkend="ports-patch">patches</link>
needed to get the source to compile and run under FreeBSD.</para>
</step>
@@ -212,8 +211,8 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<step>
<para>Register the installation in a database. This means that,
- if you do not like the program, you can cleanly <xref
- linkend="ports-remove" remap="remove"> all traces of it from
+ if you do not like the program, you can cleanly <link
+ linkend="ports-remove">remove</link> all traces of it from
your system.</para>
</step>
@@ -230,85 +229,28 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<title>Getting a FreeBSD Port</title>
<para>There are two ways of getting hold of the FreeBSD port for a
- program. One requires a <xref linkend="ports-cd" remap="FreeBSD
- CDROM">, the other involves using an <xref linkend="ports-inet"
- remap="Internet Connection."></para>
+ program. One requires a <link linkend="ports-cd">FreeBSD
+ CDROM</link>, the other involves using an <link linkend="ports-inet">Internet Connection.</link></para>
<sect2 id="ports-cd">
<title>Compiling ports from CDROM</title>
-
- <para>If you answered yes to the question “Do you want to link the
- ports collection to your CDROM” during the FreeBSD installation,
- the initial setting up will already have been done for you.</para>
-
- <para>If not, make sure the <emphasis>FreeBSD</emphasis> CDROM is in
- the drive and mounted on, say, <filename>/cdrom</filename>. Then
- do</para>
-
- <informalexample>
- <screen>&prompt.root; <userinput>mkdir /usr/ports</userinput>
-&prompt.root; <userinput>cd /usr/ports</userinput>
-&prompt.root; <userinput>ln -s /cdrom/ports/distfiles distfiles</userinput></screen>
- </informalexample>
-
- <para>to enable the ports make mechanism to find the tarballs (it
- expects to find them in <filename>/usr/ports/distfiles</filename>,
- which is why we sym-linked the CDROM's tarball directory to that
- directory).</para>
-
- <para>Now, suppose you want to install the gnats program from the
- databases directory. Here is how to do it:-</para>
-
- <informalexample>
- <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
-&prompt.root; <userinput>mkdir databases</userinput>
-&prompt.root; <userinput>cp -R /cdrom/ports/databases/gnats databases</userinput>
-&prompt.root; <userinput>cd databases/gnats</userinput>
-&prompt.root; <userinput>make install</userinput></screen>
- </informalexample>
-
- <para>Or if you are a serious database user and you want to compare
- all the ones available in the Ports collection, do</para>
-
- <informalexample>
- <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
-&prompt.root; <userinput>cp -R /cdrom/ports/databases .</userinput>
-&prompt.root; <userinput>cd databases</userinput>
-&prompt.root; <userinput>make install</userinput></screen>
- </informalexample>
-
- <para>(yes, that really is a dot on its own after the <command>cp</command> command and
- not a mistake. It is Unix-ese for “the current
- directory”) and the ports make mechanism will automatically compile and
- install all the ports in the databases directory for you!</para>
-
- <para>If you do not like this method, here is a completely different
- way of doing it:-</para>
-
- <para>Create a “link tree” to it using the
- <citerefentry><refentrytitle>lndir</refentrytitle><manvolnum>1</manvolnum></citerefentry> command that comes with the
- <emphasis>XFree86</emphasis> distribution. Find a location with
- some free space, create a directory there and then cd to it. Then
- invoke the <citerefentry><refentrytitle>lndir</refentrytitle><manvolnum>1</manvolnum></citerefentry> command with the full
- pathname of the <filename>ports</filename> directory on the CDROM as the first
- argument and . (the current directory) as the second. This might
- be, for example, something like:</para>
- <informalexample>
- <screen>&prompt.root; <userinput>lndir /cdrom/ports .</userinput></screen>
- </informalexample>
-
- <para>Then you can build ports directly off the CDROM by building
- them in the link tree you have created.</para>
-
- <para>Note that there are some ports for which we cannot provide the
+ <para>Assuming that your FreeBSD CDROM is in the drive and mounted on
+ <filename>/cdrom</filename> (and the mount point
+ <emphasis>must</emphasis> be <filename>/cdrom</filename>), you should
+ then be able to build ports just as you normally do and the port
+ collection's built in search path should find the tarballs in
+ <filename>/cdrom/ports/distfiles/</filename> (if they exist there)
+ rather than downloading them over the net.</para>
+
+ <note>
+ <para>There are some ports for which we cannot provide the
original source in the CDROM due to licensing limitations. In
- that case, you will need to look at the section on <xref
- linkend="ports-inet"
- remap="Compiling ports using an Internet connection."></para>
-
- </sect2>
+ that case, you will need to look at the section on <link
+ linkend="ports-inet">Compiling ports using an Internet connection.</link></para>
+ </note>
+ </sect2>
<sect2 id="ports-inet">
<title>Compiling ports from the Internet</title>
@@ -316,13 +258,20 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<para>If you do not have a CDROM, or you want to make sure you get
the very latest version of the port you want, you will need to
download the
- <xref linkend="ports-skeleton" remap="skeleton"> for the port. Now
+ <link linkend="ports-skeleton">skeleton</link> for the port. Now
this might sound like rather a fiddly job full of pitfalls, but
it is actually very easy.</para>
-
- <para>The key to it is that the FreeBSD FTP server can create
+
+ <para>First, if you are running a release version of FreeBSD, make
+ sure you get the appropriate “upgradekiet” for your
+ replease from the <ulink url="http://www.freebsd.org/ports/">ports
+ web page</ulink>. These packages include files that have been
+ updated since the release that you may need to compile new
+ ports.</para>
+
+ <para>The key to the skeletons is that the FreeBSD FTP server can create
on-the-fly
- <xref linkend="ports-tarball" remap="tarballs"> for you. Here is
+ <link linkend="ports-tarball">tarballs</link> for you. Here is
how it works, with the gnats program in the databases directory as
an example (the bits in square brackets are comments. Do not type
them in if you are trying this yourself!):-</para>
@@ -347,14 +296,12 @@ password. Remember to use binary (also known as image) mode!]
<para>What happened here? We connected to the FTP server in the
usual way and went to its <filename>databases</filename> sub-directory. When we gave it
- the command <command>get gnats.tar</command>, the FTP server <xref
- linkend="ports-tarball"
- remap="tarred"> up the gnats directory for us.</para>
+ the command <command>get gnats.tar</command>, the FTP server <link
+ linkend="ports-tarball">tarred</link> up the gnats directory for us.</para>
<para>We then extracted the gnats skeleton and went into the gnats
- directory to build the port. As we explained <xref
- linkend="ports-fetch"
- remap="earlier">, the make process noticed we did not have a
+ directory to build the port. As we explained <link
+ linkend="ports-fetch">earlier</link>, the make process noticed we did not have a
copy of the source locally, so it fetched one before extracting,
patching and building it.</para>
@@ -436,16 +383,17 @@ do-install:
the benefit of human readers (as in most Unix script
files).</para>
- <para><literal>DISTNAME</literal> specifies the name of the <xref
- linkend="ports-tarball" remap="tarball">, but without the
+ <para><literal>DISTNAME</literal> specifies the name of the <link
+ linkend="ports-tarball">tarball</link>, but without the
extension.</para>
<para><literal>CATEGORIES</literal> states what kind of program this is. In
- this case, a utility for developers.</para>
+ this case, a utility for developers. See the <link
+ linkend="porting-categories">categories</link> section of this
+ handbook for a complete list.</para>
<para><literal>MASTER_SITES</literal> is the URL(s) of the master FTP site,
- which is used to retrieve the <xref linkend="ports-tarball"
- remap="tarball"> if it is not available on the local system.
+ which is used to retrieve the <link linkend="ports-tarball">tarball</link> if it is not available on the local system.
This is a site which is regarded as reputable, and is normally the
one from which the program is officially distributed (in so far
as any software is "officially" distributed on the
@@ -477,8 +425,7 @@ do-install:
<sect2>
<title>The <filename>files</filename> directory</title>
- <para>The file containing the <xref linkend="ports-checksum"
- remap="checksum"> for the port is called
+ <para>The file containing the <link linkend="ports-checksum">checksum</link> for the port is called
<filename>md5</filename>, after the MD5 algorithm used for ports
checksums. It lives in a directory with the slightly confusing
name of <filename>files</filename>.</para>
@@ -491,8 +438,7 @@ do-install:
<sect2>
<title>The <filename>patches</filename> directory</title>
- <para>This directory contains the <xref linkend="ports-patch"
- remap="patches"> needed to make everything work properly under
+ <para>This directory contains the <link linkend="ports-patch">patches</link> needed to make everything work properly under
FreeBSD.</para>
</sect2>
@@ -536,7 +482,7 @@ do-install:
<listitem>
<para>Fix it yourself. Technical details on how ports work can
be found in
- <xref linkend="porting" remap="Porting applications."></para>
+ <link linkend="porting">Porting applications.</link></para>
</listitem>
<listitem>
@@ -568,15 +514,6 @@ do-install:
</sect1>
- <sect1>
- <title>I Want to Make a Port!</title>
-
- <para>Great! Please see the <xref linkend="porting"
- remap="guidelines"> for detailed instructions on how to do
- this.</para>
-
- </sect1>
-
<sect1>
<title>Some Questions and Answers</title>
@@ -707,8 +644,7 @@ do-install:
</listitem>
<listitem>
- <para>Q. I did what you said for <xref linkend="ports-cd"
- remap="compiling ports from a CDROM"> and it worked great
+ <para>Q. I did what you said for <link linkend="ports-cd">compiling ports from a CDROM</link> and it worked great
until I tried to install the kermit port:-</para>
<informalexample>
@@ -884,7 +820,16 @@ do-install:
<para>Q. There are so many ports it is hard to find the one I
want. Is there a list anywhere of what ports are available?</para>
- <para>A. Look in the <filename>INDEX</filename> file in <filename>/usr/ports</filename>.</para>
+ <para>A. Look in the <filename>INDEX</filename> file in
+ <filename>/usr/ports</filename>. If you would like to search the
+ ports collection for a keyword, you can do that too. For example,
+ you can find ports relevant to the LISP programming language
+ using:</para>
+
+ <informalexample>
+ <screen>&prompt.user; <userinput>cd /usr/ports</userinput>
+&prompt.user; <userinput>make search key=lisp</userinput></screen>
+ </informalexample>
</listitem>
<listitem>
@@ -1044,6 +989,3524 @@ grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arc
</sect1>
+
+ <sect1 id="porting">
+ <title>Making a port yourself</title>
+
+ <para><emphasis>Contributed by &a.jkh;, &a.gpalmer;, &a.asami;
+ &a.obrien; and &a.hoek;. 28 August 1996.</emphasis></para>
+
+ <para>So, now you are interested in making your own port?
+ Great!</para>
+
+ <para>What follows are some guidelines for creating a new port for
+ FreeBSD. The bulk of the work is done by
+ <filename>/usr/share/mk/bsd.port.mk</filename>, which all port
+ Makefiles include. Please refer to that file for more details on
+ the inner workings of the ports collection. Even if you don't
+ hack Makefiles daily, it is well commented, and you will still
+ gain much knowledge from it.</para>
+
+ <note>
+ <para>Only a fraction of the overridable variables
+ (<makevar><replaceable>VAR</replaceable></makevar>) are mentioned
+ in this document. Most (if not all) are documented at the start of
+ <filename>bsd.port.mk</filename>. This file users a non-standard
+ tab setting. <application>Emacs</application> and
+ <application>Vim</application> should recognise the setting on
+ loading the file. <command>vi</command> or <command>ex</command>
+ can be set to use the correct value by typing <command>:set
+ tabstop=4</command> once the file has been loaded.</para>
+ </note>
+
+ <sect2>
+ <title>Quick Porting</title>
+
+ <para>This section tells you how to do a quick port. In many
+ cases, it is not enough, but we will see.</para>
+
+ <para>First, get the original tarball and put it into <makevar>DISTDIR</makevar>, which defaults to
+ <filename>/usr/ports/distfiles</filename>.</para>
+
+ <note>
+ <para>The following assumes that the software compiled
+ out-of-the-box, i.e., there was absolutely no change required
+ for the port to work on your FreeBSD box. If you needed to
+ change something, you will have to refer to the next section
+ too.</para>
+ </note>
+
+ <sect3>
+ <title>Writing the <filename>Makefile</filename></title>
+
+ <para>The minimal <filename>Makefile</filename> would
+ look something like this:</para>
+
+ <programlisting>
+# New ports collection makefile for: oneko
+# Version required: 1.1b
+# Date created: 5 December 1994
+# Whom: asami
+#
+# $Id$
+#
+
+DISTNAME= oneko-1.1b
+CATEGORIES= games
+MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
+
+MAINTAINER= asami@FreeBSD.ORG
+
+MAN1= oneko.1
+MANCOMPRESSED= yes
+USE_IMAKE= yes
+
+.include <bsd.port.mk></programlisting>
+
+ <para>See if you can figure it out. Do not worry about the
+ contents of the <literal>$Id$</literal>
+ line, it will be filled in automatically by CVS when the port
+ is imported to our main ports tree. You can find a more
+ detailed example in the <link
+ linkend="porting-samplem">sample Makefile</link>
+ section.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Writing the description files</title>
+
+ <para>There are three description files that are
+ required for any port, whether they actually package or not.
+ They are <filename>COMMENT</filename>,
+ <filename>DESCR</filename>, and <filename>PLIST</filename>,
+ and reside in the <filename>pkg</filename>
+ subdirectory.</para>
+
+
+ <sect4>
+ <title><filename>COMMENT</filename></title>
+
+ <para>This is the one-line description of the port.
+ <emphasis>Please</emphasis> do not include the package name (or version
+ number of the software) in the comment. Here is
+ an example:</para>
+
+ <programlisting>
+A cat chasing a mouse all over the screen.</programlisting>
+
+ </sect4>
+
+ <sect4>
+ <title><filename>DESCR</filename></title>
+
+ <para>This is a longer description of the port. One to a few
+ paragraphs concisely explaining what the port does is
+ sufficient.</para>
+
+ <note>
+ <para>This is <emphasis>not</emphasis> a manual or an
+ in-depth description on how to use or compile the port!
+ <emphasis>Please be careful if you are copying from the
+ <filename>README</filename> or manpage</emphasis>; too often
+ they are not a concise description of the port or are in an
+ awkward format (e.g., manpages have justified spacing). If the
+ ported software has an official WWW homepage, you should list
+ it here.</para>
+ </note>
+
+ <para>It is recommended that you sign the name at the end of
+ this file, as in:</para>
+
+ <programlisting>
+This is a port of oneko, in which a cat chases a poor mouse all over
+the screen.
+ :
+(etc.)
+
+http://www.oneko.org/
+
+- Satoshi
+asami@cs.berkeley.edu</programlisting>
+
+ </sect4>
+
+ <sect4>
+ <title><filename>PLIST</filename></title>
+
+ <para>This file lists all the files installed by the port. It
+ is also called the “packing list” because the package is
+ generated by packing the files listed here. The pathnames
+ are relative to the installation prefix (usually
+ <filename>/usr/local</filename> or
+ <filename>/usr/X11R6</filename>). If you are using the
+ <makevar>MAN<replaceable>n</replaceable></makevar> variables (as
+ you should be), do not list any manpages here.</para>
+
+ <para>Here is a small example:</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>Refer to the <citerefentry><refentrytitle>pkg_create</refentrytitle><manvolnum>1</manvolnum></citerefentry> man page
+ for details on the packing list.</para>
+
+ <note>
+ <para>You should list all the files, but not the name
+ directories, in the list. Also, if the port creates
+ directories for itself during installtion, make sure to add
+ <literal>@dirrm</literal> lines as necessary to remove them
+ when the port is deleted.</para>
+
+ <para>It is recommended that you keep all the filenames in
+ this file sorted alphabetically. It will make verifying the
+ changes when you upgrade the port much easier.</para>
+ </note>
+ </sect4>
+ </sect3>
+
+ <sect3>
+ <title>Creating the checksum file</title>
+
+ <para>Just type <command>make makesum</command>.
+ The ports make rules will automatically generate the file
+ <filename>files/md5</filename>.</para>
+
+ </sect3>
+
+ <sect3 id="porting-testing">
+ <title>Testing the port</title>
+
+ <para>You should make sure that the port rules do exactly what
+ you want it to do, including packaging up the port. These are
+ the important points you need to verify.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename>PLIST</filename> does not contain anything not
+ installed by your port</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>PLIST</filename> contains everything that is
+ installed by your port</para>
+ </listitem>
+
+ <listitem>
+ <para>Your port can be installed multiple times using the
+ <maketarget>reinstall</maketarget> target</para>
+ </listitem>
+
+ <listitem>
+ <para>Your port <link linkend="porting-cleaning">cleans
+ up</link> after itself upon deinstall</para>
+ </listitem>
+ </itemizedlist>
+
+ <procedure>
+ <title>Recommended test ordering</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 `make package-name`</command></para>
+ </step>
+
+ <step>
+ <para><command>make deinstall</command></para>
+ </step>
+
+ <step>
+ <para><command>make reinstall</command></para>
+ </step>
+
+ <step>
+ <para><command>make package</command></para>
+ </step>
+ </procedure>
+
+ <para>Make sure that there aren't any warnings issued in any of
+ the <maketarget>package</maketarget> and
+ <maketarget>deinstall</maketarget> stages, After step 3, check
+ to see if all the new directories are correctly deleted. Also,
+ try using the software after step 4, to ensure that is works
+ correctly when installed from a package.</para>
+ </sect3>
+
+ <sect3 id="porting-portlint">
+ <title>Checking your port with <command>portlint</command></title>
+
+ <para>Please use <command>portlint</command> to see if your port
+ conforms to our guidelines. The <command>portlint</command>
+ program is part of the ports collection. In particular, your may
+ want to check if the <link
+ linkend="porting-samplem">Makefile</link> is in the right
+ shape and the <link linkend="porting-pkgname">package</link> is
+ named appropriately.</para>
+ </sect3>
+
+ <sect3 id="porting-submitting">
+ <title>Submitting the port</title>
+
+ <para>First, make sure you have read the <link
+ linkend="porting-dads">Do's and Dont's</link> section.</para>
+
+ <para>Now that you are happy with your port, the only thing
+ remaining is to put it in the main FreeBSD ports tree and make
+ everybody else happy about it too. We do not need your
+ <filename>work</filename> directory or the
+ <filename>pkgname.tgz</filename> package, so delete them
+ now. Next, simply include the output of <command>shar `find
+ port_dir`</command> in a bug report and send it with the
+ <citerefentry>
+ <refentrytitle>send-pr</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry> program (see <link linkend="contrib-general">Bug
+ Reports and General Commentary</link> for more information
+ about <citerefentry>
+ <refentrytitle>send-pr</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>. If the uncompressed port is larger than
+ 20KB, you should compress it into a tarfile and use <citerefentry>
+ <refentrytitle>uuencode</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry> before including it in the bug report (uuencoded
+ tarfiles are acceptable even if the bug report is smaller than
+ 20KB but are not preferred). Be sure to classify the bug report as
+ category <literal>ports</literal> and class
+ <literal>change-request</literal>. (Do not mark the report
+ <literal>confidential</literal>!)</para>
+
+ <para>One more time, <emphasis>do not include the original source
+ distfile, the <filename>work</filename> directory, or the
+ package you built with <command>make
+ package</command></emphasis>.</para>
+
+ <note>
+ <para>In the past, we asked you to upload new port submissions
+ in our ftp site (<hostid
+ role="fqdn">ftp.freebsd.org</hostid>). This is no longer
+ recommended as read access is turned off on that
+ <filename>incoming/</filename> directory of that site due to
+ the large amount of pirated software showing up there.</para>
+ </note>
+
+ <para>We will look at your port,
+ get back to you if necessary, and put it in the
+ tree. Your name will also appear in the list of “Additional
+ FreeBSD contributors” on the FreeBSD Handbook and other files.
+ Isn't that great?!? <!-- smiley -->:)</para>
+
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Slow Porting</title>
+
+ <para>Ok, so it was not that simple, and the port required some
+ modifications to get it to work. In this section, we will
+ explain, step by step, how to modify it to get it to work with
+ the ports paradigm.</para>
+
+
+ <sect3>
+ <title>How things work</title>
+
+ <para>First, this is the sequence of events which occurs when
+ the user first types <command>make</command> in
+ your port's directory, and you may find that having
+ <filename>bsd.port.mk</filename> in another window while you
+ read this really helps to understand it.</para>
+
+ <para>But do not worry if you do not really understand what
+ <filename>bsd.port.mk</filename> is doing, not many people
+ do... <!-- smiley --><emphasis>:></emphasis></para>
+
+
+ <procedure>
+
+ <step>
+ <para>The <maketarget>fetch</maketarget> target is run. The <maketarget>fetch</maketarget> target is
+ responsible for making sure that the tarball exists
+ locally in <makevar>DISTDIR</makevar>.
+ If <maketarget>fetch</maketarget> cannot find the required files in <makevar>DISTDIR</makevar> it will look up the
+ URL <makevar>MASTER_SITES</makevar>,
+ which is set in the Makefile, as well as our main ftp
+ site at <ulink
+ URL="ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/">ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/,</ulink> where we put sanctioned distfiles as backup. It will then attempt to fetch the named distribution file with <makevar>FETCH</makevar>, assuming that the requesting site has direct access to the Internet. If that succeeds, it will save the file in <makevar>DISTDIR</makevar> for future use and proceed.</para>
+ </step>
+
+ <step>
+ <para>The <maketarget>extract</maketarget> target is run. It looks for your port's
+ distribution file (typically a gzip'd tarball) in <makevar>DISTDIR</makevar> and unpacks it into a temporary subdirectory
+ specified by <makevar>WRKDIR</makevar>
+ (defaults to <filename>work</filename>).</para>
+ </step>
+
+ <step>
+ <para>The <maketarget>patch</maketarget> target is run. First, any patches defined
+ in <makevar>PATCHFILES</makevar> are
+ applied. Second, if any patches are found in <makevar>PATCHDIR</makevar> (defaults to the
+ <filename>patches</filename> subdirectory), they are
+ applied at this time in alphabetical order.</para>
+ </step>
+
+ <step>
+ <para>The <maketarget>configure</maketarget> target is run. This can do any one of
+ many different things.</para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>If it exists,
+ <filename>scripts/configure</filename> is run.</para>
+ </listitem>
+
+ <listitem>
+ <para>If <makevar>HAS_CONFIGURE</makevar> or
+ <makevar>GNU_CONFIGURE</makevar>
+ is set,
+ <filename><makevar>WRKSRC</makevar>/configure</filename> is
+ run.</para>
+ </listitem>
+
+ <listitem>
+ <para>If <makevar>USE_IMAKE</makevar> is set,
+ <makevar>XMKMF</makevar>
+ (default: <command>xmkmf
+ -a</command>) is run.</para>
+ </listitem>
+
+ </orderedlist>
+
+ </step>
+
+ <step>
+ <para>The <maketarget>build</maketarget> target is run. This is responsible for
+ descending into the ports' private working directory
+ (<makevar>WRKSRC</makevar>) and
+ building it. If <makevar>USE_GMAKE</makevar> is set, GNU
+ <command>make</command> will be used,
+ otherwise the system <command>make</command>
+ will be used.</para>
+ </step>
+
+ </procedure>
+
+
+ <para>The above are the default actions. In addition, you can
+ define targets <maketarget>pre-<replaceable>something</replaceable></maketarget> or <maketarget>post-<replaceable>something</replaceable></maketarget>, or put scripts
+ with those names, in the <filename>scripts</filename>
+ subdirectory, and they will be run before or after the default
+ actions are done.</para>
+
+ <para>For example, if you have a <maketarget>post-extract</maketarget> target defined in your
+ Makefile, and a file <filename>pre-build</filename> in the
+ <filename>scripts</filename> subdirectory, the
+ <maketarget>post-extract</maketarget> target will be
+ called after the regular extraction actions, and the
+ <filename>pre-build</filename> script will be executed before
+ the default build rules are done. It is recommended that you
+ use <filename>Makefile</filename> targets if the actions are
+ simple enough, because it will be easier for someone to figure
+ out what kind of non-default action the port requires.</para>
+
+ <para>The default actions are done by the
+ <filename>bsd.port.mk</filename> targets <maketarget>do-<replaceable>something</replaceable></maketarget>. For example, the
+ commands to extract a port are in the target <maketarget>do-extract</maketarget>. If you are not happy with
+ the default target, you can fix it by redefining the
+ <maketarget>do-<replaceable>something</replaceable></maketarget> target in
+ your <filename>Makefile</filename>.</para>
+
+ <note>
+ <para>The “main” targets (e.g., <maketarget>extract</maketarget>, <maketarget>configure</maketarget>, etc.) do nothing more than
+ make sure all the stages up to that one is completed and
+ call the real targets or scripts, and they are not intended
+ to be changed. If you want to fix the extraction, fix
+ <maketarget>do-extract</maketarget>, but never ever
+ touch <maketarget>extract</maketarget>!</para>
+ </note>
+
+ <para>Now that you understand what goes on when the user types
+ <command>make</command>, let us go through the
+ recommended steps to create the perfect port.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Getting the original sources</title>
+
+ <para>Get the original sources (normally) as a compressed
+ tarball (<filename><replaceable>foo</replaceable>.tar.gz</filename> or
+ <filename><replaceable>foo</replaceable>.tar.Z</filename>) and copy it into
+ <makevar>DISTDIR</makevar>. Always use
+ <emphasis>mainstream</emphasis> sources when and where you
+ can.</para>
+
+ <para>If you cannot find a ftp/http site that is well-connected
+ to the net, or can only find sites that have irritatingly
+ non-standard formats, you might want to put a copy on a
+ reliable ftp or http server that you control (e.g., your home
+ page). Make sure you set <makevar>MASTER_SITES</makevar> to
+ reflect your choice.</para>
+
+ <para>If you
+ cannot find somewhere convenient and reliable to put the distfile
+ (if you are a FreeBSD committer, you can just put it in your
+ <filename>public_html/</filename> directory on
+ <hostid>freefall</hostid>),
+ we can “house” it ourselves by putting
+ it on <filename>ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/LOCAL_PORTS/</filename> as the last resort. Please refer to this
+ location as <makevar>MASTER_SITE_LOCAL</makevar>. Send mail to
+ the &a.ports;if you are not sure what to do.</para>
+
+ <para>If your port's distfile changes all the time for no good
+ reason, consider putting the distfile in your home page and
+ listing it as the first <makevar>MASTER_SITES</makevar>. This
+ will prevent users from getting <errorname>checksum
+ mismatch</errorname> errors, and also reduce the workload of
+ maintainers of our ftp site. Also, if there isonly one master
+ site for the port, it is recommended that you house a backup at
+ your site and list it as the second
+ <makevar>MASTER_SITES</makevar>.</para>
+
+ <para>If your port requires some additional `patches' that are
+ available on the Internet, fetch them too and put them in
+ <makevar>DISTDIR</makevar>. Do not worry if
+ they come from site other than where you got the main source
+ tarball, we have a way to handle these situations (see the
+ description of <link
+ linkend="porting-patchfiles">PATCHFILES</link> below).</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Modifying the port</title>
+
+ <para>Unpack a copy of the tarball in a private directory and
+ make whatever changes are necessary to get the port to compile
+ properly under the current version of FreeBSD. Keep
+ <emphasis>careful track</emphasis> of everything you do, as
+ you will be automating the process shortly. Everything,
+ including the deletion, addition or modification of files
+ should be doable using an automated script or patch file when
+ your port is finished.</para>
+
+ <para>If your port requires significant user
+ interaction/customization to compile or install, you should
+ take a look at one of Larry Wall's classic <application>Configure</application> scripts
+ and perhaps do something similar yourself. The goal of the
+ new ports collection is to make each port as “plug-and-play”
+ as possible for the end-user while using a minimum of disk
+ space.</para>
+
+ <note>
+ <para>Unless explicitly stated, patch files, scripts, and
+ other files you have created and contributed to the FreeBSD
+ ports collection are assumed to be covered by the standard
+ BSD copyright conditions.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>Patching</title>
+
+ <para>In the preparation of the port, files that have been added
+ or changed can be picked up with a recursive diff for later
+ feeding to patch. Each set of patches you wish to apply
+ should be collected into a file named
+ <filename>patch-<replaceable>xx</replaceable></filename> where
+ <replaceable>xx</replaceable> denotes the sequence in which
+ the patches will be applied — these are done in
+ <emphasis>alphabetical order</emphasis>, thus
+ <literal>aa</literal> first, <literal>ab</literal> second and so on. These files
+ should be stored in <makevar>PATCHDIR</makevar>, from where they will be
+ automatically applied. All patches should be relative to
+ <makevar>WRKSRC</makevar> (generally the
+ directory your port's tarball unpacks itself into, that being
+ where the build is done). To make fixes and upgrades easier,
+ you should avoid having more than one patch fix the same file
+ (e.g., <filename>patch-aa</filename> and <filename>patch-ab</filename> both changing <filename><makevar>WRKSRC</makevar>/foobar.c</filename>).</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Configuring</title>
+
+ <para>Include any additional customization commands to your
+ <filename>configure</filename> script and save it in the
+ <filename>scripts</filename> subdirectory. As mentioned
+ above, you can also do this as <filename>Makefile</filename>
+ targets and/or scripts with the name
+ <filename>pre-configure</filename> or
+ <filename>post-configure</filename>.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Handling user input</title>
+
+ <para>If your port requires user input to build, configure or
+ install, then set <makevar>IS_INTERACTIVE</makevar> in your
+ Makefile. This will allow “overnight builds” to skip your port
+ if the user sets the variable <envar>BATCH</envar> in his
+ environment (and if the user sets the variable
+ <envar>INTERACTIVE</envar>, then <emphasis>only</emphasis>
+ those ports requiring interaction are built).</para>
+
+ <para>It is also recommended that if there are reasonable default
+ answers to the questions, you check the
+ <makevar>PACKAGE_BUILDING</makevar> variable and turn off the
+ interactive script when it is set. This will allow us to build
+ the packages for CD-ROMs and ftp.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Configuring the Makefile</title>
+
+ <para>Configuring the Makefile is pretty simple, and again we
+ suggest that you look at existing examples before starting.
+ Also, there is a <link linkend="porting-samplem">sample
+ Makefile</link> in this handbook, so take a look and please follow
+ the ordering of variables and sections in that template to make
+ your port easier for others to read.</para>
+
+ <para>Now, consider the following problems in sequence as you
+ design your new Makefile:</para>
+
+
+ <sect3>
+ <title>The original source</title>
+
+ <para>Does it live in <makevar>DISTDIR</makevar> as a standard gzip'd
+ tarball? If so, you can go on to the next step. If not, you
+ should look at overriding any of the <makevar>EXTRACT_CMD</makevar>, <makevar>EXTRACT_BEFORE_ARGS</makevar>, <makevar>EXTRACT_AFTER_ARGS</makevar>, <makevar>EXTRACT_SUFX</makevar>, or <makevar>DISTFILES</makevar> variables, depending on
+ how alien a format your port's distribution file is. (The
+ most common case is <literal>EXTRACT_SUFX=.tar.Z</literal>,
+ when the tarball is condensed by regular compress, not
+ gzip.)</para>
+
+ <para>In the worst case, you can simply create your own
+ <maketarget>do-extract</maketarget> target to override
+ the default, though this should be rarely, if ever,
+ necessary.</para>
+
+ </sect3>
+
+ <sect3>
+ <title><makevar>DISTNAME</makevar></title>
+
+ <para>You should set <makevar>DISTNAME</makevar> to be the base name of
+ your port. The default rules expect the distribution file
+ list (<makevar>DISTFILES</makevar>) to be
+ named <makevar>DISTNAME</makevar><makevar>EXTRACT_SUFX</makevar> which, if it is a normal tarball, is going to be
+ something like <literal>foozolix-1.0.tar.gz</literal> for a setting of <literal>DISTNAME=foozolix-1.0</literal>.</para>
+
+ <para>The default rules also expect the tarball(s) to extract
+ into a subdirectory called
+ <filename>work/<makevar>DISTNAME</makevar></filename>, e.g. <filename>work/foozolix-1.0/</filename>.</para>
+
+ <para>All this behavior can be overridden, of course; it simply
+ represents the most common time-saving defaults. For a port
+ requiring multiple distribution files, simply set <makevar>DISTFILES</makevar> explicitly. If only a
+ subset of <makevar>DISTFILES</makevar> are
+ actual extractable archives, then set them up in <makevar>EXTRACT_ONLY</makevar>, which will override
+ the <makevar>DISTFILES</makevar> list when
+ it comes to extraction, and the rest will be just left in
+ <makevar>DISTDIR</makevar> for later
+ use.</para>
+
+ </sect3>
+
+ <sect3>
+ <title><makevar>PKGNAME</makevar></title>
+
+ <para>If <makevar>DISTNAME</makevar> does not conform to our <link
+ linkend="porting-pkgname">guidelines for a good package
+ name</link>, you should set the <makevar>PKGNAME</makevar>
+ variable to something better. See the abovementioned guidelines
+ for more details.</para>
+ </sect3>
+
+ <sect3>
+ <title><makevar>CATEGORIES</makevar></title>
+
+ <para>When a package is created, it is put under
+ <filename>/usr/ports/packages/All</filename> and links are
+ made from one or more subdirectories of
+ <filename>/usr/ports/packages</filename>. The names of these
+ subdirectories are specified by the variable <makevar>CATEGORIES</makevar>. It is intended to
+ make life easier for the user when he is wading through the
+ pile of packages on the ftp site or the CD-ROM. Please take a
+ look at the existing <link
+ linkend="porting-categories">categories</link> and pick the
+ ones that are suitable for your port.</para>
+
+ <para>This list also determines where in the ports tree the port
+ is imported. If you put more than one category here, it is
+ assumed that the port files will be put in the subdirectory with
+ the name in the first category. See the <link
+ linkend="porting-categories">categories</link> section for
+ more discussion about how to pick the right categories.</para>
+
+ <para>If you port truly belongs to something that is different
+ from all the existing ones, you can even create a new category
+ name. In that case, please send mail to the &a.ports; to propose
+ a new category.</para>
+
+ <note>
+ <para>There is no error checking for category
+ names. <command>make package</command> will happily create a
+ new directory if you mustype the category name, so be
+ careful!</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><makevar>MASTER_SITES</makevar></title>
+
+ <para>Record the directory part of the ftp/http-URL pointing at
+ the original tarball in <makevar>MASTER_SITES</makevar>. Do not forget the
+ trailing slash (<filename>/</filename>)!</para>
+
+ <para>The <command>make</command> macros will try to use this specification for
+ grabbing the distribution file with <makevar>FETCH</makevar> if they cannot find it
+ already on the system.</para>
+
+ <para>It is recommended that you put multiple sites on this
+ list, preferably from different continents. This will
+ safeguard against wide-area network problems, and we are even
+ planning to add support for automatically determining the
+ closest master site and fetching from there!</para>
+
+ <para>If the original tarball is part of one of the following
+ popular archives: X-contrib, GNU, Perl CPAN, TeX CTAN, or
+ Linux Sunsite, you refer to those sites in an easy compact
+ form using <makevar>MASTER_SITE_XCONTRIB</makevar>, <makevar>MASTER_SITE_GNU</makevar>,
+ <makevar>MASTER_SITE_PERL_CPAN</makevar>, <makevar>MASTER_SITE_TEX_CTAN</makevar>, and
+ <makevar>MASTER_SITE_SUNSITE</makevar>. Simply set <makevar>MASTER_SITE_SUBDIR</makevar> to the
+ path with in the archive. Here is an example:</para>
+
+ <programlisting>
+MASTER_SITES= ${MASTER_SITE_XCONTRIB}
+MASTER_SITE_SUBDIR= applications</programlisting>
+
+ <para>The user can also set the <makevar>MASTER_SITE_*</makevar> variables in
+ <filename>/etc/make.conf</filename> to override our choices,
+ and use their favorite mirrors of these popular archives
+ instead.</para>
+
+ </sect3>
+
+ <sect3 id="porting-patchfiles">
+ <title><makevar>PATCHFILES</makevar></title>
+
+ <para>If your port requires some additional patches that are
+ available by ftp or http, set <makevar>PATCHFILES</makevar> to the names of the
+ files and <makevar>PATCH_SITES</makevar> to
+ the URL of the directory that contains them (the format is the
+ same as <makevar>MASTER_SITES</makevar>).</para>
+
+ <para>If the patch is not relative to the top of the source tree
+ (i.e., <makevar>WKRSRC</makevar>) because it
+ contains some extra pathnames, set <makevar>PATCH_DIST_STRIP</makevar> accordingly.
+ For instance, if all the pathnames in the patch has an extra
+ <literal>foozolix-1.0/</literal> in front of the
+ filenames, then set
+ <literal>PATCH_DIST_STRIP=-p1</literal>.</para>
+
+ <para>Do not worry if the patches are compressed, they will be
+ decompressed automatically if the filenames end with
+ <filename>.gz</filename> or
+ <filename>.Z</filename>.</para>
+
+ <para>If the patch is distributed with some other files, such as
+ documentation, in a gzip'd tarball, you can't just use
+ <makevar>PATCHFILES</makevar>. If that is
+ the case, add the name and the location of the patch tarball
+ to <makevar>DISTFILES</makevar> and
+ <makevar>MASTER_SITES</makevar>. Then, from
+ the <maketarget>pre-patch</maketarget> target, apply the
+ patch either by running the patch command from there, or
+ copying the patch file into the <makevar>PATCHDIR</makevar> directory and calling it
+ <filename>patch-<replaceable>xx</replaceable></filename>.</para>
+
+ <note>
+ <para>Note the tarball will have been extracted alongside the
+ regular source by then, so there is no need to explicitly
+ extract it if it is a regular gzip'd or compress'd tarball.
+ If you do the latter, take extra care not to overwrite
+ something that already exists in that directory. Also do
+ not forget to add a command to remove the copied patch in
+ the <maketarget>pre-clean</maketarget> target.</para>
+ </note>
+
+ </sect3>
+
+ <sect3>
+ <title><makevar>MAINTAINER</makevar></title>
+
+ <para>Set your mail-address here. Please. <!-- smiley --><emphasis>:)</emphasis></para>
+
+ <para>For detailed description of the responsibility of
+ maintainers, refer to <link
+ linkend="policies-maintainer">MAINTAINER
+ on Makefiles</link> section.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Dependencies</title>
+
+ <para>Many ports depend on other ports. There are five
+ variables that you can use to ensure that all the required
+ bits will be on the user's machine. There are also some
+ pre-supported dependency variables for common cases, plus a few
+ more to control the behaviour of dependencies.</para>
+
+
+ <sect4>
+ <title><makevar>LIB_DEPENDS</makevar></title>
+
+ <para>This variable specifies the shared libraries this port
+ depends on. It is a list of <replaceable>lib</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples where
+ <replaceable>lib</replaceable> is the name of the shared library,
+ and <replaceable>dir</replaceable> is the directory in which to
+ find it in case it is not available, and
+ <replaceable>target</replaceable> is the target to call in
+ that directory. For example,
+
+ <programlisting>
+LIB_DEPENDS= jpeg\\.9\\.:${PORTSDIR}/graphics/jpeg:install</programlisting>
+
+ will check for a shared jpeg library with
+ major version 9, and descend into the
+ <filename>graphics/jpeg</filename> subdirectory of your
+ ports tree to build and install it if it is not
+ found. The <replaceable>target</replaceable> part can be
+ omitted if it is equal to <makevar>DEPENDS_TARGET</makevar>
+ (which defaults to <literal>install</literal>).</para>
+
+ <note>
+ <para>The <replaceable>lib</replaceable> part is an argument
+ given to <command>ldconfig -r | grep -wF</command>. There
+ shall be no reqular expressions in this variable.</para>
+ </note>
+
+ <para>The dependency is checked twice, once from within the
+ <maketarget>extract</maketarget> target and then from within
+ the <maketarget>install</maketarget> target. Also, the name of the
+ dependency is put in to the package so that
+ <command>pkg_add</command> will automatically install it if it
+ is not on the user's system.</para>
+
+ </sect4>
+
+ <sect4>
+ <title><makevar>RUN_DEPENDS</makevar></title>
+
+ <para>This variable specifies executables or files this port
+ depends on during run-time. It is a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples where
+ <replaceable>path</replaceable> is the name of the executable or
+ file, and <replaceable>dir</replaceable> is the directory in which
+ to find it in case it is not available, and
+ <replaceable>target</replaceable> is the target to call in
+ that directory. If
+ <replaceable>path</replaceable> starts with a slash
+ (<literal>/</literal>), it is treated as a file and its
+ existence is tested with <command>test -e</command>;
+ otherwise, it is assumed to be an executable, and
+ <command>which -s</command> is used to determine if the
+ program exists in the user's search path.</para>
+
+ <para>For example,
+
+ <programlisting>
+RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \
+ wish8.0:${PORTSDIR}/x11-toolkits/tk80</programlisting>
+
+ will check if the file or directory
+ <filename>/usr/local/etc/innd</filename> exists, and build
+ and install it from the <filename>news/inn</filename>
+ subdirectory of the ports tree if it is not found. It will
+ also see if an executable called <command>wish8.0</command> is in your search path, and
+ descend into the <filename>x11-toolkits/tk80</filename> subdirectory of
+ your ports tree to build and install it if it is not
+ found.</para>
+
+ <note>
+ <para>In this case, <command>innd</command> is actually an
+ executable; if an executable is in a place that is not
+ expected to be in a normal user's search path, you should
+ use the full pathname.</para>
+ </note>
+
+ <para>The dependency is checked from within the <maketarget>install</maketarget> target. Also, the name of the
+ dependency is put in to the package so that
+ <command>pkg_add</command> will automatically install it if it
+ is not on the user's system. The
+ <replaceable>target</replaceable> part can be omitted if it is
+ the same <makevar>DEPENDS_TARGET</makevar>.</para>
+
+ </sect4>
+
+ <sect4>
+ <title><makevar>BUILD_DEPENDS</makevar></title>
+
+ <para>This variable specifies executables or files this port
+ requires to build. Like <makevar>RUN_DEPENDS</makevar>, it is
+ a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples.
+ For example,
+
+ <programlisting>
+BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>
+
+ will check for an executable called
+ <command>unzip</command>, and descend into the
+ <filename>archivers/unzip</filename> subdirectory of your
+ ports tree to build and install it if it is not
+ found.</para>
+
+ <note>
+ <para>“build” here means everything from extracting to
+ compilation. The dependency is checked from within the
+ <maketarget>extract</maketarget> target. The
+ <replaceable>target</replaceable> part can be omitted if it
+ is the same as <makevar>DEPENDS_TARGET</makevar></para>
+ </note>
+ </sect4>
+
+ <sect4>
+ <title><makevar>FETCH_DEPENDS</makevar></title>
+
+ <para>This variable specifies executables or files this port
+ requires to fetch. Like the previous two, it is a list of
+ <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples. For
+ example,
+
+ <programlisting>
+FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting>
+
+ will check for an executable called
+ <command>ncftp2</command>, and descend into the
+ <filename>net/ncftp2</filename> subdirectory of your ports
+ tree to build and install it if it is not found.</para>
+
+ <para>The dependency is checked from within the
+ <maketarget>fetch</maketarget> target. The
+ <replaceable>target</replaceable> part can be omitted if it is
+ the same as <makevar>DEPENDS_TARGET</makevar>.</para>
+
+ </sect4>
+
+ <sect4>
+ <title><makevar>DEPENDS</makevar></title>
+
+ <para>If there is a dependency that does not fall into either
+ of the above four categories, or your port requires to have
+ the source of the other port extracted in addition to having
+ them installed, then use this variable. This is a list of
+ <replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional>, as there is nothing to check, unlike the previous four. The <replaceable>target</replaceable> part can be omitted if it is the same as <makevar>DEPENDS_TARGET</makevar>.</para>
+ </sect4>
+
+ <sect4>
+ <title>Common dependency variables</title>
+
+ <para>Define <literal>USE_XLIB=yes</literal> if your port
+ requires the X Window System to be installed (it is implied by
+ <makevar>USE_IMAKE</makevar>). Define
+ <literal>USE_GMAKE=yes</literal> if your port requires GNU
+ <command>make</command> instead of BSD
+ <command>make</command>. Define
+ <literal>USE_AUTOCONF=yes</literal> if your port requires GNU
+ autoconf to be run. Define <literal>USE_QT=yes</literal> if
+ your port uses the latest qt toolkit. Use
+ <literal>USE_PERL5=yes</literal> if your port requires version
+ 5 of the perl language. (The last is especially important since
+ some versions of FreeBSD has perl5 as part of the base system
+ while others don't.)</para>
+ </sect4>
+
+ <sect4>
+ <title>Notes on dependencies</title>
+
+ <para>As mentioned above, the default target to call when a
+ dependency is required is
+ <maketarget>DEPENDS_TARGET</maketarget>. It defaults to
+ <literal>install</literal>. This is a user variable; is is
+ never defined in a port's <filename>Makefile</filename>. If
+ your port needs a special way to handle a dependency, use the
+ <literal>:target</literal> part of the
+ <makevar>*_DEPENDS</makevar> variables instead of redefining
+ <makevar>DEPENDS_TARGET</makevar>.</para>
+
+ <para>When you type <command>make clean</command>, its
+ dependencies are automatically cleaned too. If you do not wish
+ this to happen, define the variable
+ <makevar>NOCLEANDEPENDS</makevar> in your environment.</para>
+
+ <para>To depend on another port unconditionally, it is customary
+ to use the string <literal>nonexistent</literal> as the first
+ field of <makevar>BUILD_DEPENDS</makevar> or
+ <makevar>RUN_DEPENDS</makevar>. Use this only when you need to
+ the to get to the source of the other port. You can often save
+ compilation time by specifying the target too. For
+ instance
+
+ <programlisting>
+BUILD_DEPENDS= /nonexistent:${PORTSDIR}/graphics/jpeg:extract</programlisting>
+
+ will always descend to the JPEG port and extract it.</para>
+
+ <para>Do not use <makevar>DEPENDS</makevar> unless there is no
+ other way the behaviour you want can be accomplished. It will
+ cause the other port to be always build (and installed, by
+ default), and the dependency will go into the packages as
+ well. If this is really what you need, I recommend you to
+ write it as <literal>BUILD_DEPENDS</literal> and
+ <literal>RUN_DEPENDS</literal> instead—at least the
+ intention will be clear.</para>
+ </sect4>
+ </sect3>
+
+ <sect3>
+ <title>Building mechanisms</title>
+
+ <para>If your package uses GNU <command>make</command>, set
+ <literal>USE_GMAKE=yes</literal>. If your package uses
+ <command>configure</command>, set
+ <literal>HAS_CONFIGURE=yes</literal>. If your package uses GNU
+ <command>configure</command>, set
+ <literal>GNU_CONFIGURE=yes</literal> (this implies
+ <literal>HAS_CONFIGURE</literal>). If you want to give some
+ extra arguments to <command>configure</command> (the default
+ argument list <literal>--prefix=${PREFIX}</literal> for
+ GNU <command>configure</command> and empty for non-GNU
+ <command>configure</command>), set those extra arguments in
+ <makevar>CONFIGURE_ARGS</makevar>. If your package uses GNU
+ <command>autoconf</command>, set
+ <literal>USE_AUTOCONF=yes</literal>. This implies
+ <makevar>GNU_CONFIGURE</makevar>, and will cause
+ <command>autoconf</command> to be run before
+ <command>configure</command>.</para>
+
+ <para>If your package is an X application that creates
+ <filename>Makefile</filename>s from
+ <filename>Imakefile</filename>s using <command>imake</command>, then set
+ <literal>USE_IMAKE=yes</literal>. This will cause the
+ configure stage to automatically do an <command>xmkmf
+ -a</command>. If the <option>-a</option> flag is a
+ problem for your port, set
+ <literal>XMKMF=xmkmf</literal>.
+ If the port uses <command>imake</command> but does not understand the
+ <maketarget>install.man</maketarget> target,
+ <literal>NO_INSTALL_MANPAGES=yes</literal> should be set.
+ In addition, the author of the original port should be shot.
+ <!-- smiley --><emphasis>:></emphasis></para>
+
+ <para>If your port's source <filename>Makefile</filename> has
+ something else than <maketarget>all</maketarget> as the main
+ build target, set <makevar>ALL_TARGET</makevar>
+ accordingly. Same goes for <maketarget>install</maketarget> and
+ <makevar>INSTALL_TARGET</makevar>.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Special considerations</title>
+
+ <para>There are some more things you have to take into account when
+ you create a port. This section explains the most common of
+ those.</para>
+
+ <sect3>
+ <title><command>ldconfig</command></title>
+
+ <para>If your port installs a shared library, add a
+ <maketarget>post-install</maketarget> target to your
+ <filename>Makefile</filename> that runs
+ <literal>${LDCONFIG} -m</literal> on the directory where
+ the new library is installed (usually
+ <filename><makevar>PREFIX</makevar>/lib</filename>) to register
+ it into the shared library cache.</para>
+
+ <para>Also, add a matching <literal>@exec /sbin/ldconfig
+ -m</literal> and <literal>@unexec /sbin/ldconfig -R</literal>
+ pair to your <filename>pkg/PLIST</filename> file so that a user
+ who installed the package can start using teh shared libraru
+ immediately and deinstallation will not cause the system to
+ still believe the library is there. These lines should
+ immediately follow the line for the shared library itself, as
+ in:</para>
+
+ <programlisting>
+lib/libtvl80.so.1
+@exec /sbin/ldconfig -m %D/lib
+@unexec /sbin/ldconfig -R</programlisting>
+
+ <para>Never, ever, <emphasis>ever</emphasis> add a line that says
+ <literal>ldconfig</literal> without any arguments to your
+ <filename>Makefile</filename> or
+ <filename>pkg/PLIST</filename>. This will reset the shared
+ libraru cache to the contents of <filename>/usr/lib</filename>
+ only, and will royally screw up the user's machine ("Help, xinit
+ does not run anymore after I install this port!"). Anybody who
+ does this will be shot and cut in 65,536 pieces by a rusty knife
+ and have is liver chopped out by a bunch of crows and will
+ eternally rot to death in the deepest bowels of hell (not
+ necessarily in that order…)</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>ELF support</title>
+
+ <para>Since FreeBSD is moving to ELF from 3.0-release onwards,
+ 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 that there will
+ be one more release (2.2.8) from the 2.2 branch. 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 awhile for reference
+ in case you have come across some old port you wish to
+ upgrade.</para>
+
+ <sect3>
+ <title>Moving a.out libraries out of the way</title>
+
+ <para>A.out libraries should be moved out of
+ <filename>/usr/local/lib</filename> and similar to an
+ <filename>aout</filename> subdirectory. (If you don't move them
+ out of the way, ELF ports will happily overwrite a.out libraries.)
+ The <maketarget>move-aout-libs</maketarget> target in the -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>
+ </sect3>
+
+ <sect3>
+ <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>
+ </sect3>
+
+ <sect3>
+ <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's always going to be
+ <literal>aout</literal> in -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>
+ </sect3>
+
+ <sect3>
+ <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 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>PLIST</filename> too, and it won't 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>
+ </sect3>
+
+ <sect3>
+ <title><makevar>LIB_DEPENDS</makevar></title>
+
+ <para>All port Makefiles 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>
+ </sect3>
+
+ <sect3>
+ <title><filename>PLIST</filename></title>
+
+ <para><filename>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>PLIST</filename> mentioned in the previous
+ paragraph.</para>
+ </sect3>
+
+ <sect3>
+ <title><literal>ldconfig</literal></title>
+
+ <para>The <literal>ldconfig</literal> line in Makefiles should read:</para>
+
+ <programlisting>
+${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....</programlisting>
+
+ <para>In <filename>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>
+ </sect3>
+ </sect2>
+
+ <sect2 id="porting-masterdir">
+ <title><makevar>MASTERDIR</makevar></title>
+
+ <para>If your port needs to build slightly different versions of
+ packages by having a variable (for instance, resolution, or paper
+ size) take different values, create one subdirectory per package
+ to make it easier forusers to see what to do, but try to share as
+ many files as possible between ports. Typically you only need a
+ very short <filename>Makefile</filename> in all but one of the
+ directories if you use variables cleverly. In the sole
+ <filename>Makefiles</filename>, you can use
+ <makevar>MASTERDIR</makevar> to specify the directory where the
+ rest of the files are. Also, use a variable as part of
+ <link linkend="porting-pkgname"><makevar>PKGNAME</makevar></link>
+ so the packages will have different names.</para>
+
+ <para>This will be best demonstrated by an example. This is part of
+ <filename>japanese/xdvi300/Makefile</filename>;</para>
+
+ <programlisting>
+PKGNAME= ja-xdvi${RESOLUTION}-17
+ :
+# 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>japanese/xdvi300</filename> also has all the regular
+ patches, package files, etc. If you type <command>make</command>
+ there, it will take the default value for the resolution (300) and
+ build the port normally.</para>
+
+ <para>As for other resolutions, this is the
+ <emphasis>entire</emphasis>
+ <filename>xdvi118/Makefile</filename>;</para>
+
+ <programlisting>
+RESOLUTION= 118
+MASTERDIR= ${.CURDIR}/../xdvi300
+
+.include ${MASTERDIR}/Makefile</programlisting>
+
+ <para>(<filename>xdvi240/Makefile</filename> and
+ <filename>xdvi400/Makefile</filename> are similar). The
+ <makevar>MASTERDIR</makevar> definition tells
+ <filename>bsd.port.mk</filename> that the refulat set of
+ subdirectories like <makevar>PATCHDIR</makevar> and
+ <makevar>PKGDIR</makevar> are to be found under
+ <filename>xdvi300</filename>. The
+ <literal>RESOLUTION=118</literal> line will override the
+ <literal>RESOLUTION=300</literal> line in
+ <filename>xdvi300/Makefile</filename> and the port will be built
+ with resolution set to 118.</para>
+ </sect2>
+
+ <sect2>
+ <title>Shared library versions</title>
+
+ <para>First, please read our <link linkend="policies-shlib">policy
+ on shared library versioning</link> to understand
+ what to do with shared library versions in general. Do
+ not blindly assume software authors know what they are
+ doing; many of them do not. It is very important that
+ these details are carefully considered, as we have quite a
+ unique situation where we are trying to have dozens of
+ potentially incompatible software pairs co-exist.
+ Careless port imports have caused great trouble regarding
+ shared libraries in the past (ever wondered why the port
+ <filename>jpeg-6b</filename> has a shared library version of 9.0?).
+ If in doubt, send a message to the &a.ports;. Most of the
+ time, your job ends by determining the right shared
+ library version and making appropriate patches to
+ implement it.</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>
+ </sect2>
+
+ <sect2 id="porting-manpages">
+ <title>Manpages</title>
+
+ <para>The <makevar>MAN[1-9LN]</makevar> variables will automatically
+ add any manpages to <filename>pkg/PLIST</filename> (this means you
+ must <emphasis>not</emphasis> list manpages in the
+ <filename>PLIST</filename>—see <link
+ linkend="porting-plist">generating PLIST</link> for more). It
+ also makes the install stage automatically compress or uncompress
+ manpages depending on the setting of
+ <makevar>NOMANCOMPRESS</makevar> in
+ <filename>/etc/make.conf</filename>.</para>
+
+ <para>To specify whether the manpages are compressed upon
+ installation, use the <makevar>MANCOMPRESSED</makevar> variable.
+ This variable can take three values, <literal>yes</literal>,
+ <literal>no</literal> and <literal>maybe</literal>.
+ <literal>yes</literal> means manpages are already installed
+ compressed, <literal>no</literal> means they are not, and
+ <literal>maybe</literal> means the software already respects the
+ value of <makevar>NOMANCOMPRESS</makevar> so
+ <filename>bsd.port.mk</filename> does not have to do anything
+ special.</para>
+
+ <para><makevar>MANCOMPRESSED</makevar> is automatically set to
+ <literal>yes</literal> if <makevar>USE_IMAKE</makevar> is set and
+ <makevar>NO_INSTALL_MANPAGES</makevar> is not set, and to
+ <literal>no</literal> otherwise. You don't have to explicitly
+ define it unless the default is not suitable for your port.</para>
+
+ <para>If your port anchors its man tree somewhere other than
+ <makevar>PREFIX</makevar>, you can use the
+ <makevar>MANPREFIX</makevar> to set it. Also, if only manpages in
+ certain sections go in a non-standard place, such as some Perl
+ modules ports, you can set individual man paths using
+ <makevar>MAN<replaceable>sect</replaceable>PREFIX</makevar> (where
+ <replaceable>sect</replaceable> is one of <literal>1-9</literal>,
+ <literal>L</literal> or <literal>N</literal>).</para>
+
+ <para>If your manpages go to language-specific subdirectories, set
+ the name of the languages to <makevar>MANLANG</makevar>. The
+ value of this variable defaults to <literal>""</literal> (i.e.,
+ English only).</para>
+
+ <para>Here is an example that puts it all together.</para>
+
+ <programlisting>
+MAN1= foo.1
+MAN3= bar.3
+MAN4= baz.4
+MANLANG= "" ja
+MAN3PREFIX= ${PREFIX}/share/foobar
+MANCOMPRESSED= yes</programlisting>
+
+ <para>This states that six files are installed by this 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>
+ </sect2>
+
+ <sect2>
+ <title>Ports that require Motif</title>
+
+ <para>There are many programs that require a Motif library
+ (available from several commercial vendors, while there is
+ a free clone reported to be able to run many applications in
+ <filename>x11-toolkits/lesstif</filename>) to compile. Since
+ it is a popular toolkit and their licenses usually permit
+ redistribution of statically linked binaries, we have made
+ special provisions for handling ports that require Motif in a
+ way that we can easily compile binaries linked either
+ dynamically (for people who are compiling from the port) or
+ statically (for people who distribute packages).</para>
+
+ <sect3>
+ <title><makevar>REQUIRES_MOTIF</makevar></title>
+
+ <para>If your port requires Motif, define this variable in the
+ Makefile. This will prevent people who don't own a copy of
+ Motif from even attempting to build it.</para>
+ </sect3>
+
+ <sect3>
+ <title><makevar>MOTIFLIB</makevar></title>
+
+ <para>This variable will be set by
+ <filename>bsd.port.mk</filename> to be the appropriate reference
+ to the Motif library. Please patch the source to use this
+ wherever the Motif library is referenced in the
+ <filename>Makefile</filename> or
+ <filename>Imakefile</filename>.</para>
+
+ <para>There are two common cases:</para>
+
+ <itemizedlist>
+ <listitem><para>If the port refers to the Motif library as
+ <literal>-lXm</literal> in its <filename>Makefile</filename>
+ or <filename>Imakefile</filename>, simply substitute
+ <literal>${MOTIFLIB}</literal> for
+ it.</para></listitem>
+
+ <listitem><para>If the port uses <literal>XmClientLibs</literal>
+ in its <filename>Imakefile</filename>, change it to
+ <literal>${MOTIFLIB} ${XTOOLLIB}
+ ${XLIB}</literal>.</para></listitem>
+ </itemizedlist>
+
+ <para>Note that <makevar>MOTIFLIB</makevar> (usually) expands to
+ <literal>-L/usr/X11R6/lib -lXm</literal> or
+ <literal>/usr/X11R6/lib/libXm.a</literal>, so there is no need
+ to add <literal>-L</literal> or <literal>-l</literal> in
+ front.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>X11 fonts</title>
+
+ <para>If your port installs fonts for the X Window system, put them
+ in
+ <filename><makevar>X11BASE</makevar>/lib/X11/fonts/local</filename>.
+ This directory is new to XFree86 release 3.3.3. If it does not
+ exist, please create it, and print out a message urging the user
+ to update their XFree86 to 3.3.3 or newer, or at least add this
+ directory to the font path in
+ <filename>/etc/XF86Config</filename>.</para>
+ </sect2>
+
+ <sect2>
+ <title>Info files</title>
+
+ <para>The new version of texinfo (included in 2.2.2-RELEASE and
+ onwards) contains a utility called <command>install-info</command>
+ to add and delete entries to the <filename>dir</filename> file. If
+ your port installs any info documents, please follow this
+ instructions so your port/package will correctly update the user's
+ <filename><makevar>PREFIX</makevar>/info/dir</filename>
+ file. (Sorry for the length of this section, but is it imperative
+ to weave all the info files together. If done correctly, it will
+ produce a <emphasis>beautiful</emphasis> listing, so please bear
+ with me!</para>
+
+ <para>First, this is what you (as a porter) need to know</para>
+
+ <informalexample>
+ <screen>&prompt.user; <userinput>install-info --help</userinput>
+install-info [OPTION]... [INFO-FILE [DIR-FILE]]
+ Install INFO-FILE in the Info directory file DIR-FILE.
+
+Options:
+--delete Delete existing entries in INFO-FILE;
+ don't insert any new entries.
+ :
+--entry=TEXT Insert TEXT as an Info directory entry.
+ :
+--section=SEC Put this file's entries in section SEC of the directory. :</screen>
+ </informalexample>
+
+ <note>
+ <para>This program will not actually
+ <emphasis>install</emphasis> info files; it merely inserts or
+ deletes entries in the <filename>dir</filename> file.</para>
+ </note>
+
+ <para>Here's a seven-step procedure to convert ports to use
+ <command>install-info</command>. I will use
+ <filename>editors/emacs</filename> as an example.</para>
+
+ <procedure>
+ <step>
+ <para>Look at the texinfo sources and make a patch to insert
+ <literal>@dircategory</literal> and <literal>@direntry</literal>
+ statements to files that don't have them. This is part of
+ my patch:</para>
+
+ <programlisting>
+--- ./man/vip.texi.org Fri Jun 16 15:31:11 1995
++++ ./man/vip.texi Tue May 20 01:28:33 1997
+@@ -2,6 +2,10 @@
+
+ @setfilename ../info/vip
+ @settitle VIP
++@dircategory The Emacs editor and associated tools
++@direntry
++* VIP: (vip). A VI-emulation for Emacs.
++@end direntry
+
+ @iftex
+ @finalout
+ :</programlisting>
+
+ <para>The format should be self-explanatory. Many authors
+ leave a <filename>dir</filename> file in the source tree
+ that contains all the entries you need, so look around
+ before you try to write your own. Also, make sure you
+ look into related ports and make the section names and
+ entry indentations consistent (we recommend that all entry
+ text start at the 4th tab stop).</para>
+
+ <note>
+ <para>Note that you can put only one info entry per file
+ because of a bug in <command>install-info
+ --delete</command> that deletes only the first entry
+ if you specify multiple entries in the
+ <email>@direntry</email> section.</para>
+ </note>
+
+ <para>You can give the <literal>dir</literal>
+ entries to <command>install-info</command> as
+ arguments (<option>--section</option> and
+ <option>--entry</option>) instead of patching the texinfo
+ sources. I do not think this is a good idea for ports
+ because you need to duplicate the same information in
+ <emphasis>three</emphasis> places
+ (<filename>Makefile</filename> and
+ <literal>@exec</literal>/<literal>@unexec</literal> of
+ <filename>PLIST</filename>; see below). However, if you
+ have a Japanese (or other multibyte encoding) info files,
+ you will have to use the extra arguments to <command>install-info</command> because <command>makeinfo</command> can't handle those texinfo
+ sources. (See <filename>Makefile</filename> and
+ <filename>PLIST</filename> of
+ <filename>japanese/skk</filename> for examples on how to
+ do this).</para>
+ </step>
+
+ <step>
+ <para>Go back to the port directory and do a <command>make clean; make</command> and verify that
+ the info files are regenerated from the texinfo sources.
+ Since the texinfo sources are newer than the info files,
+ they should be rebuilt when you type <command>make</command>; but many
+ <filename>Makefile</filename>s don't include correct
+ dependencies for info files. In <command>emacs</command>' case, I had to
+ patch the main <filename>Makefile.in</filename> so it will
+ descend into the <filename>man</filename>
+ subdirectory to rebuild the info pages.</para>
+
+ <programlisting>
+--- ./Makefile.in.org Mon Aug 19 21:12:19 1996
++++ ./Makefile.in Tue Apr 15 00:15:28 1997
+@@ -184,7 +184,7 @@
+ # Subdirectories to make recursively. `lisp' is not included
+ # because the compiled lisp files are part of the distribution
+ # and you cannot remake them without installing Emacs first.
+-SUBDIR = lib-src src
++SUBDIR = lib-src src man
+
+ # The makefiles of the directories in $SUBDIR.
+ SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile lwlib/Makefile
+--- ./man/Makefile.in.org Thu Jun 27 15:27:19 1996
++++ ./man/Makefile.in Tue Apr 15 00:29:52 1997
+@@ -66,6 +66,7 @@
+ ${srcdir}/gnu1.texi \
+ ${srcdir}/glossary.texi
+
++all: info
+ info: $(INFO_TARGETS)
+
+ dvi: $(DVI_TARGETS)</programlisting>
+
+ <para>The second hunk was necessary because the default
+ target in the <filename>man</filename> subdir is called
+ <maketarget>info</maketarget>, while the main
+ <filename>Makefile</filename> wants to call <maketarget>all</maketarget>. I also deleted the installation
+ of the <filename>info</filename> info file
+ because we already have one with the same name in
+ <filename>/usr/share/info</filename> (that patch is not
+ shown here).</para>
+ </step>
+
+ <step>
+ <para>If there is a place in the
+ <filename>Makefile</filename> that is installing the
+ <filename>dir</filename> file, delete it. Your
+ port may not be doing it. Also, remove any commands that
+ are otherwise mucking around with the
+ <filename>dir</filename> file.</para>
+
+ <programlisting>
+--- ./Makefile.in.org Mon Aug 19 21:12:19 1996
++++ ./Makefile.in Mon Apr 14 23:38:07 1997
+@@ -368,14 +368,8 @@
+ if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \
+ then \
+ (cd ${infodir}; \
+- if [ -f dir ]; then \
+- if [ ! -f dir.old ]; then mv -f dir dir.old; \
+- else mv -f dir dir.bak; fi; \
+- fi; \
+ cd ${srcdir}/info ; \
+- (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir); \
+- (cd $${thisdir}; chmod a+r ${infodir}/dir); \
+ for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \
+ (cd $${thisdir}; \
+ ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \
+ chmod a+r ${infodir}/$$f); \</programlisting>
+ </step>
+
+ <step>
+ <para>(This step is only necessary if you are modifying an
+ existing port.) Take a look at
+ <filename>pkg/PLIST</filename> and delete anything that is
+ trying to patch up <filename>info/dir</filename>. They
+ may be in <filename>pkg/INSTALL</filename> or some other
+ file, so search extensively.</para>
+
+ <programlisting>
+Index: pkg/PLIST
+===================================================================
+RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v
+retrieving revision 1.15
+diff -u -r1.15 PLIST
+--- PLIST 1997/03/04 08:04:00 1.15
++++ PLIST 1997/04/15 06:32:12
+@@ -15,9 +15,6 @@
+ man/man1/emacs.1.gz
+ man/man1/etags.1.gz
+ man/man1/ctags.1.gz
+-@unexec cp %D/info/dir %D/info/dir.bak
+-info/dir
+-@unexec cp %D/info/dir.bak %D/info/dir
+ info/cl
+ info/cl-1
+ info/cl-2</programlisting>
+ </step>
+
+ <step>
+ <para>Add a <maketarget>post-install</maketarget>
+ target to the <filename>Makefile</filename> to create a
+ <filename>dir</filename> file if it is not there. Also,
+ call <maketarget>install-info</maketarget> with the
+ installed info files.</para>
+
+ <programlisting>
+Index: Makefile
+===================================================================
+RCS file: /usr/cvs/ports/editors/emacs/Makefile,v
+retrieving revision 1.26
+diff -u -r1.26 Makefile
+--- Makefile 1996/11/19 13:14:40 1.26
++++ Makefile 1997/05/20 10:25:09 1.28
+@@ -20,5 +20,11 @@
+ post-install:
+ .for file in emacs-19.34 emacsclient etags ctags b2m
+ strip ${PREFIX}/bin/${file}
+ .endfor
++ if [ ! -f ${PREFIX}/info/dir ]; then \
++ ${SED} -ne '1,/Menu:/p' /usr/share/info/dir > ${PREFIX}/info/dir; \
++ fi
++.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode
++ install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir
++.endfor
+
+ .include <bsd.port.mk></programlisting>
+
+ <para>Do not use anything other than
+ <filename>/usr/share/info/dir</filename> and the above
+ command to create a new info file. In fact, I'd add the
+ first three lines of the above patch to
+ <filename>bsd.port.mk</filename> if you (the porter)
+ wouldn't have to do it in <filename>PLIST</filename> by
+ yourself anyway.</para>
+ </step>
+
+ <step>
+ <para>Edit <filename>PLIST</filename> and add equivalent
+ <literal>@exec</literal> statements and also
+ <literal>@unexec</literal> for <command>pkg_delete</command>.
+ You do not need to delete <filename>info/dir</filename>
+ with <literal>@unexec</literal>.</para>
+
+ <programlisting>
+Index: pkg/PLIST
+===================================================================
+RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v
+retrieving revision 1.15
+diff -u -r1.15 PLIST
+--- PLIST 1997/03/04 08:04:00 1.15
++++ PLIST 1997/05/20 10:25:12 1.17
+@@ -16,7 +14,15 @@
+ man/man1/etags.1.gz
+ man/man1/ctags.1.gz
++@unexec install-info --delete %D/info/emacs %D/info/dir
+ :
++@unexec install-info --delete %D/info/ccmode %D/info/dir
+ info/cl
+ info/cl-1
+@@ -87,6 +94,18 @@
+ info/viper-3
+ info/viper-4
++@exec [ -f %D/info/dir ] || sed -ne '1,/Menu:/p' /usr/share/info/dir > %D/info/dir
++@exec install-info %D/info/emacs %D/info/dir
+ :
++@exec install-info %D/info/ccmode %D/info/dir
+ libexec/emacs/19.34/i386--freebsd/cvtmail
+ libexec/emacs/19.34/i386--freebsd/digest-doc</programlisting>
+
+ <note>
+ <para>The <literal>@unexec install-info
+ --delete</literal> commands have to be listed before
+ the info files themselves so they can read the files.
+ Also, the <literal>@exec install-info</literal> commands
+ have to be after the info files and the
+ <literal>@exec</literal> command that creates the the
+ <filename>dir</filename> file.</para>
+ </note>
+ </step>
+
+ <step>
+ <para><link linkend="porting-testing">Test</link> and admire your work. <!-- smiley --><emphasis>:)</emphasis>. Check the <filename>dir</filename> file before and after each
+ step.</para>
+ </step>
+ </procedure>
+
+ </sect2>
+
+ <sect2>
+ <title>The <filename>pkg/</filename> subdirectory</title>
+
+ <para>There are some tricks we haven't mentioned yet about the
+ <filename>pkg/</filename> subdirectory that come in handy
+ sometimes.</para>
+
+ <sect3 id="porting-message">
+ <title><filename>MESSAGE</filename></title>
+
+ <para>If you need to display a message to the installer, you may
+ place the message in <filename>pkg/MESSAGE</filename>. This
+ capability is often useful to display additional installation
+ steps to be taken after a <command>pkg_add</command> or to display
+ licensing information.</para>
+
+ <note>
+ <para>The <filename>pkg/MESSAGE</filename> file does not need to
+ be added to <filename>pkg/PLIST</filename>. Also, it will not get
+ automatically printed if the user is using the port, not the
+ package, so you should probably display it from the
+ <maketarget>post-install</maketarget> target yourself.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><filename>INSTALL</filename></title>
+
+ <para>If your port needs execute commands when the binary package is
+ installed with <command>pkg_add</command> you can do with via the
+ <filename>pkg/INSTALL</filename> script. This script will
+ automatically be added to the package, and will be run twice by
+ <command>pkg_add</command>. The first time will as
+ <literal>INSTALL ${PKGNAME} PRE-INSTALL</literal> and the
+ second time as <literal>INSTALL ${PKGNAME}
+ POST-INSTALL</literal>. <literal>$2</literal> can be
+ tested to determine which mode the script is being run in. The
+ <envar>PKG_PREFIX</envar> environmental variable will be set to
+ the package installation directory. See <citerefentry>
+ <refentrytitle>pkg_add</refentrytitle>
+ <manvolnum>1</manvolnum></citerefentry> for additional
+ information.</para>
+
+ <note>
+ <para>This script is not run automatically if you install the port
+ with <command>make install</command>. If you are depending on
+ it being run, you will have to explicitly call it on your port's
+ <filename>Makefile</filename>.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><filename>REQ</filename></title>
+
+ <para>If your port needs to determine if it should install or not,
+ you can create a <filename>pkg/REQ</filename>
+ “requirements” script. It will be invoked
+ automatically at installation/deinstallation time to determine
+ whether or not installation/deinstallation should proceed.</para>
+ </sect3>
+
+ <sect3 id="porting-plist">
+ <title>Changing <filename>PLIST</filename> based on make variables</title>
+
+ <para>Some ports, particularly the p5- ports, need to change their
+ <filename>PLIST</filename> depending on what options they are
+ configured with (or version of perl, in the case of p5- ports). To
+ make this easy, any instances in the <filename>PLIST</filename> of
+ <literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal>, and
+ <literal>%%PERL_VERSION%%</literal> will be substituted for
+ appropriately. The value of <literal>%%OSREL%%</literal> is the
+ numeric revision of the operating system (e.g.,
+ <literal>2.2.7</literal>). <literal>%%PERL_VERSION%%</literal> is
+ the full version number of perl (e.g., <literal>5.00502</literal>)
+ and <literal>%%PERL_VER%%</literal> is the perl version number
+ minus the patchlevel (e.g., <literal>5.005</literal>).</para>
+
+ <para>If you need to make other substitutions, you can set the
+ <makevar>PLIST_SUB</makevar> variable with a list of
+ <literal><replaceable>VAR</replaceable>=<replaceable>VALUE</replaceable></literal>
+ pairs and instances of
+ <literal>%%<replaceable>VAR</replaceable>%%</literal>' will be
+ substituted with <replaceable>VALUE</replaceable> in the
+ <filename>PLIST</filename>.</para>
+
+ <para>For instance, if you have a port that installs many files in
+ a version-specific subdirectory, you can put something
+ like
+
+ <programlisting>
+OCTAVE_VERSION= 2.0.13
+PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
+
+ in the <filename>Makefile</filename> and use
+ <literal>%%OCTAVE_VERSION%%</literal> wherever the version shows
+ up in <filename>PLIST</filename>. That way, when you upgrade the
+ port, you will not have to change dozens (or in some cases,
+ hundreds) of lines in the <filename>PLIST</filename>.</para>
+
+ <para>This substitution (as well as addition of any <link
+ linkend="porting-manpages">man pages</link>) will be done
+ between the <maketarget>do-install</maketarget> and
+ <maketarget>post-install</maketarget> targets, by reading from
+ <makevar>PLIST</makevar> and writing to
+ <makevar>TMPPLIST</makevar> (default:
+ <filename><makevar>WRKDIR</makevar>/.PLIST.mktmp</filename>). So
+ if your port builds <makevar>PLIST</makevar> on the fly, do so in
+ or before <maketarget>do-install</maketarget>. Also, if your port
+ needs to edit the resulting file, do so in
+ <maketarget>post-install</maketarget> to a file named
+ <makevar>TMPPLIST</makevar>.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Licensing Problems</title>
+
+ <para>Some software packages have restrictive licenses or can be
+ in violation to the law (PKP's patent on public key crypto, ITAR
+ (export of crypto software) to name just two of them). What we
+ can do with them vary a lot, depending on the exact wordings of
+ the respective licenses.</para>
+
+ <note>
+ <para>It is your responsibility as a porter to read the
+ licensing terms of the software and make sure that the FreeBSD
+ project will not be held accountable of violating them by
+ redistributing the source or compiled binaries either via ftp
+ or CD-ROM. If in doubt, please contact the &a.ports;.</para>
+ </note>
+
+ <para>There are two variables you can set in the Makefile to
+ handle the situations that arise frequently:</para>
+
+
+ <orderedlist>
+
+ <listitem>
+ <para>If the port has a “do not sell for profit” type of
+ license, set the variable <makevar>NO_CDROM</makevar> to a
+ string describing the reason why. We
+ will make sure such ports won't go into the CD-ROM come
+ release time. The distfile and package will still be
+ available via ftp.</para>
+ </listitem>
+
+ <listitem>
+ <para>If the resulting package needs to be built uniquely
+ for each site, or the resulting binary package can't be
+ distributed due to licensing; set the variable
+ <makevar>NO_PACKAGE</makevar> to a string describing the
+ reason why. We will make sure such
+ packages won't go on the ftp site, nor into the CD-ROM
+ come release time. The distfile will still be included on
+ both however.</para>
+ </listitem>
+
+ <listitem>
+ <para>If the port has legal restrictions on who can use it
+ (e.g., crypto stuff) or has a “no commercial use” license,
+ set the variable <makevar>RESTRICTED</makevar> to be the
+ string describing the reason why. For such ports, the
+ distfiles/packages will not be available even from our ftp
+ sites.</para>
+ </listitem>
+
+ </orderedlist>
+
+
+ <note>
+ <para>The GNU General Public License (GPL), both version 1
+ and 2, should not be a problem for ports.</para>
+ </note>
+
+ <note>
+ <para>If you are a committer, make sure you update the
+ <filename>ports/LEGAL</filename> file too.</para>
+ </note>
+ </sect2>
+
+ <sect2>
+ <title>Upgrading</title>
+
+ <para>When you notice that a port is out of date compared to the
+ latest version from the original authors, first make sure you
+ have the latest port. You can find them in the
+ <filename>ports-current</filename> directory of the ftp mirror
+ sites.</para>
+
+ <para>The next step is to send a mail to the maintainer, if one is
+ listed in the port's <filename>Makefile</filename>. That person may already be
+ working on an upgrade, or have a reason to not upgrade the port
+ right now (because of, for example, stability problems of the
+ new version).</para>
+
+ <para>If the maintainer asks you to do the upgrade or there isn't
+ any such person to begin with, please make the upgrade and send
+ the recursive diff (either unified or context diff is fine, but
+ port committers appear to prefer unified diff more) of the new
+ and old ports directories to us (e.g., if your modified port
+ directory is called <filename>superedit</filename>
+ and the original as in our tree is
+ <filename>superedit.bak</filename>, then send us the result of
+ <command>diff -ruN superedit.bak
+ superedit</command>). Please examine the output to make
+ sure all the changes make sense. The best way to send us the
+ diff is by including it to <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ (category <literal>ports</literal>). Please mention any added or deleted files
+ in the message, as they have to be explicitly specified to CVS
+ when doing a commit. If the diff is more than about 20KB, please
+ compress and uuencode it; otherwise, just include it in as is in
+ the PR.</para>
+
+ </sect2>
+
+ <sect2>
+ <title><anchor id="porting-dads">Do's and Dont's</title>
+
+ <para>Here is a list of common do's and dont's that you encounter
+ during the porting process.You should check your own port
+ against this list, but you can also check ports in the PR
+ database that others have submitted. Submit any comments on
+ ports you check as described in <link linkend="contrib-general">Bug
+ Reports and General Commentary</link>. Checking ports in
+ the PR database will both make it faster for us to commit them,
+ and prove that you know what you are doing.</para>
+
+ <sect3>
+ <title>Strip Binaries</title>
+
+ <para>Do strip binaries. If the original source already strips the
+ binaries, fine; otherwise you should add a
+ <literal>post-install</literal> rule to to it yourself. Here is an
+ example;</para>
+
+ <programlisting>
+post-install:
+ strip ${PREFIX}/bin/xdl</programlisting>
+
+ <para>Use the <citerefentry>
+ <refentrytitle>file</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry> command on the installed executable to check
+ whether the binary is stripped or not. If it does not say
+ <literal>not stripped</literal>, it is stripped.</para>
+ </sect3>
+
+ <sect3>
+ <title>INSTALL_* macros</title>
+
+ <para>Do use the macros provided in <filename>bsd.port.mk</filename>
+ to ensure correct modes and ownership of files in your own
+ <maketarget>*-install</maketarget> targets. They are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><makevar>INSTALL_PROGRAM</makevar> is a command to install
+ binary executables.</para>
+ </listitem>
+
+ <listitem>
+ <para><makevar>INSTALL_SCRIPT</makevar> is a command to install
+ executable scripts.</para>
+ </listitem>
+
+ <listitem>
+ <para><makevar>INSTALL_DATA</makevar> is a command to install
+ sharable data.</para>
+ </listitem>
+
+ <listitem>
+ <para><makevar>INSTALL_MAN</makevar> is a command to install
+ manpages and other documentation (it doesn't compress
+ anything).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>These are basically the <command>install</command> command
+ with all the appropriate flags. See below for an example on how
+ to use them.</para>
+ </sect3>
+
+ <sect3 id="porting-versions">
+ <title>Differentiating operating systems and OS versions</title>
+
+ <para>You may come across code that needs modifications or
+ conditional compilation based upon what version of UNIX it is
+ running under. If you need to make such changes to the code for
+ conditional compilation, make sure you make the changes as general
+ as possible so that we can back-port code to FreeBSD 1.x systems
+ and cross-port to other BSD systems such as 4.4BSD from CSRG,
+ BSD/386, 386BSD, NetBSD, and OpenBSD.</para>
+
+ <para>The preferred way to tell 4.3BSD/Reno (1990) and newer
+ versions of the BSD code apart is by using the
+ <literal>BSD</literal> macro defined in
+ <filename><sys/param.h></filename>. Hopefully that file is
+ already included; if not, add the code:</para>
+
+ <programlisting>
+#if (defined(__unix__) || defined(unix)) && !defined(USG)
+#include <sys/param.h>
+#endif</programlisting>
+
+ <para>to the proper place in the <filename>.c</filename> file. We
+ believe that every system that defines these to symbols has
+ <filename>sys/param.h</filename>. If you find a system that
+ doesn't, we would like to know. Please send mail to the
+ &a.ports;.</para>
+
+ <para>Another way is to use the GNU Autoconf style of doing
+ this:</para>
+
+ <programlisting>
+#ifdef HAVE_SYS_PARAM_H
+#include <sys/param.h>
+#endif</programlisting>
+
+ <para>Don't forget to add <literal>-DHAVE_SYS_PARAM_H</literal> to
+ the <makevar>CFLAGS</makevar> in the <filename>Makefile</filename>
+ for this method.</para>
+
+ <para>Once you have <filename>sys/param.h</filename>
+ included, you may use:</para>
+
+ <programlisting>
+#if (defined(BSD) && (BSD >= 199103))</programlisting>
+
+ <para>to detect if the code is being compiled on a 4.3 Net2 code
+ base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD,
+ BSD/386 1.1 and below).</para>
+
+ <para>Use:</para>
+
+ <programlisting>
+#if (defined(BSD) && (BSD >= 199306))</programlisting>
+
+ <para>to detect if the code is being compiled on a 4.4 code base
+ or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or
+ above).</para>
+
+ <para>The value of the <literal>BSD</literal> macro is
+ <literal>199506</literal> for the 4.4BSD-Lite2 code base. This is
+ stated for informational purposes only. It should not be used to
+ distinguish between version of FreeBSD based only on 4.4-Lite vs.
+ versions that have merged in changes from 4.4-Lite2. The
+ <literal>__FreeBSD__</literal> macro should be used
+ instead.</para>
+
+ <para>Use sparingly:</para>
+
+
+ <itemizedlist>
+
+ <listitem>
+ <para><literal>__FreeBSD__</literal> is defined in all
+ versions of FreeBSD. Use it if the change you are making
+ <emphasis>only</emphasis> affects FreeBSD. Porting gotchas like the use of
+ <literal>sys_errlist[]</literal> vs
+ <function>strerror()</function> are Berkeleyisms, not
+ FreeBSD changes.</para>
+ </listitem>
+
+ <listitem>
+ <para>In FreeBSD 2.x, <literal>__FreeBSD__</literal> is
+ defined to be <literal>2</literal>. In earlier
+ versions, it is <literal>1</literal>. Later
+ versions will bump it to match their major version number.</para>
+ </listitem>
+
+ <listitem>
+ <para>If you need to tell the difference between a FreeBSD
+ 1.x system and a FreeBSD 2.x or 3.x system, usually the
+ right answer is to use the <literal>BSD</literal> macros
+ described above. If there actually is a FreeBSD specific
+ change (such as special shared library options when using
+ <command>ld</command>) then it is OK to use
+ <literal>__FreeBSD__</literal> and <literal>#if
+ __FreeBSD__ > 1</literal> to detect a FreeBSD 2.x
+ and later system. If you need more granularity in
+ detecting FreeBSD systems since 2.0-RELEASE you can use
+ the following:</para>
+
+ <programlisting>
+#if __FreeBSD__ >= 2
+#include <osreldate.h>
+# if __FreeBSD_version >= 199504
+ /* 2.0.5+ release specific code here */
+# endif
+#endif</programlisting>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Release</entry>
+ <entry><literal>_FreeBSD_version</literal></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>2.0-RELEASE</entry>
+ <entry>119411</entry>
+ </row>
+
+ <row>
+ <entry>2.1-currents</entry>
+ <entry>199501, 199503</entry>
+ </row>
+
+ <row>
+ <entry>2.0.5-RELEASE</entry>
+ <entry>199504</entry>
+ </row>
+
+ <row>
+ <entry>2.2-current before 2.1</entry>
+ <entry>199508</entry>
+ </row>
+
+ <row>
+ <entry>2.1.0-RELEASE</entry>
+ <entry>199511</entry>
+ </row>
+
+ <row>
+ <entry>2.2-current before 2.1.5</entry>
+ <entry>199512</entry>
+ </row>
+
+ <row>
+ <entry>2.1.5-RELEASE</entry>
+ <entry>199607</entry>
+ </row>
+
+ <row>
+ <entry>2.2-current before 2.1.6</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 (no change)</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.1-RELEASE</entry>
+ <entry>220000 (no change)</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after texinfo-3.9</entry>
+ <entry>221001</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after top</entry>
+ <entry>221002</entry>
+ </row>
+
+ <row>
+ <entry>2.2.2-RELEASE</entry>
+ <entry>222000</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.2-RELEASE</entry>
+ <entry>222001</entry>
+ </row>
+
+ <row>
+ <entry>2.2.5-RELEASE</entry>
+ <entry>225000</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.5-RELEASE</entry>
+ <entry>225001</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after ldconfig -R merge</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-STABLE after 2.2.7-RELEASE</entry>
+ <entry>227001</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after semctl(2) change</entry>
+ <entry>227002</entry>
+ </row>
+
+ <row>
+ <entry>2.2.8-RELEASE</entry>
+ <entry>228000</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.8-RELEASE</entry>
+ <entry>228001</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current before mount(2) change</entry>
+ <entry>300000</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after mount(2) change</entry>
+ <entry>300001</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after semctl(2) change</entry>
+ <entry>300002</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after ioctl arg changes</entry>
+ <entry>300003</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after ELF conversion</entry>
+ <entry>300004</entry>
+ </row>
+
+ <row>
+ <entry>3.0-RELEASE</entry>
+ <entry>300005</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after 3.0-RELEASE</entry>
+ <entry>300006</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </listitem>
+ </itemizedlist>
+
+ <note>
+ <para>Note that 2.2-STABLE sometimes identifies itself as
+ “2.2.5-STABLE” after the 2.2.5-RELEASE. The pattern used to
+ be year followed by the month, but we decided to change it
+ to a more straightforward major/minor system starting from
+ 2.2. This is because the parallel development on several
+ branches made it infeasible to classify the releases simply
+ by their real release dates. If you are making a port now,
+ you don't have to worry about old -current's; they are
+ listed here just for your reference.</para>
+ </note>
+
+
+ <para>In the hundreds of ports that have been done, there have
+ only been one or two cases where <literal>__FreeBSD__</literal>
+ should have been used. Just because an earlier port screwed up
+ and used it in the wrong place does not mean you should do so
+ too.</para>
+ </sect3>
+
+ <sect3>
+ <title>Writing something after
+ <filename>bsd.port.mk</filename></title>
+
+ <para>Do not write anything after the <literal>.include
+ <bsd.port.mk></literal> line. it usually can be avoided by
+ including <filename>bsd.port.pre.mk</filename> somewhere in the
+ middle of your <filename>Makefile</filename> and
+ <filename>bsd.port.post.mk</filename> at the end.</para>
+
+ <note>
+ <para>You need to include either the
+ <filename>pre.mk</filename>/<filename>post.mk</filename> pair or
+ <filename>bsd.port.mk</filename> only; don't mix these
+ two.</para>
+ </note>
+
+ <para><filename>bsd.port.pre.mk</filename> only defines a few
+ variables, which can be used in tests in the
+ <filename>Makefile</filename>,
+ <filename>bsd.port.post.mk</filename> defines the rest.</para>
+
+ <para>Here are some important variables defined in
+ <filename>bsd.port.pre.mk</filename> (this is not the complete
+ list, please read <filename>bsd.port.mk</filename> for the
+ complete list).</para>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Variable</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><makevar>ARCH</makevar></entry>
+ <entry>The architecture as returned by <command>uname
+ -m</command> (e.g., <literal>i386</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>OPSYS</makevar></entry>
+ <entry>The operating system type, as returned by
+ <command>uname -s</command> (e.g.,
+ <literal>FreeBSD</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>OSREL</makevar></entry>
+ <entry>The release version of the operating system (e.g.,
+ <literal>2.1.5</literal> or
+ <literal>2.2.7</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>OSVERSION</makevar></entry>
+ <entry>The numeric version of the operating system, same as
+ <link
+ linkend="porting-versions"><literal>__FreeBSD_version</literal></link>.</entry>
+ </row>
+
+ <row>
+ <entry><makevar>PORTOBJFORMAT</makevar></entry>
+ <entry>The object format of the system
+ (<literal>aout</literal> or <literal>elf</literal></entry>
+ </row>
+
+ <row>
+ <entry><makevar>LOCALBASE</makevar></entry>
+ <entry>The base of the “local” tree (e.g.,
+ <literal>/usr/local/</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>X11BASE</makevar></entry>
+ <entry>The base of the “X11” tree (e.g.,
+ <literal>/usr/X11R6</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>PREFIX</makevar></entry>
+ <entry>Where the port installs itself (see <link
+ linkend="porting-prefix">more on
+ <makevar>PREFIX</makevar></link>).</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <note>
+ <para>If you have to define the variables
+ <makevar>USE_IMAKE</makevar>, <makevar>USE_X_PREFIX</makevar>,
+ or <makevar>MASTERDIR</makevar>, do so before including
+ <filename>bsd.port.pre.mk</filename>.</para>
+ </note>
+
+ <para>Here are some examples of things you can write after
+ <filename>bsd.port.pre.mk</filename>;</para>
+
+ <programlisting>
+# no need to compile lang/perl5 if perl5 is already in system
+.if ${OSVERSION} > 300003
+BROKEN= perl is in system
+.endif
+
+# only one shlib version number for ELF
+.if ${PORTOBJFORMAT} == "elf"
+TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}
+.else
+TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}.${SHLIB_MINOR}
+.endif
+
+# software already makes link for ELF, but not for a.out
+post-install:
+.if ${PORTOBJFORMAT} == "aout"
+ ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so
+.endif</programlisting>
+ </sect3>
+
+ <sect3>
+ <title>Install additional documentation</title>
+
+ <para>If your software has some documentation other than the
+ standard man and info pages that you think is useful for the
+ user, install it under
+ <filename><makevar>PREFIX</makevar>/share/doc</filename>. This can be
+ done, like the previous item, in the <maketarget>post-install</maketarget> target.</para>
+
+ <para>Create a new directory for your port. The directory name
+ should reflect what the port is. This usually means <makevar>PKGNAME</makevar> minus the version part.
+ However, if you think the user might want different versions
+ of the port to be installed at the same time, you can use the
+ whole <makevar>PKGNAME</makevar>.</para>
+
+ <para>Make the installation dependent to the variable
+ <makevar>NOPORTDOCS</makevar> so that users can disable it in
+ <filename>/etc/make.conf</filename>, like this:</para>
+
+ <programlisting>
+post-install:
+.if !defined(NOPORTDOCS)
+ ${MKDIR}${PREFIX}/share/doc/xv
+ ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
+.endif</programlisting>
+
+ <para>Do not forget to add them to
+ <filename>pkg/PLIST</filename> too! (Do not worry about
+ <makevar>NOPORTDOCS</makevar> here; there is currently no way
+ for the packages to read variables from
+ <filename>/etc/make.conf</filename>.)</para>
+
+ <para>Also you can use the <filename>pkg/MESSAGE</filename> file to
+ display messages upon installation. See the <link
+ linkend="porting-message">using
+ <filename>pkg/MESSAGE</filename></link> section for
+ details.</para>
+
+ <note>
+ <para><filename>MESSAGE</filename> does not need to be added
+ to <filename>pkg/PLIST</filename>).</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><makevar>DIST_SUBDIR</makevar></title>
+
+ <para>Do not let your port clutter
+ <filename>/usr/ports/distfiles</filename>. If your port
+ requires a lot of files to be fetched, or contains a file that
+ has a name that might conflict with other ports (e.g.,
+ <filename>Makefile</filename>), set <makevar>DIST_SUBDIR</makevar> to the name of the
+ port (<makevar>PKGNAME</makevar> without the
+ version part should work fine). This will change <makevar>DISTDIR</makevar> from the default
+ <filename>/usr/ports/distfiles</filename> to
+ <filename>/usr/ports/distfiles/<makevar>DIST_SUBDIR</makevar></filename>,
+ and in effect puts everything that is required for your port
+ into that subdirectory.</para>
+
+ <para>It will also look at the subdirectory with the same name
+ on the backup master site at
+ <filename>ftp.freebsd.org</filename>. (Setting <makevar>DISTDIR</makevar> explicitly in your
+ <makevar>Makefile</makevar> will not accomplish this, so please use <makevar>DIST_SUBDIR</makevar>.)</para>
+
+ <note>
+ <para>This does not affect the <makevar>MASTER_SITES</makevar> you define in your
+ Makefile.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>Package information</title>
+
+ <para>Do include package information, i.e.
+ <filename>COMMENT</filename>, <filename>DESCR</filename>, and
+ <filename>PLIST</filename>, in <filename>pkg</filename>.</para>
+
+ <note>
+ <para>Note that these files are not used only for packaging
+ anymore, and are <emphasis>mandatory</emphasis> now, even if
+ <makevar>NO_PACKAGE</makevar> is
+ set.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>RCS strings</title>
+
+ <para>Do not put RCS strings in patches. CVS will mangle them
+ when we put the files into the ports tree, and when we check
+ them out again, they will come out different and the patch
+ will fail. RCS strings are surrounded by dollar (<literal>$</literal>) signs, and typically start with
+ <literal>$Id</literal> or <literal>$RCS</literal>.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Recursive diff</title>
+
+ <para>Using the recurse (<option>-r</option>) option to
+ <command>diff</command> to generate patches is
+ fine, but please take a look at the resulting patches to make
+ sure you don't have any unnecessary junk in there. In
+ particular, diffs between two backup files, <filename>Makefiles</filename> when the
+ port uses <command>Imake</command> or GNU <command>configure</command>, etc., are unnecessary and
+ should be deleted. If you had to edit
+ <filename>configure.in</filename> and run
+ <command>autoconf</command> to regenerate
+ <command>configure</command>, do not take the diffs of
+ <command>configure</command> (it often grows to a few thousand
+ lines!); define <literal>USE_AUTOCONF=yes</literal> and take the
+ diffsof <filename>configure.in</filename>.</para>
+
+ <para>Also, if you had to delete a file, then you
+ can do it in the <maketarget>post-extract</maketarget>
+ target rather than as part of the patch. Once you are happy
+ with the resulting diff, please split it up into one source
+ file per patch file.</para>
+
+ </sect3>
+
+ <sect3 id="porting-prefix">
+ <title><makevar>PREFIX</makevar></title>
+
+ <para>Do try to make your port install relative to <makevar>PREFIX</makevar>. (The value of this
+ variable will be set to <makevar>LOCALBASE</makevar> (default
+ <filename>/usr/local</filename>), unless <makevar>USE_X_PREFIX</makevar> or <makevar>USE_IMAKE</makevar> is set, in which case it
+ will be <makevar>X11BASE</makevar> (default
+ <filename>/usr/X11R6</filename>).)</para>
+
+ <para>Not hard-coding <filename>/usr/local</filename> or
+ <filename>/usr/X11R6</filename> anywhere in the source will
+ make the port much more flexible and able to cater to the
+ needs of other sites. For X ports that use <command>imake</command>, this is
+ automatic; otherwise, this can often be done by simply
+ replacing the occurrences of <filename>/usr/local</filename>
+ (or <filename>/usr/X11R6</filename> for X ports that do not
+ use imake) in the various scripts/Makefiles in the port to
+ read <makevar>PREFIX</makevar>, as this
+ variable is automatically passed down to every stage of the
+ build and install processes.</para>
+
+ <para>Do not set <makevar>USE_X_PREFIX</makevar> unless your port
+ truly require it (i.e., it links against X libs or it needs to
+ reference files in <makevar>X11BASE</makevar>).</para>
+
+ <para>The variable <makevar>PREFIX</makevar>
+ can be reassigned in your <filename>Makefile</filename> or in the user's
+ environment. However, it is strongly discouraged for
+ individual ports to set this variable explicitly in the
+ <filename>Makefiles</filename>.</para>
+
+ <para>Also, refer to programs/files from other ports with the
+ variables mentioned above, not explicit pathnames. For
+ instance, if your port requires a macro
+ <literal>PAGER</literal> to be the full pathname of <command>less</command>, use the compiler flag:
+
+ <programlisting>
+-DPAGER=\"${PREFIX}/bin/less\"</programlisting>
+
+ or
+
+ <programlisting>
+-DPAGER=\"${LOCALBASE}/bin/less\"</programlisting>
+
+ if this is an X port, instead of <literal>-DPAGER=\"/usr/local/bin/less\".</literal> This way it will have a better chance of working if the system administrator has moved the whole `/usr/local' tree somewhere else.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Subdirectories</title>
+
+ <para>Try to let the port put things in the right subdirectories
+ of <makevar>PREFIX</makevar>. Some ports
+ lump everything and put it in the subdirectory with the port's
+ name, which is incorrect. Also, many ports put everything
+ except binaries, header files and manual pages in the a
+ subdirectory of <filename>lib</filename>, which does not
+ bode well with the BSD paradigm. Many of the files should be
+ moved to one of the following: <filename>etc</filename>
+ (setup/configuration files), <filename>libexec</filename>
+ (executables started internally), <filename>sbin</filename>
+ (executables for superusers/managers),
+ <filename>info</filename> (documentation for info browser)
+ or <filename>share</filename> (architecture independent
+ files). See man <citerefentry><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+ details, the rule governing <filename>/usr</filename> pretty
+ much applies to <filename>/usr/local</filename> too. The
+ exception are ports dealing with USENET “news”. They may use
+ <filename><makevar>PREFIX</makevar>/news</filename> as a destination for
+ their files.</para>
+
+ </sect3>
+
+ <sect3 id="porting-cleaning">
+ <title>Cleaning up empty directories</title>
+
+ <para>Do make your ports clean up after themselves when they are
+ deinstalled. This is usually accomplished by adding
+ <literal>@dirrm</literal> lines for all directories that are
+ specifically created by the port. You need to delete
+ subdirectories before you can delete parent directories.</para>
+
+ <programlisting>
+ :
+lib/X11/oneko/pixmaps/cat.xpm
+lib/X11/oneko/sounds/cat.au
+ :
+@dirrm lib/X11/oneko/pixmals
+@dirrm lib/X11/oneko/sounds
+@dirrm lib/X11/oneko</programlisting>
+
+ <para>However, sometimes <literal>@dirrm</literal> will give you
+ errors because other ports also share the same subdirectory. You
+ can call <command>rmdir</command> from <literal>@unexec</literal>
+ to remove only empty directories without warning.</para>
+
+ <programlisting>
+@unexec rmdir %D/share/doc/gimp 2>/dev/null || true</programlisting>
+
+ <para>This will neither print any error messages nor cause
+ <command>pkg_delete</command> to exit abnormally even if
+ <filename><makevar>PREFIX</makevar>/share/doc/gimp</filename> is
+ not empty due to other ports installing some files in there.</para>
+ </sect3>
+
+
+ <sect3>
+ <title>UIDs</title>
+
+ <para>If your port requires a certain user to be on the
+ installed system, let the <filename>pkg/INSTALL</filename>
+ script call <command>pw</command> to create it
+ automatically. Look at <filename>net/cvsup-mirror</filename>
+ for an example.</para>
+
+ <para>If your port must use the same user/group ID number when it is
+ installed a binarypackage as when it was compiled, then you mus
+ choose a free UID from 50 to 99 and register it below. Look at
+ <filename>japanese/Wnn</filename> for an example.</para>
+
+ <para>Make sure you don't use a UID already used by the system
+ or other ports. This is the current list of UIDs between 50
+ and 99.</para>
+
+ <programlisting>
+majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent
+cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent
+gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh
+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:/nonexistent
+wnn:*:69:7:Wnn:/nonexistent:/nonexistent
+ifmail:*:70:66:Ifmail user:/nonexistent:/nonexistent
+pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh
+ircd:*:72:72:IRCd hybrid:/nonexistent:/nonexistent
+alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent
+qmaill:*:83:81:QMail user:/var/qmail:/nonexistent
+qmaild:*:82:81:QMail user:/var/qmail:/nonexistent
+qmailq:*:85:82:QMail user:/var/qmail:/nonexistent
+qmails:*:87:82:QMail user:/var/qmail:/nonexistent
+qmailp:*:84:81:QMail user:/var/qmail:/nonexistent
+qmailr:*:86:82:QMail user:/var/qmail:/nonexistent
+msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh</programlisting>
+
+ <para>Please include a notice when you submit a port (or an
+ upgrade) that reserves a new UID or GID in this range. This allows
+ us to keep the list of reserved IDs up to date.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Do things rationally</title>
+
+ <para>The <filename>Makefile</filename> should do things simply and
+ reasonably. If you can make it a couple of lines shorter or more
+ readable, then do so. Examples include using a make
+ <literal>.if</literal> construct instead of a shell
+ <literal>if</literal> construct, not redefining
+ <maketarget>do-extract</maketarget> if you can redefine
+ <makevar>EXTRACT*</makevar> instead, and using
+ <makevar>GNU_CONFIGURE</makevar> instead of
+ <literal>CONFIGURE_ARGS +=
+ --prefix=${PREFIX}</literal>.</para>
+ </sect3>
+
+ <sect3>
+ <title>Respect <makevar>CFLAGS</makevar></title>
+
+ <para>The port should respect the <makevar>CFLAGS</makevar>
+ variable. If it doesn't, please add <literal>NO_PACKAGE=ignores
+ cflags</literal> to the <filename>Makefile</filename>.</para>
+ </sect3>
+
+ <sect3>
+ <title>Configuration files</title>
+
+ <para>If your port requires some configuration files in
+ <filename><makevar>PREFIX</makevar>/etc</filename>, do
+ <emphasis>not</emphasis> just install them and list them in
+ <filename>pkg/PLIST</filename>. That will cause
+ <command>pkg_delete</command> to delete files carefully edited by
+ the user and a new installation to wipe them out.</para>
+
+ <para>Instead, install sample files with a suffix
+ (<filename><replaceable>filename</replaceable>.sample</filename>
+ will work well) and print out a <link
+ linkend="porting-message">message</link> pointing out that the
+ user has to copy and edit the file before the software can be made
+ to work.</para>
+ </sect3>
+
+ <sect3>
+ <title>Portlint</title>
+
+ <para>Do check your work with <link
+ linkend="porting-portlint"><command>portlint</command></link>
+ before you submit or commit it.</para>
+ </sect3>
+
+ <sect3>
+ <title>Feedback</title>
+
+ <para>Do send applicable changes/patches to the original
+ author/maintainer for inclusion in next release of the code. This
+ will only make your job that much easier for the next
+ release.</para>
+ </sect3>
+
+ <sect3>
+ <title>Miscellanea</title>
+
+ <para>The files <filename>pkg/DESCR</filename>,
+ <filename>pkg/COMMENT</filename>, and
+ <filename>pkg/PLIST</filename> should each be double-checked. If
+ you are reviewing a port and feel they can be worded better, do
+ so.</para>
+
+ <para>Don't copy more copies of the GNU General Public License into
+ our system, please.</para>
+
+ <para>Please be careful to note any legal issues! Don't let us
+ illegally distribute software!</para>
+ </sect3>
+
+ <sect3>
+ <title>If you are stuck…</title>
+
+ <para>Do look at existing examples and the
+ <filename>bsd.port.mk</filename> file before asking us
+ questions! <!-- smiley --><emphasis>;)</emphasis></para>
+
+ <para>Do ask us questions if you have any trouble! Do not just
+ beat your head against a wall! <!-- smiley --><emphasis>:)</emphasis></para>
+
+ </sect3>
+ </sect2>
+
+ <sect2 id="porting-samplem">
+ <title>A Sample <filename>Makefile</filename></title>
+
+ <para>Here is a sample <filename>Makefile</filename> that you can
+ use to create a new port. Make sure you remove all the extra
+ comments (ones between brackets)!</para>
+
+ <para>It is recommended that you follow this format (ordering of
+ variables, empty lines between sections, etc.). This format is
+ designed so that the most important information is easy to
+ locate. We recommend that you use <link
+ linkend="porting-portlint">portlint</link> to check the <filename>Makefile</filename>.</para>
+
+ <programlisting>
+[the header...just to make it easier for us to identify the ports.]
+# New ports collection makefile for: xdvi
+[the version required header should updated when upgrading a port.]
+# Version required: pl18 [things like "1.5alpha" are fine here too]
+[this is the date when the first version of this Makefile was created.
+Never change this when doing an update of the port.]
+# Date created: 26 May 1995
+[this is the person who did the original port to FreeBSD, in particular, the
+person who wrote the first version of this Makefile. Remember, this should
+not be changed when upgrading the port later.]
+# Whom: Satoshi Asami <asami@FreeBSD.ORG>
+#
+# $Id$
+[ ^^^^ This will be automatically replaced with RCS ID string by CVS
+when it is committed to our repository.]
+#
+
+[section to describe the port itself and the master site - DISTNAME
+ is always first, followed by PKGNAME (if necessary), CATEGORIES,
+ and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR.
+ After those, one of EXTRACT_SUFX or DISTFILES can be specified too.]
+DISTNAME= xdvi
+PKGNAME= xdvi-pl18
+CATEGORIES= print
+[do not forget the trailing slash ("/")!
+ if you aren't using MASTER_SITE_* macros]
+MASTER_SITES= ${MASTER_SITE_XCONTRIB}
+MASTER_SITE_SUBDIR= applications
+[set this if the source is not in the standard ".tar.gz" form]
+EXTRACT_SUFX= .tar.Z
+
+[section for distributed patches -- can be empty]
+PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/
+PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz
+
+[maintainer; *mandatory*! This is the person (preferably with commit
+ privileges) who a user can contact for questions and bug reports - this
+ person should be the porter or someone who can forward questions to the
+ original porter reasonably promptly. If you really do not want to have
+ your address here, set it to "ports@FreeBSD.ORG".]
+MAINTAINER= asami@FreeBSD.ORG
+
+[dependencies -- can be empty]
+RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript
+LIB_DEPENDS= Xpm.5:${PORTSDIR}/graphics/xpm
+
+[this section is for other standard bsd.port.mk variables that do not
+ belong to any of the above]
+[If it asks questions during configure, build, install...]
+IS_INTERACTIVE= yes
+[If it extracts to a directory other than ${DISTNAME}...]
+WRKSRC= ${WRKDIR}/xdvi-new
+[If the distributed patches were not made relative to ${WRKSRC}, you
+ may need to tweak this]
+PATCH_DIST_STRIP= -p1
+[If it requires a "configure" script generated by GNU autoconf to be run]
+GNU_CONFIGURE= yes
+[If it requires GNU make, not /usr/bin/make, to build...]
+USE_GMAKE= yes
+[If it is an X application and requires "xmkmf -a" to be run...]
+USE_IMAKE= yes
+[et cetera.]
+
+[non-standard variables to be used in the rules below]
+MY_FAVORITE_RESPONSE= "yeah, right"
+
+[then the special rules, in the order they are called]
+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
+
+[and then the epilogue]
+.include <bsd.port.mk></programlisting>
+
+ </sect2>
+
+ <sect2 id="porting-pkgname">
+ <title>Package Names</title>
+
+ <para>The following are the conventions you should follow in
+ naming your packages. This is to have our package directory
+ easy to scan, as there are already lots and lots of packages and
+ users are going to turn away if they hurt their eyes!</para>
+
+ <para>The package name should look like <filename><replaceable>language-</replaceable>name<replaceable>-compiled.specifics</replaceable><replaceable>-version.numbers</replaceable></filename>.</para>
+
+ <para>If your <makevar>DISTNAME</makevar>
+ doesn't look like that, set <makevar>PKGNAME</makevar> to something in that
+ format.</para>
+
+
+ <orderedlist>
+
+ <listitem>
+ <para>FreeBSD strives to support the native language of its
+ users. The <replaceable>language-</replaceable> part should be a two letter
+ abbreviation of the natural language defined by ISO-639 if
+ the port is specific to a certain language. Examples are
+ <literal>ja</literal> for Japanese, <literal>ru</literal> for Russian, <literal>vi</literal> for Vietnamese,
+ <literal>zh</literal> for Chinese, <literal>ko</literal> for Korean and <literal>de</literal> for German.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <filename>name</filename> part
+ should be all lowercases, except for a really large
+ package (with lots of programs in it). Things like
+ XFree86 (yes there really is a port of it, check it
+ out) and ImageMagick fall into this category. Otherwise,
+ convert the name (or at least the first letter) to
+ lowercase. If the capital letters are
+ important to the name (for example, with one-letter names
+ like <literal>R</literal> or <literal>V</literal>) you may use capital letters at your discretion.
+ There is a tradition of naming Perl 5 modules by prepending
+ <literal>p5-</literal> and converting the double-colon separator to a hyphen;
+ for example, the <literal>Data::Dumper</literal> module becomes
+ <literal>p5-Data-Dumper</literal>. If the software in question has numbers,
+ hyphens, or underscores in its name, you may include them as
+ well (like <literal>kinput2</literal>).</para>
+ </listitem>
+
+ <listitem>
+ <para>If the port can be built with different <link linkend="porting-masterdir">hardcoded
+ defaults</link> (usually part of the directory name in a
+ family of ports), the
+ <replaceable>-compiled.specifics</replaceable> part should state the
+ compiled-in defaults (the hyphen is optional). Examples
+ are papersize and font units.</para>
+ </listitem>
+
+ <listitem>
+ <para>The version string should be a period-separated list
+ of integers and single lowercase alphabetics. The only
+ exception is the string <literal>pl</literal> (meaning `patchlevel'), which
+ can be used <emphasis>only</emphasis> when there are no
+ major and minor version numbers in the software.</para>
+ </listitem>
+
+ </orderedlist>
+
+
+ <para>Here are some (real) examples on how to convert a <makevar>DISTNAME</makevar> into a suitable <makevar>PKGNAME</makevar>:</para>
+
+ <informaltable frame="none">
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Distribution Name</entry>
+ <entry>Package Name</entry>
+ <entry>Reason</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>mule-2.2.2.</entry>
+ <entry>mule-2.2.2</entry>
+ <entry>No changes required</entry>
+ </row>
+
+ <row>
+ <entry>XFree86-3.1.2</entry>
+ <entry>XFree86-3.1.2</entry>
+ <entry>No changes required</entry>
+ </row>
+
+ <row>
+ <entry>EmiClock-1.0.2</entry>
+ <entry>emiclock-1.0.2</entry>
+ <entry>No uppercase names for single programs</entry>
+ </row>
+
+ <row>
+ <entry>gmod1.4</entry>
+ <entry>gmod-1.4</entry>
+ <entry>Need a hyphen before version numbers</entry>
+ </row>
+
+ <row>
+ <entry>xmris.4.0.2</entry>
+ <entry>xmris-4.0.2</entry>
+ <entry>Need a hyphen before version numbers</entry>
+ </row>
+
+ <row>
+ <entry>rdist-1.3alpha</entry>
+ <entry>rdist-1.3a</entry>
+ <entry>No strings like <literal>alpha</literal>
+ allowed</entry>
+ </row>
+
+ <row>
+ <entry>es-0.9-beta1</entry>
+ <entry>es-0.9b1</entry>
+ <entry>No strings like <literal>beta</literal>
+ allowed</entry>
+ </row>
+
+ <row>
+ <entry>v3.3beta021.src</entry>
+ <entry>tiff-3.3</entry>
+ <entry>What the heck was that anyway?</entry>
+ </row>
+
+ <row>
+ <entry>tvtwm</entry>
+ <entry>tvtwm-pl11</entry>
+ <entry>Version string always required</entry>
+ </row>
+
+ <row>
+ <entry>piewm</entry>
+ <entry>piewm-1.0</entry>
+ <entry>Version string always required</entry>
+ </row>
+
+ <row>
+ <entry>xvgr-2.10pl1</entry>
+ <entry>xvgr-2.10.1</entry>
+ <entry><literal>pl</literal> allowed only when no
+ major/minor version numbers</entry>
+ </row>
+
+ <row>
+ <entry>gawk-2.15.6</entry>
+ <entry>ja-gawk-2.15.6</entry>
+ <entry>Japanese language version</entry>
+ </row>
+
+ <row>
+ <entry>psutils-1.13</entry>
+ <entry>psutils-letter-1.13</entry>
+ <entry>Papersize hardcoded at package build time</entry>
+ </row>
+
+ <row>
+ <entry>pkfonts</entry>
+ <entry>pkfonts300-1.0</entry>
+ <entry>Package for 300dpi fonts</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>If there is absolutely no trace of version information in
+ the original source and it is unlikely that the original author
+ will ever release another version, just set the version string
+ to <literal>1.0</literal> (like the piewm example above). Otherwise, ask the
+ original author or use the date string (<literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>) as the
+ version.</para>
+
+ </sect2>
+
+ <sect2 id="porting-categories">
+ <title>Categories</title>
+
+ <para>As you already know, ports are classified in several
+ categories. But for this to wor, it is important that porters and
+ users understand what each category and how we deicde what to put in
+ each category.</para>
+
+ <sect3>
+ <title>Current list of categories</title>
+
+ <para>First, this is the current list of port categories. Those
+ marked with an asterisk (<literal>*</literal>) are
+ <emphasis>virtual</emphasis> categories—those that do not
+ have a corresponding subdirectory in the ports tree.</para>
+
+ <note>
+ <para>For non-virtual categories, you will find a one-line
+ description in the <filename>pkg/COMMENT</filename> file in that
+ subdirectory (e.g.,
+ <filename>archivers/pkg/COMMENT</filename>).</para>
+ </note>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Category</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><filename>archivers</filename></entry>
+ <entry>Archiving tools.</entry>
+ </row>
+
+ <row>
+ <entry><filename>astro</filename></entry>
+ <entry>Astronomical ports.</entry>
+ </row>
+
+ <row>
+ <entry><filename>audio</filename></entry>
+ <entry>Sound support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>benchmarks</filename></entry>
+ <entry>Benchmarking utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>biology</filename></entry>
+ <entry>Biology-related software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>cad</filename></entry>
+ <entry>Computer aided design tools.</entry>
+ </row>
+
+ <row>
+ <entry><filename>chinese</filename></entry>
+ <entry>Chinese language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>comms</filename></entry>
+ <entry>Communication software. Mostly software to talk to
+ your serial port.</entry>
+ </row>
+
+ <row>
+ <entry><filename>converters</filename></entry>
+ <entry>Character code converters.</entry>
+ </row>
+
+ <row>
+ <entry><filename>databases</filename></entry>
+ <entry>Databases.</entry>
+ </row>
+
+ <row>
+ <entry><filename>deskutils</filename></entry>
+ <entry>Things that used to be on the desktop before
+ computers were invented.</entry>
+ </row>
+
+ <row>
+ <entry><filename>devel</filename></entry>
+ <entry>Development utilities. Do not put libraries here just
+ because they are libraries—unless they truly don't
+ belong to anywhere else, they shouldn't be in this
+ category.</entry>
+ </row>
+
+ <row>
+ <entry><filename>editors</filename></entry>
+ <entry>General editors. Specialized editors go in the
+ section for those tools (e.g., a mathematical-formula
+ editor will go in <filename>math</filename>).</entry>
+ </row>
+
+ <row>
+ <entry><filename>elisp</filename></entry>
+ <entry>Emacs-lisp ports.</entry>
+ </row>
+
+ <row>
+ <entry><filename>emulators</filename></entry>
+ <entry>Emulators for other operating systems. Terminal
+ emulators do <emphasis>not</emphasis> belong
+ here—X-based ones should go to
+ <filename>x11</filename> and text-based ones to either
+ <filename>comms</filename> or <filename>misc</filename>,
+ depending on the exact functionality.</entry>
+ </row>
+
+ <row>
+ <entry><filename>games</filename></entry>
+ <entry>Games.</entry>
+ </row>
+
+ <row>
+ <entry><filename>german</filename></entry>
+ <entry>German language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>graphics</filename></entry>
+ <entry>Graphics utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>japanese</filename></entry>
+ <entry>Japanese language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>kde*</filename></entry>
+ <entry>Ports that form the K Desktop Environment
+ (kde).</entry>
+ </row>
+
+ <row>
+ <entry><filename>korean</filename></entry>
+ <entry>Korean language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>lang</filename></entry>
+ <entry>Programming languages.</entry>
+ </row>
+
+ <row>
+ <entry><filename>mail</filename></entry>
+ <entry>Mail software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>math</filename></entry>
+ <entry>Numerical computation software and other utilities
+ for mathematics.</entry>
+ </row>
+
+ <row>
+ <entry><filename>mbone</filename></entry>
+ <entry>MBone applications.</entry>
+ </row>
+
+ <row>
+ <entry><filename>misc</filename></entry>
+ <entry>Miscellaneous utilities—basically things that
+ doesn't belong to anywhere else. This is the only category
+ that should not appear with any other non-virtual
+ category. If you have <literal>misc</literal> with
+ something else in your <makevar>CATEGORIES</makevar> line,
+ that means you can safely delete <literal>misc</literal>
+ and just put the port in that other subdirectory!</entry>
+ </row>
+
+ <row>
+ <entry><filename>net</filename></entry>
+ <entry>Miscellaneous networking software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>news</filename></entry>
+ <entry>USENET news software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>offix*</filename></entry>
+ <entry>Ports from the OffiX suite.</entry>
+ </row>
+
+ <row>
+ <entry><filename>perl5*</filename></entry>
+ <entry>Ports that require perl version 5 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>pilot*</filename></entry>
+ <entry>Software to use with the 3Com PalmPilot.</entry>
+ </row>
+
+ <row>
+ <entry><filename>plan9</filename></entry>
+ <entry>Various programs from Plan9.</entry>
+ </row>
+
+ <row>
+ <entry><filename>print</filename></entry>
+ <entry>Printing software. Desktop publishing tools
+ (previewers, etc.) belong here too.</entry>
+ </row>
+
+ <row>
+ <entry><filename>python*</filename></entry>
+ <entry>Software written in python.</entry>
+ </row>
+
+ <row>
+ <entry><filename>russian</filename></entry>
+ <entry>Russian language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>security</filename></entry>
+ <entry>Security utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>shells</filename></entry>
+ <entry>Command line shells.</entry>
+ </row>
+
+ <row>
+ <entry><filename>sysutils</filename></entry>
+ <entry>System utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl75*</filename></entry>
+ <entry>Ports that use tcl version 7.5 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl76*</filename></entry>
+ <entry>Ports that use tcl version 7.6 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl80*</filename></entry>
+ <entry>Ports that use tcl version 8.0 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl81*</filename></entry>
+ <entry>Ports that use tcl version 8.1 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>textproc</filename></entry>
+ <entry>Text processing utilities. It does not include
+ desktop publishing tools, which go to print/.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk41*</filename></entry>
+ <entry>Ports that use tk version 4.1 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk42*</filename></entry>
+ <entry>Ports that use tk version 4.2 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk80*</filename></entry>
+ <entry>Ports that use tk version 8.0 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk81*</filename></entry>
+ <entry>Ports that use tk version 8.1 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>vietnamese</filename></entry>
+ <entry>Vietnamese language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>www</filename></entry>
+ <entry>Software related to the World Wide Web. HTML language
+ support belong here too.</entry>
+ </row>
+
+ <row>
+ <entry>x11</entry>
+ <entry>The X window system and friends. This category is
+ only for software that directly support the window system.
+ Do not put regular X applications here. If your port is
+ an X application, define <makevar>USE_XLIB</makevar>
+ (implied by <makevar>USE_IMAKE</makevar>) and put it in
+ appropriate categories. Also, many of them go into other
+ <filename>x11-*</filename> categories (see below).</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-clocks</filename></entry>
+ <entry>X11 clocks.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-fm</filename></entry>
+ <entry>X11 file managers.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-fonts</filename></entry>
+ <entry>X11 fonts and font utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-toolkits</filename></entry>
+ <entry>X11 toolkits.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-wm</filename></entry>
+ <entry>X11 window managers.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect3>
+
+ <sect3>
+ <title>Choosing the right category</title>
+
+ <para>As many of the categories overlap, you often have to choose
+ which of the categories should be the primary category of your
+ port. There are several rules that govern this usse. Here is the
+ list of priorities, in decreasing order of precedence.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Language specific categories alwasys come first. For
+ example, if your port installs Japanese X11 fonts, then your
+ <makevar>CATEGORIES</makevar> line would read
+ <literal>japanese x11</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Specific categories win over less-specific ones. For
+ instance, an HTML editor should be listed as <literal>www
+ editors</literal>, not the other way around. Also, you don't
+ need to list <literal>net</literal> when the port belongs to
+ either of <literal>mail</literal>, <literal>mbone</literal>,
+ <literal>news</literal>, <literal>security</literal>, or
+ <literal>www</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>x11</literal> is used as a secondary category
+ only when the primary category is a natural language. In
+ particular, you should not put <literal>x11</literal> in the
+ category line for X applications.</para>
+ </listitem>
+
+ <listitem>
+ <para>If your port truly does not belong anywhere else, put it
+ in <literal>misc</literal>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>If you are not sure about the category, please put a comment
+ to that effect in your <command>send-pr</command> submission so we
+ can discuss it before import it. (If you are a committer, send a
+ note &a.ports; so we can discuss it first—too often new
+ ports are imported to a wrong category only to be moved right
+ away.)</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Changes to this document and the ports system</title>
+
+ <para>If you maintain a lot of ports, you should consider following
+ the &a.ports;. Important changes to
+ the way ports work will be announced there. You can always
+ find more detailed information on the latest changes by
+ looking at <ulink
+ url="http://www.FreeBSD.ORG/cgi/cvsweb.cgi/src/share/mk/bsd.port.mk">
+ the bsd.port.mk CVS log</ulink>.</para>
+ </sect2>
+
+ <sect2>
+ <title>That is It, Folks!</title>
+
+ <para>Boy, this sure was a long tutorial, wasn't it? Thanks for
+ following us to here, really.</para>
+
+ <para>Well, now that you know how to do a port, let us go at it
+ and convert everything in the world into ports! That is the
+ easiest way to start contributing to the FreeBSD Project!
+ <!-- smiley --><emphasis>:)</emphasis></para>
+
+ </sect2>
+ </sect1>
+
</chapter>
@@ -1053,9 +4516,7 @@ grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arc
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/ppp-and-slip/chapter.sgml b/en/handbook/ppp-and-slip/chapter.sgml
index b0d244ca37..a83def5913 100644
--- a/en/handbook/ppp-and-slip/chapter.sgml
+++ b/en/handbook/ppp-and-slip/chapter.sgml
@@ -2561,9 +2561,7 @@ import proto rip interface ed {
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/printing/chapter.sgml b/en/handbook/printing/chapter.sgml
index f1937d3edf..6bbaf37a71 100644
--- a/en/handbook/printing/chapter.sgml
+++ b/en/handbook/printing/chapter.sgml
@@ -2839,13 +2839,13 @@ if [ "$first_two_chars" = "%!" ]; then
#
# PostScript job, print it.
#
- echo $first_line && cat && printf "\004" && exit 0
+ echo "$first_line" && cat && printf "\004" && exit 0
exit 2
else
#
# Plain text, convert it, then print it.
#
- ( echo $first_line; cat ) | /usr/local/bin/textps && printf "\004" && exit 0
+ ( echo "$first_line"; cat ) | /usr/local/bin/textps && printf "\004" && exit 0
exit 2
fi</programlisting>
@@ -2919,7 +2919,7 @@ else
# Plain text or HP/PCL, so just print it directly; print a form
# at the end to eject the last page.
#
- echo $first_line && cat && printf "\f" && exit 0
+ echo "$first_line" && cat && printf "\f" && exit 0
fi
exit 2</programlisting>
@@ -4912,9 +4912,7 @@ total 337.00 154 $ 6.74</screen>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/quotas/chapter.sgml b/en/handbook/quotas/chapter.sgml
index 9052bb131b..8d9c3de622 100644
--- a/en/handbook/quotas/chapter.sgml
+++ b/en/handbook/quotas/chapter.sgml
@@ -239,9 +239,7 @@ Disk quotas for user test (uid 1002):
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/security/chapter.sgml b/en/handbook/security/chapter.sgml
index b620aeb316..00fcb1dc43 100644
--- a/en/handbook/security/chapter.sgml
+++ b/en/handbook/security/chapter.sgml
@@ -1703,9 +1703,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/serialcomms/chapter.sgml b/en/handbook/serialcomms/chapter.sgml
index 59b6b828f9..c6112d3bcf 100644
--- a/en/handbook/serialcomms/chapter.sgml
+++ b/en/handbook/serialcomms/chapter.sgml
@@ -2090,9 +2090,7 @@ raisechar=^^</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/staff/chapter.sgml b/en/handbook/staff/chapter.sgml
index 350c823cb5..b34fa0411c 100644
--- a/en/handbook/staff/chapter.sgml
+++ b/en/handbook/staff/chapter.sgml
@@ -128,14 +128,6 @@
<para>&a.dburr;</para>
</listitem>
- <listitem>
- <para>&a.danny;</para>
- </listitem>
-
- <listitem>
- <para>&a.thepish;</para>
- </listitem>
-
<listitem>
<para>&a.charnier;</para>
</listitem>
@@ -155,7 +147,11 @@
<listitem>
<para>&a.gclarkii;</para>
</listitem>
-
+
+ <listitem>
+ <para>&a.archie</para>
+ </listitem>
+
<listitem>
<para>&a.cracauer;</para>
</listitem>
@@ -212,14 +208,18 @@
<para>&a.jfitz;</para>
</listitem>
- <listitem>
- <para>&a.lars;</para>
- </listitem>
-
<listitem>
<para>&a.scrappy;</para>
</listitem>
+ <listitem>
+ <para>&a.lars;</para>
+ </listitem>
+
+ <listitem>
+ <para>&a.billf;</para>
+ </listitem>
+
<listitem>
<para>&a.tg;</para>
</listitem>
@@ -247,23 +247,35 @@
<listitem>
<para>&a.hanai;</para>
</listitem>
-
+
+ <listitem>
+ <para>&a.thepish;</para>
+ </listitem>
+
<listitem>
<para>&a.jhay;</para>
</listitem>
+ <listitem>
+ <para>&a.helbig;</para>
+ </listitem>
+
<listitem>
<para>&a.ghelmer;</para>
</listitem>
- <listitem>
- <para>&a.helbig;</para>
- </listitem>
-
<listitem>
<para>&a.erich;</para>
</listitem>
+ <listitem>
+ <para>&a.nhibma;</para>
+ </listitem>
+
+ <listitem>
+ <para>&a.flathill;</para>
+ </listitem>
+
<listitem>
<para>&a.hosokawa;</para>
</listitem>
@@ -279,7 +291,11 @@
<listitem>
<para>&a.itojun;</para>
</listitem>
-
+
+ <listitem>
+ <para>&a.mjacob;</para>
+ </listitem>
+
<listitem>
<para>&a.gj;</para>
</listitem>
@@ -319,7 +335,11 @@
<listitem>
<para>&a.jlemon;</para>
</listitem>
-
+
+ <listitem>
+ <para>&a.truckman;</para>
+ </listitem>
+
<listitem>
<para>&a.imp;</para>
</listitem>
@@ -372,6 +392,10 @@
<para>&a.obrien;</para>
</listitem>
+ <listitem>
+ <para>&a.danny;</para>
+ </listitem>
+
<listitem>
<para>&a.ljo;</para>
</listitem>
@@ -391,7 +415,11 @@
<listitem>
<para>&a.jmacd;</para>
</listitem>
-
+
+ <listitem>
+ <para>&a.wes;</para>
+ </listitem>
+
<listitem>
<para>&a.steve;</para>
</listitem>
@@ -435,7 +463,11 @@
<listitem>
<para>&a.dima;</para>
</listitem>
-
+
+ <listitem>
+ <para>&a.sada;</para>
+ </listitem>
+
<listitem>
<para>&a.wosch;</para>
</listitem>
@@ -512,10 +544,6 @@
<para>&a.jmz;</para>
</listitem>
- <listitem>
- <para>&a.hosokawa;</para>
- </listitem>
-
<listitem>
<para>&a.archie;</para>
</listitem>
@@ -536,8 +564,9 @@
<variablelist>
<varlistentry><term>Documentation Project Manager</term>
- <listitem>
- <para><emphasis>currently vacant</emphasis></para>
+
+ <listitem>
+ <para>&a.nik;</para>
</listitem>
</varlistentry>
@@ -545,7 +574,7 @@
<varlistentry><term>Webmaster</term>
<listitem>
- <para>&a.wosch;;</para>
+ <para>&a.wosch;</para>
</listitem>
</varlistentry>
@@ -641,7 +670,7 @@
url="http://www.freebsd.org/docproj/docproj.html">Documentation Project Manager</ulink></term>
<listitem>
- <para><emphasis>currently vacant</emphasis></para>
+ <para>&a.nik;</para>
</listitem>
</varlistentry>
@@ -758,9 +787,7 @@
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en/handbook/x11/chapter.sgml b/en/handbook/x11/chapter.sgml
index 3d6c6c5c05..e8fb397095 100644
--- a/en/handbook/x11/chapter.sgml
+++ b/en/handbook/x11/chapter.sgml
@@ -13,9 +13,7 @@
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/articles/contributing/article.sgml b/en_US.ISO8859-1/articles/contributing/article.sgml
index c04d625c12..2dffa913a2 100644
--- a/en_US.ISO8859-1/articles/contributing/article.sgml
+++ b/en_US.ISO8859-1/articles/contributing/article.sgml
@@ -1,5 +1,4 @@
-
- <chapter id="contrib">
+<chapter id="contrib">
<title>Contributing to FreeBSD</title>
<para><emphasis>Contributed by &a.jkh;.</emphasis></para>
@@ -724,2529 +723,7 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</sect2>
- <sect2 id="porting">
- <title>Porting an existing piece of free software</title>
-
- <para><emphasis>Contributed by &a.jkh;, &a.gpalmer;, &a.asami; and
- &a.obrien;.<!-- <br> -->28 August 1996.</emphasis></para>
-
- <para>The porting of freely available software, while perhaps not as
- gratifying as developing your own from scratch, is still a vital
- part of FreeBSD's growth and of great usefulness to those who
- would not otherwise know where to turn for it. All ported
- software is organized into a carefully organized hierarchy known
- as “the ports collection”. The collection enables a new user to
- get a quick and complete overview of what is available for FreeBSD
- in an easy-to-compile form. It also saves considerable space by
- not actually containing the majority of the sources being ported,
- but merely those differences required for running under FreeBSD.</para>
-
- <para>What follows are some guidelines for creating a new port for
- FreeBSD. The bulk of the work is done by
- <filename>/usr/share/mk/bsd.port.mk</filename>, which all port
- Makefiles include. Please refer to that file for more details on
- the inner workings of the ports collection. Even if you don't
- hack Makefiles daily, it is well commented, and you will still
- gain much knowledge from it.</para>
-
-
- <sect3 id="porting-starting">
- <title>Before Starting the Port</title>
- <note>
- <para>Only a fraction of the overridable variables
- are mentioned in
- this document. Most (if not all) are documented at the start
- of <filename>bsd.port.mk</filename>. This file uses a
- non-standard tab setting. <command>Emacs</command> and
- <command>Vim</command> should recognize the setting on loading
- the file. <command>vi</command> or <command>ex</command> can
- be set to using the correct value by typing <literal>:set
- tabstop=4</literal> once the file has been loaded.</para>
- </note>
-
- <para>You may come across code that needs modifications or
- conditional compilation based upon what version of UNIX it is
- running under. If you need to make such changes to the code for
- conditional compilation, make sure you make the changes as
- general as possible so that we can back-port code to FreeBSD 1.x
- systems and cross-port to other BSD systems such as 4.4BSD from
- CSRG, BSD/386, 386BSD, NetBSD, and OpenBSD.</para>
-
- <para>The preferred way to tell 4.3BSD/Reno (1990) and newer
- versions of the BSD code apart is by using the
- <acronym>BSD</acronym> macro defined in
- <filename><sys/param.h></filename>. Hopefully that file
- is already included; if not, add the code:</para>
-
- <programlisting>
-#if (defined(__unix__) || defined(unix)) && !defined(USG)
-#include <sys/param.h>
-#endif</programlisting>
-
- <para>to the proper place in the <filename>.c</filename> file. We
- believe that every system that defines these to symbols has
- <filename>sys/param.h</filename>. If you find a system that
- doesn't, we would like to know. Please send mail to
- &a.ports;.</para>
-
- <para>Another way is to use the GNU Autoconf style of doing
- this:</para>
-
- <programlisting>
-#ifdef HAVE_SYS_PARAM_H
-#include <sys/param.h>
-#endif</programlisting>
-
- <para>Don't forget to add <literal>-DHAVE_SYS_PARAM_H</literal> to
- the <makevar>CFLAGS</makevar> in the Makefile for this
- method.</para>
-
- <para>Once you have <filename>sys/param.h</filename>
- included, you may use:</para>
-
- <programlisting>
-#if (defined(BSD) && (BSD >= 199103))</programlisting>
-
- <para>to detect if the code is being compiled on a 4.3 Net2 code
- base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD,
- BSD/386 1.1 and below).</para>
-
- <para>Use:</para>
-
- <programlisting>
-#if (defined(BSD) && (BSD >= 199306))</programlisting>
-
- <para>to detect if the code is being compiled on a 4.4 code base
- or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or
- above).</para>
-
- <para>The value of the BSD macro is 199506 for the 4.4BSD-Lite2
- code base. This is stated for informational purposes only. It
- should not be used to distinguish between version of FreeBSD
- based only on 4.4-Lite vs. versions that have merged in changes
- from 4.4-Lite2. The __FreeBSD__ macro should be used
- instead.</para>
-
- <para>Use sparingly:</para>
-
-
- <itemizedlist>
-
- <listitem>
- <para><literal>__FreeBSD__</literal> is defined in all
- versions of FreeBSD. Use it if the change you are making
- ONLY affects FreeBSD. Porting gotchas like the use of
- <literal>sys_errlist[]</literal> vs
- <function>strerror()</function> are Berkeleyisms, not
- FreeBSD changes.</para>
- </listitem>
-
- <listitem>
- <para>In FreeBSD 2.x, <literal>__FreeBSD__</literal> is
- defined to be <literal>2</literal>. In earlier
- versions, it is <literal>1</literal>. Later
- versions will bump it to match their major version number.</para>
- </listitem>
-
- <listitem>
- <para>If you need to tell the difference between a FreeBSD
- 1.x system and a FreeBSD 2.x or 3.x system, usually the
- right answer is to use the <acronym>BSD</acronym> macros
- described above. If there actually is a FreeBSD specific
- change (such as special shared library options when using
- <command>ld</command>) then it is OK to use
- <literal>__FreeBSD__</literal> and <literal>#if
- __FreeBSD__ > 1</literal> to detect a FreeBSD 2.x
- and later system. If you need more granularity in
- detecting FreeBSD systems since 2.0-RELEASE you can use
- the following:</para>
-
- <programlisting>
-#if __FreeBSD__ >= 2
-#include <osreldate.h>
-# if __FreeBSD_version >= 199504
- /* 2.0.5+ release specific code here */
-# endif
-#endif</programlisting>
-
- <informaltable frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Release</entry>
- <entry><literal>_FreeBSD_version</literal></entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>2.0-RELEASE</entry>
- <entry>119411</entry>
- </row>
-
- <row>
- <entry>2.1-currents</entry>
- <entry>199501, 199503</entry>
- </row>
-
- <row>
- <entry>2.0.5-RELEASE</entry>
- <entry>199504</entry>
- </row>
-
- <row>
- <entry>2.2-current before 2.1</entry>
- <entry>199508</entry>
- </row>
-
- <row>
- <entry>2.1.0-RELEASE</entry>
- <entry>199511</entry>
- </row>
-
- <row>
- <entry>2.2-current before 2.1.5</entry>
- <entry>199512</entry>
- </row>
-
- <row>
- <entry>2.1.5-RELEASE</entry>
- <entry>199607</entry>
- </row>
-
- <row>
- <entry>2.2-current before 2.1.6</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 (no change)</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after 2.2.1-RELEASE</entry>
- <entry>220000 (no change)</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after texinfo-3.9</entry>
- <entry>221001</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after top</entry>
- <entry>221002</entry>
- </row>
-
- <row>
- <entry>2.2.2-RELEASE</entry>
- <entry>222000</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after 2.2.2-RELEASE</entry>
- <entry>222001</entry>
- </row>
-
- <row>
- <entry>2.2.5-RELEASE</entry>
- <entry>225000</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after 2.2.5-RELEASE</entry>
- <entry>225001</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after ldconfig -R merge</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-STABLE after 2.2.7-RELEASE</entry>
- <entry>227001</entry>
- </row>
-
- <row>
- <entry>3.0-current before mount(2) change</entry>
- <entry>300000</entry>
- </row>
-
- <row>
- <entry>3.0-current as of November 1996</entry>
- <entry>300001</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </listitem>
- </itemizedlist>
-
- <note>
- <para>Note that 2.2-STABLE sometimes identifies itself as
- “2.2.5-STABLE” after the 2.2.5-RELEASE. The pattern used to
- be year followed by the month, but we decided to change it
- to a more straightforward major/minor system starting from
- 2.2. This is because the parallel development on several
- branches made it infeasible to classify the releases simply
- by their real release dates. If you are making a port now,
- you don't have to worry about old -current's; they are
- listed here just for your reference.</para>
- </note>
-
-
- <para>In the hundreds of ports that have been done, there have
- only been one or two cases where <literal>__FreeBSD__</literal>
- should have been used. Just because an earlier port screwed up
- and used it in the wrong place does not mean you should do so
- too.</para>
-
- </sect3>
-
- <sect3>
- <title>Quick Porting</title>
-
- <para>This section tells you how to do a quick port. In many
- cases, it is not enough, but we will see.</para>
-
- <para>First, get the original tarball and put it into <makevar>DISTDIR</makevar>, which defaults to
- <filename>/usr/ports/distfiles</filename>.</para>
-
- <note>
- <para>The following assumes that the software compiled
- out-of-the-box, i.e., there was absolutely no change required
- for the port to work on your FreeBSD box. If you needed to
- change something, you will have to refer to the next section
- too.</para>
- </note>
-
- <sect4>
- <title>Writing the <filename>Makefile</filename></title>
-
- <para>The minimal <filename>Makefile</filename> would
- look something like this:</para>
-
- <programlisting>
-# New ports collection makefile for: oneko
-# Version required: 1.1b
-# Date created: 5 December 1994
-# Whom: asami
-#
-# $Id$
-#
-
-DISTNAME= oneko-1.1b
-CATEGORIES= games
-MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
-
-MAINTAINER= asami@FreeBSD.ORG
-
-MAN1= oneko.1
-MANCOMPRESSED= yes
-USE_IMAKE= yes
-
-.include <bsd.port.mk></programlisting>
-
- <para>See if you can figure it out. Do not worry about the
- contents of the <literal>$Id$</literal>
- line, it will be filled in automatically by CVS when the port
- is imported to our main ports tree. You can find a more
- detailed example in the <link
- linkend="porting-samplem">sample Makefile</link>
- section.</para>
-
- </sect4>
-
- <sect4>
- <title>Writing the description files</title>
-
- <para>There are three required description files that are
- required for any port, whether they actually package or not.
- They are <filename>COMMENT</filename>,
- <filename>DESCR</filename>, and <filename>PLIST</filename>,
- and reside in the <filename>pkg</filename>
- subdirectory.</para>
-
-
- <sect5>
- <title><filename>COMMENT</filename></title>
-
- <para>This is the one-line description of the port.
- <emphasis>Please</emphasis> do not include the package name (or version
- number of the software) in the comment. Here is
- an example:</para>
-
- <programlisting>
-A cat chasing a mouse all over the screen.</programlisting>
-
- </sect5>
-
- <sect5>
- <title><filename>DESCR</filename></title>
-
- <para>This is a longer description of the port. One to a few
- paragraphs concisely explaining what the port does is
- sufficient.</para>
-
- <note>
- <para>This is <emphasis>not</emphasis> a manual or an
- in-depth description on how to use or compile the port!
- <emphasis>Please be careful if you are copying from the
- <filename>README</filename> or manpage</emphasis>; too often
- they are not a concise description of the port or are in an
- awkward format (e.g., manpages have justified spacing). If the
- ported software has an official WWW homepage, you should list
- it here.</para>
- </note>
-
- <para>It is recommended that you sign the name at the end of
- this file, as in:</para>
-
- <programlisting>
-This is a port of oneko, in which a cat chases a poor mouse all over
-the screen.
- :
-(etc.)
-
-http://www.oneko.org/
-
-- Satoshi
-asami@cs.berkeley.edu</programlisting>
-
- </sect5>
-
- <sect5>
- <title><filename>PLIST</filename></title>
-
- <para>This file lists all the files installed by the port. It
- is also called the `packing list' because the package is
- generated by packing the files listed here. The pathnames
- are relative to the installation prefix (usually
- <filename>/usr/local</filename> or
- <filename>/usr/X11R6</filename>). If you are using the
- <makevar>MAN<replaceable>n</replaceable></makevar> variables (as
- you should be), do not list any manpages here.</para>
-
- <para>Here is a small example:</para>
-
- <programlisting>
-bin/oneko
-lib/X11/app-defaults/Oneko
-lib/X11/oneko/cat1.xpm
-lib/X11/oneko/cat2.xpm
-lib/X11/oneko/mouse.xpm</programlisting>
-
- <para>Refer to the <citerefentry><refentrytitle>pkg_create</refentrytitle><manvolnum>1</manvolnum></citerefentry> man page
- for details on the packing list.</para>
-
- </sect5>
- </sect4>
-
- <sect4>
- <title>Creating the checksum file</title>
-
- <para>Just type <command>make makesum</command>.
- The ports make rules will automatically generate the file
- <filename>files/md5</filename>.</para>
-
- </sect4>
-
- <sect4>
- <title>Testing the port</title>
-
- <para>You should make sure that the port rules do exactly what
- you want it to do, including packaging up the port. Try doing
- <command>make install</command>, <command>make package</command> and then <command>make deinstall</command> and see if all the files
- and directories are correctly deleted. Then do a <command>pkg_add `make package-name`.tgz</command> and see
- if everything re-appears and works correctly. Then do another
- <command>make deinstall</command> and then
- <command>make reinstall; make package</command>
- to make sure you haven't included in the packing list any
- files that are not installed by your port.</para>
-
- </sect4>
-
- <sect4 id="porting-submitting">
- <title>Submitting the port</title>
-
- <para>First, make sure you have read the <link
- linkend="porting-dads">Do's and Dont's</link> section.</para>
-
- <para>Now that you are happy with your port, the only thing
- remaining is to put it in the main FreeBSD ports tree and make
- everybody else happy about it too. We do not need your
- <filename>work</filename> directory or the
- <filename>pkgname.tgz</filename> package, so delete them
- now. Next, simply include the output of <command>shar `find
- port_dir`</command> in a bug report and send it with the
- <citerefentry>
- <refentrytitle>send-pr</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> program. If the uncompressed port is larger than
- 20KB, you should compress it into a tarfile and use <citerefentry>
- <refentrytitle>uuencode</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> before including it in the bug report (uuencoded
- tarfiles are acceptable even if the bug report is smaller than
- 20KB but are not preferred). Be sure to classify the bug report as
- category <literal>ports</literal> and class
- <literal>change-request</literal>.</para>
-
- <para>One more time, <emphasis>do not include the original source
- distfile, the <filename>work</filename> directory, or the
- package you built with <command>make
- package</command></emphasis>.</para>
-
- <para>See <link linkend="contrib-general">Bug Reports and General
- Commentary</link> for more information.</para>
-
- <para>We will look at your port,
- get back to you if necessary, and put it in the
- tree. Your name will also appear in the list of “Additional
- FreeBSD contributors” on the FreeBSD Handbook and other files.
- Isn't that great?!? <!-- smiley -->:)</para>
-
- </sect4>
- </sect3>
-
- <sect3>
- <title>Slow Porting</title>
-
- <para>Ok, so it was not that simple, and the port required some
- modifications to get it to work. In this section, we will
- explain, step by step, how to modify it to get it to work with
- the ports paradigm.</para>
-
-
- <sect4>
- <title>How things work</title>
-
- <para>First, this is the sequence of events which occurs when
- the user first types <command>make</command> in
- your port's directory, and you may find that having
- <filename>bsd.port.mk</filename> in another window while you
- read this really helps to understand it.</para>
-
- <para>But do not worry if you do not really understand what
- <filename>bsd.port.mk</filename> is doing, not many people
- do... <!-- smiley --><emphasis>:></emphasis></para>
-
-
- <procedure>
-
- <step>
- <para>The <maketarget>fetch</maketarget> target is run. The <maketarget>fetch</maketarget> target is
- responsible for making sure that the tarball exists
- locally in <makevar>DISTDIR</makevar>.
- If <maketarget>fetch</maketarget> cannot find the required files in <makevar>DISTDIR</makevar> it will look up the
- URL <makevar>MASTER_SITES</makevar>,
- which is set in the Makefile, as well as our main ftp
- site at <ulink
- URL="ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/">ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/,</ulink> where we put sanctioned distfiles as backup. It will then attempt to fetch the named distribution file with <makevar>FETCH</makevar>, assuming that the requesting site has direct access to the Internet. If that succeeds, it will save the file in <makevar>DISTDIR</makevar> for future use and proceed.</para>
- </step>
-
- <step>
- <para>The <maketarget>extract</maketarget> target is run. It looks for your port's
- distribution file in <makevar>DISTDIR</makevar> (typically a gzip'd
- tarball) and unpacks it into a temporary subdirectory
- specified by <makevar>WRKDIR</makevar>
- (defaults to <filename>work</filename>).</para>
- </step>
-
- <step>
- <para>The <maketarget>patch</maketarget> target is run. First, any patches defined
- in <makevar>PATCHFILES</makevar> are
- applied. Second, if any patches are found in <makevar>PATCHDIR</makevar> (defaults to the
- <filename>patches</filename> subdirectory), they are
- applied at this time in alphabetical order.</para>
- </step>
-
- <step>
- <para>The <maketarget>configure</maketarget> target is run. This can do any one of
- many different things.</para>
-
- <orderedlist>
-
- <listitem>
- <para>If it exists,
- <filename>scripts/configure</filename> is run.</para>
- </listitem>
-
- <listitem>
- <para>If <makevar>HAS_CONFIGURE</makevar> or
- <makevar>GNU_CONFIGURE</makevar>
- is set,
- <filename><makevar>WRKSRC</makevar>/configure</filename> is
- run.</para>
- </listitem>
-
- <listitem>
- <para>If <makevar>USE_IMAKE</makevar> is set,
- <makevar>XMKMF</makevar>
- (default: <command>xmkmf
- -a</command>) is run.</para>
- </listitem>
-
- </orderedlist>
-
- </step>
-
- <step>
- <para>The <maketarget>build</maketarget> target is run. This is responsible for
- descending into the ports' private working directory
- (<makevar>WRKSRC</makevar>) and
- building it. If <makevar>USE_GMAKE</makevar> is set, GNU
- <command>make</command> will be used,
- otherwise the system <command>make</command>
- will be used.</para>
- </step>
-
- </procedure>
-
-
- <para>The above are the default actions. In addition, you can
- define targets <maketarget>pre-<replaceable>something</replaceable></maketarget> or <maketarget>post-<replaceable>something</replaceable></maketarget>, or put scripts
- with those names, in the <filename>scripts</filename>
- subdirectory, and they will be run before or after the default
- actions are done.</para>
-
- <para>For example, if you have a <maketarget>post-extract</maketarget> target defined in your
- Makefile, and a file <filename>pre-build</filename> in the
- <filename>scripts</filename> subdirectory, the
- <maketarget>post-extract</maketarget> target will be
- called after the regular extraction actions, and the
- <filename>pre-build</filename> script will be executed before
- the default build rules are done. It is recommended that you
- use <filename>Makefile</filename> targets if the actions are
- simple enough, because it will be easier for someone to figure
- out what kind of non-default action the port requires.</para>
-
- <para>The default actions are done by the
- <filename>bsd.port.mk</filename> targets <maketarget>do-<replaceable>something</replaceable></maketarget>. For example, the
- commands to extract a port are in the target <maketarget>do-extract</maketarget>. If you are not happy with
- the default target, you can fix it by redefining the
- <maketarget>do-<replaceable>something</replaceable></maketarget> target in
- your <filename>Makefile</filename>.</para>
-
- <note>
- <para>The “main” targets (e.g., <maketarget>extract</maketarget>, <maketarget>configure</maketarget>, etc.) do nothing more than
- make sure all the stages up to that one is completed and
- call the real targets or scripts, and they are not intended
- to be changed. If you want to fix the extraction, fix
- <maketarget>do-extract</maketarget>, but never ever
- touch <maketarget>extract</maketarget>!</para>
- </note>
-
- <para>Now that you understand what goes on when the user types
- <command>make</command>, let us go through the
- recommended steps to create the perfect port.</para>
-
- </sect4>
-
- <sect4>
- <title>Getting the original sources</title>
-
- <para>Get the original sources (normally) as a compressed
- tarball (<filename><replaceable>foo</replaceable>.tar.gz</filename> or
- <filename><replaceable>foo</replaceable>.tar.Z</filename>) and copy it into
- <makevar>DISTDIR</makevar>. Always use
- <emphasis>mainstream</emphasis> sources when and where you
- can.</para>
-
- <para>If you cannot find a ftp/http site that is well-connected
- to the net, or can only find sites that have irritatingly
- non-standard formats, you might want to put a copy on a
- reliable http or ftp server that you control. If you are a FreeBSD
- committer, your <filename>public_html</filename> directory on
- <hostid>freefall</hostid> is ideal. Make sure you set
- <makevar>MASTER_SITE</makevar> to reflect your choice. If you
- cannot find somewhere convenient and reliable to put the distfile,
- we can “house” it ourselves by putting
- it on <filename>ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/LOCAL_PORTS/</filename> as the last resort. Please refer to this
- location as <makevar>MASTER_SITE_LOCAL</makevar>. Send mail to
- the &a.ports;if you are not sure what to do.</para>
-
- <para>If your port requires some additional `patches' that are
- available on the Internet, fetch them too and put them in
- <makevar>DISTDIR</makevar>. Do not worry if
- they come from site other than where you got the main source
- tarball, we have a way to handle these situations (see the
- description of <link
- linkend="porting-patchfiles">PATCHFILES</link> below).</para>
-
- </sect4>
-
- <sect4>
- <title>Modifying the port</title>
-
- <para>Unpack a copy of the tarball in a private directory and
- make whatever changes are necessary to get the port to compile
- properly under the current version of FreeBSD. Keep
- <emphasis>careful track</emphasis> of everything you do, as
- you will be automating the process shortly. Everything,
- including the deletion, addition or modification of files
- should be doable using an automated script or patch file when
- your port is finished.</para>
-
- <para>If your port requires significant user
- interaction/customization to compile or install, you should
- take a look at one of Larry Wall's classic <application>Configure</application> scripts
- and perhaps do something similar yourself. The goal of the
- new ports collection is to make each port as “plug-and-play”
- as possible for the end-user while using a minimum of disk
- space.</para>
-
- <note>
- <para>Unless explicitly stated, patch files, scripts, and
- other files you have created and contributed to the FreeBSD
- ports collection are assumed to be covered by the standard
- BSD copyright conditions.</para>
- </note>
- </sect4>
-
- <sect4>
- <title>Patching</title>
-
- <para>In the preparation of the port, files that have been added
- or changed can be picked up with a recursive diff for later
- feeding to patch. Each set of patches you wish to apply
- should be collected into a file named
- <filename>patch-<replaceable>xx</replaceable></filename> where
- <replaceable>xx</replaceable> denotes the sequence in which
- the patches will be applied — these are done in
- <emphasis>alphabetical order</emphasis>, thus
- <literal>aa</literal> first, <literal>ab</literal> second and so on. These files
- should be stored in <makevar>PATCHDIR</makevar>, from where they will be
- automatically applied. All patches should be relative to
- <makevar>WRKSRC</makevar> (generally the
- directory your port's tarball unpacks itself into, that being
- where the build is done). To make fixes and upgrades easier
- you should avoid having more than one patch fix the same file
- (e.g., patch-aa and patch-ab both changing <makevar>WRKSRC</makevar>/foobar.c).</para>
-
- </sect4>
-
- <sect4>
- <title>Configuring</title>
-
- <para>Include any additional customization commands to your
- <filename>configure</filename> script and save it in the
- <filename>scripts</filename> subdirectory. As mentioned
- above, you can also do this as <filename>Makefile</filename>
- targets and/or scripts with the name
- <filename>pre-configure</filename> or
- <filename>post-configure</filename>.</para>
-
- </sect4>
-
- <sect4>
- <title>Handling user input</title>
-
- <para>If your port requires user input to build, configure or
- install, then set <makevar>IS_INTERACTIVE</makevar> in your
- Makefile. This will allow “overnight builds” to skip your port
- if the user sets the variable <envar>BATCH</envar> in his
- environment (and if the user sets the variable
- <envar>INTERACTIVE</envar>, then <emphasis>only</emphasis>
- those ports requiring interaction are built).</para>
-
- </sect4>
- </sect3>
-
- <sect3>
- <title>Configuring the Makefile</title>
-
- <para>Configuring the Makefile is pretty simple, and again we
- suggest that you look at existing examples before starting.
- Also, there is a <link linkend="porting-samplem">sample
- Makefile</link> in this handbook, so take a look and please follow
- the ordering of variables and sections in that template to make
- your port easier for others to read.</para>
-
- <para>Now, consider the following problems in sequence as you
- design your new Makefile:</para>
-
-
- <sect4>
- <title>The original source</title>
-
- <para>Does it live in <makevar>DISTDIR</makevar> as a standard gzip'd
- tarball? If so, you can go on to the next step. If not, you
- should look at overriding any of the <makevar>EXTRACT_CMD</makevar>, <makevar>EXTRACT_BEFORE_ARGS</makevar>, <makevar>EXTRACT_AFTER_ARGS</makevar>, <makevar>EXTRACT_SUFX</makevar>, or <makevar>DISTFILES</makevar> variables, depending on
- how alien a format your port's distribution file is. (The
- most common case is <literal>EXTRACT_SUFX=.tar.Z</literal>,
- when the tarball is condensed by regular compress, not
- gzip.)</para>
-
- <para>In the worst case, you can simply create your own
- <maketarget>do-extract</maketarget> target to override
- the default, though this should be rarely, if ever,
- necessary.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>DISTNAME</makevar></title>
-
- <para>You should set <makevar>DISTNAME</makevar> to be the base name of
- your port. The default rules expect the distribution file
- list (<makevar>DISTFILES</makevar>) to be
- named <makevar>DISTNAME</makevar><makevar>EXTRACT_SUFX</makevar> by
- default which, if it is a normal tarball, is going to be
- something like <literal>foozolix-1.0.tar.gz</literal> for a setting of
- <programlisting>
-DISTNAME=foozolix-1.0</programlisting>.</para>
-
- <para>The default rules also expect the tarball(s) to extract
- into a subdirectory called
- <filename>work/<makevar>DISTNAME</makevar></filename>, e.g. <filename>work/foozolix-1.0/</filename>.</para>
-
- <para>All this behavior can be overridden, of course; it simply
- represents the most common time-saving defaults. For a port
- requiring multiple distribution files, simply set <makevar>DISTFILES</makevar> explicitly. If only a
- subset of <makevar>DISTFILES</makevar> are
- actual extractable archives, then set them up in <makevar>EXTRACT_ONLY</makevar>, which will override
- the <makevar>DISTFILES</makevar> list when
- it comes to extraction, and the rest will be just left in
- <makevar>DISTDIR</makevar> for later
- use.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>CATEGORIES</makevar></title>
-
- <para>When a package is created, it is put under
- <filename>/usr/ports/packages/All</filename> and links are
- made from one or more subdirectories of
- <filename>/usr/ports/packages</filename>. The names of these
- subdirectories are specified by the variable <makevar>CATEGORIES</makevar>. It is intended to
- make life easier for the user when he is wading through the
- pile of packages on the ftp site or the CD-ROM. Please take a
- look at the existing categories (you can find them in <ulink
- URL="http://www.freebsd.org/ports/">the ports
- page</ulink>) and pick the ones that are suitable for your
- port. If your port truly belongs to something that is
- different from all the existing ones, you can even create a
- new category name.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>MASTER_SITES</makevar></title>
-
- <para>Record the directory part of the ftp/http-URL pointing at
- the original tarball in <makevar>MASTER_SITES</makevar>. Do not forget the
- trailing slash (<filename>/</filename>)!</para>
-
- <para>The <command>make</command> macros will try to use this specification for
- grabbing the distribution file with <makevar>FETCH</makevar> if they cannot find it
- already on the system.</para>
-
- <para>It is recommended that you put multiple sites on this
- list, preferably from different continents. This will
- safeguard against wide-area network problems, and we are even
- planning to add support for automatically determining the
- closest master site and fetching from there!</para>
-
- <para>If the original tarball is part of one of the following
- popular archives: X-contrib, GNU, Perl CPAN, TeX CTAN, or
- Linux Sunsite, you refer to those sites in an easy compact
- form using <makevar>MASTER_SITE_XCONTRIB</makevar>, <makevar>MASTER_SITE_GNU</makevar>,
- <makevar>MASTER_SITE_PERL_CPAN</makevar>, <makevar>MASTER_SITE_TEX_CTAN</makevar>, and
- <makevar>MASTER_SITE_SUNSITE</makevar>. Simply set <makevar>MASTER_SITE_SUBDIR</makevar> to the
- path with in the archive. Here is an example:</para>
-
- <programlisting>
-MASTER_SITES= ${MASTER_SITE_XCONTRIB}
-MASTER_SITE_SUBDIR= applications</programlisting>
-
- <para>The user can also set the <makevar>MASTER_SITE_*</makevar> variables in
- <filename>/etc/make.conf</filename> to override our choices,
- and use their favorite mirrors of these popular archives
- instead.</para>
-
- </sect4>
-
- <sect4 id="porting-patchfiles">
- <title><makevar>PATCHFILES</makevar></title>
-
- <para>If your port requires some additional patches that are
- available by ftp or http, set <makevar>PATCHFILES</makevar> to the names of the
- files and <makevar>PATCH_SITES</makevar> to
- the URL of the directory that contains them (the format is the
- same as <makevar>MASTER_SITES</makevar>).</para>
-
- <para>If the patch is not relative to the top of the source tree
- (i.e., <makevar>WKRSRC</makevar>) because it
- contains some extra pathnames, set <makevar>PATCH_DIST_STRIP</makevar> accordingly.
- For instance, if all the pathnames in the patch has an extra
- <literal>foozolix-1.0/</literal> in front of the
- filenames, then set
- <literal>PATCH_DIST_STRIP=-p1</literal>.</para>
-
- <para>Do not worry if the patches are compressed, they will be
- decompressed automatically if the filenames end with
- <filename>.gz</filename> or
- <filename>.Z</filename>.</para>
-
- <para>If the patch is distributed with some other files, such as
- documentation, in a gzip'd tarball, you can't just use
- <makevar>PATCHFILES</makevar>. If that is
- the case, add the name and the location of the patch tarball
- to <makevar>DISTFILES</makevar> and
- <makevar>MASTER_SITES</makevar>. Then, from
- the <maketarget>pre-patch</maketarget> target, apply the
- patch either by running the patch command from there, or
- copying the patch file into the <makevar>PATCHDIR</makevar> directory and calling it
- <filename>patch-<replaceable>xx</replaceable></filename>.</para>
-
- <note>
- <para>Note the tarball will have been extracted alongside the
- regular source by then, so there is no need to explicitly
- extract it if it is a regular gzip'd or compress'd tarball.
- If you do the latter, take extra care not to overwrite
- something that already exists in that directory. Also do
- not forget to add a command to remove the copied patch in
- the <maketarget>pre-clean</maketarget> target.</para>
- </note>
-
- </sect4>
-
- <sect4>
- <title><makevar>MAINTAINER</makevar></title>
-
- <para>Set your mail-address here. Please. <!-- smiley --><emphasis>:)</emphasis></para>
-
- <para>For detailed description of the responsibility of
- maintainers, refer to <link
- linkend="policies-maintainer">MAINTAINER
- on Makefiles</link> section.</para>
-
- </sect4>
-
- <sect4>
- <title>Dependencies</title>
-
- <para>Many ports depend on other ports. There are five
- variables that you can use to ensure that all the required
- bits will be on the user's machine.</para>
-
-
- <sect5>
- <title><makevar>LIB_DEPENDS</makevar></title>
-
- <para>This variable specifies the shared libraries this port
- depends on. It is a list of <replaceable>lib</replaceable>:<replaceable>dir</replaceable> pairs where
- <replaceable>lib</replaceable> is the name of the shared library,
- and <replaceable>dir</replaceable> is the directory in which to
- find it in case it is not available. For example,
-
- <programlisting>
-LIB_DEPENDS= jpeg\\.6\\.:${PORTSDIR}/graphics/jpeg</programlisting>
-
- will check for a shared jpeg library with
- major version 6, and descend into the
- <filename>graphics/jpeg</filename> subdirectory of your
- ports tree to build and install it if it is not
- found.</para>
-
- <note>
- <para>The <replaceable>lib</replaceable> part is just an argument
- given to <command>ldconfig -r | grep</command>, so
- periods should be escaped by two backslashes like in the
- example above.</para>
- </note>
-
- <para>The dependency is checked from within the <maketarget>extract</maketarget> target. Also, the name of the
- dependency is put in to the package so that
- <command>pkg_add</command> will automatically install it if it
- is not on the user's system.</para>
-
- </sect5>
-
- <sect5>
- <title><makevar>RUN_DEPENDS</makevar></title>
-
- <para>This variable specifies executables or files this port
- depends on during run-time. It is a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable> pairs where
- <replaceable>path</replaceable> is the name of the executable or
- file, and <replaceable>dir</replaceable> is the directory in which
- to find it in case it is not available. If
- <replaceable>path</replaceable> starts with a slash
- (<literal>/</literal>), it is treated as a file and its
- existence is tested with <command>test -e</command>;
- otherwise, it is assumed to be an executable, and
- <command>which -s</command> is used to determine if the
- program exists in the user's search path.</para>
-
- <para>For example,
-
- <programlisting>
-RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \
- wish:${PORTSDIR}/x11/tk</programlisting>
-
- will check if the file
- <filename>/usr/local/etc/innd</filename> exists, and build
- and install it from the <filename>news/inn</filename>
- subdirectory of the ports tree if it is not found. It will
- also see if an executable called <command>wish</command> is in your search path, and
- descend into the <filename>x11/tk</filename> subdirectory of
- your ports tree to build and install it if it is not
- found.</para>
-
- <note>
- <para>In this case, <command>innd</command> is actually an
- executable; if an executable is in a place that is not
- expected to be in a normal user's search path, you should
- use the full pathname.</para>
- </note>
-
- <para>The dependency is checked from within the <maketarget>install</maketarget> target. Also, the name of the
- dependency is put in to the package so that
- <command>pkg_add</command> will automatically install it if it
- is not on the user's system.</para>
-
- </sect5>
-
- <sect5>
- <title><makevar>BUILD_DEPENDS</makevar></title>
-
- <para>This variable specifies executables or files this port
- requires to build. Like <makevar>RUN_DEPENDS</makevar>, it is
- a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable> pairs.
- For example,
-
- <programlisting>
-BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>
-
- will check for an executable called
- <command>unzip</command>, and descend into the
- <filename>archivers/unzip</filename> subdirectory of your
- ports tree to build and install it if it is not
- found.</para>
-
- <note>
- <para>“build” here means everything from extracting to
- compilation. The dependency is checked from within the
- <maketarget>extract</maketarget> target.</para>
- </note>
- </sect5>
-
- <sect5>
- <title><makevar>FETCH_DEPENDS</makevar></title>
-
- <para>This variable specifies executables or files this port
- requires to fetch. Like the previous two, it is a list of
- <replaceable>path</replaceable>:<replaceable>dir</replaceable> pairs. For
- example,
-
- <programlisting>
-FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting>
-
- will check for an executable called
- <command>ncftp2</command>, and descend into the
- <filename>net/ncftp2</filename> subdirectory of your ports
- tree to build and install it if it is not found.</para>
-
- <para>The dependency is checked from within the <maketarget>fetch</maketarget> target.</para>
-
- </sect5>
-
- <sect5>
- <title><makevar>DEPENDS</makevar></title>
-
- <para>If there is a dependency that does not fall into either
- of the above four categories, or your port requires to have
- the source of the other port extracted (i.e., having them
- installed is not enough), then use this variable. This is
- just a list of directories, as there is nothing to check,
- unlike the previous four.</para>
-
- </sect5>
- </sect4>
-
- <sect4>
- <title>Building mechanisms</title>
-
- <para>If your package uses GNU <command>make</command>, set
- <literal>USE_GMAKE=yes</literal>. If your package uses GNU
- <command>configure</command>, set
- <literal>GNU_CONFIGURE=yes</literal>. If you want to give
- some extra arguments to GNU <command>configure</command> (other than the default
- <literal>--prefix=${PREFIX}</literal>), set those extra
- arguments in <makevar>CONFIGURE_ARGS</makevar>.</para>
-
- <para>If your package is an X application that creates
- <filename>Makefile</filename>s from
- <filename>Imakefile</filename>s using <command>imake</command>, then set
- <literal>USE_IMAKE=yes</literal>. This will cause the
- configure stage to automatically do an <command>xmkmf
- -a</command>. If the <option>-a</option> flag is a
- problem for your port, set
- <literal>XMKMF=xmkmf</literal>.</para>
-
- <para>If your port's source <filename>Makefile</filename> has
- something else than <maketarget>all</maketarget> as the
- main build target, set <makevar>ALL_TARGET</makevar> accordingly. Same
- goes for <maketarget>install</maketarget> and <makevar>INSTALL_TARGET</makevar>.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>NO_INSTALL_MANPAGES</makevar></title>
-
- <para>If the port uses <command>imake</command> but does not understand the
- <filename>install.man</filename> target,
- <literal>NO_INSTALL_MANPAGES=yes</literal> should be set.
- In addition, the author of the original port should be shot.
- <!-- smiley --><emphasis>:></emphasis></para>
-
- </sect4>
- </sect3>
-
- <sect3>
- <title>Ports that require Motif</title>
-
- <para>There are many programs that require a Motif library
- (available from several commercial vendors, while there is (at
- least) one effort to create a free clone) to compile. Since it
- is a popular toolkit and their licenses usually permit
- redistribution of statically linked binaries, we have made
- special provisions for handling ports that require Motif in a
- way that we can easily compile binaries linked either
- dynamically or statically.</para>
-
-
- <sect4>
- <title><makevar>REQUIRES_MOTIF</makevar></title>
-
- <para>If your port requires Motif, define this variable in the
- Makefile. This will prevent people who don't own a copy of
- Motif from even attempting to build it.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>MOTIFLIB</makevar></title>
-
- <para>This variable will be set by
- <filename>bsd.port.mk</filename> to be the appropriate
- reference to the Motif library. Please patch the source to
- use this wherever the Motif library is referenced in the
- Makefile or Imakefile.</para>
-
- <para>There are two common cases:</para>
-
- <orderedlist>
-
- <listitem>
- <para>If the port refers to the Motif library as
- <option>-lXm</option> in its Makefile or Imakefile,
- simply substitute <makevar>MOTIFLIB</makevar> for it.</para>
- </listitem>
-
- <listitem>
- <para>If the port uses <literal>XmClientLibs</literal> in its Imakefile,
- change it to <literal>${MOTIFLIB}
- ${XTOOLLIB} ${XLIB}</literal>.</para>
- </listitem>
-
- </orderedlist>
-
- <note>
- <para><makevar>MOTIFLIB</makevar> (usually)
- expands to <literal>-L/usr/X11R6/lib -lXm</literal> or
- <literal>/usr/X11R6/lib/libXm.a</literal>, so there is
- no need to add <option>-L</option> or
- <option>-l</option> in front.</para>
- </note>
- </sect4>
- </sect3>
-
- <sect3>
- <title>ELF support</title>
-
- <para>Since FreeBSD is moving to ELF from 3.0-release onwards,
- 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 that there will
- be one more release (2.2.8) from the 2.2 branch. 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 awhile for reference
- in case you have come across some old port you wish to
- upgrade.</para>
-
- <sect4>
- <title>Moving a.out libraries out of the way</title>
-
- <para>A.out libraries should be moved out of
- <filename>/usr/local/lib</filename> and similar to an
- <filename>aout</filename> subdirectory. (If you don't move them
- out of the way, ELF ports will happily overwrite a.out libraries.)
- The <maketarget>move-aout-libs</maketarget> target in the -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>
- </sect4>
-
- <sect4>
- <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>
- </sect4>
-
- <sect4>
- <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's always going to be
- <literal>aout</literal> in -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>
- </sect4>
-
- <sect4>
- <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 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>PLIST</filename> too, and it won't 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>
- </sect4>
-
- <sect4>
- <title><makevar>LIB_DEPENDS</makevar></title>
-
- <para>All port Makefiles 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>
- </sect4>
-
- <sect4>
- <title><filename>PLIST</filename></title>
-
- <para><filename>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>PLIST</filename> mentioned in the previous
- paragraph.</para>
- </sect4>
-
- <sect4>
- <title><literal>ldconfig</literal></title>
-
- <para>The <literal>ldconfig/ line in Makefiles should read:</literal></para>
-
- <programlisting>
-${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....</programlisting>
-
- <para>In <filename>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>
- </sect4>
- </sect3>
-
- <sect3>
- <title>Info files</title>
-
- <para>The new version of texinfo (included in 2.2.2-RELEASE and
- onwards) contains a utility called <command>install-info</command> to add and delete entries to
- the <filename>dir</filename> file. If your port installs any
- info documents, please follow these instructions so your
- port/package will correctly update the user's
- <filename>${PREFIX}/info/dir</filename> file. (Sorry for
- the length of this section, but it is imperative to weave all
- the info files together. If done correctly, it will produce a
- <emphasis>beautiful</emphasis> listing, so please bear with me!
- <!-- smiley --><emphasis>:)</emphasis></para>
-
- <para>First, this is what you (as a porter) need to know:</para>
-
- <informalexample>
- <screen>&prompt.user; <userinput>install-info --help</userinput>
-install-info [OPTION]... [INFO-FILE [DIR-FILE]]
- Install INFO-FILE in the Info directory file DIR-FILE.
-
-Options:
---delete Delete existing entries in INFO-FILE;
- don't insert any new entries.
- :
---entry=TEXT Insert TEXT as an Info directory entry.
- :
---section=SEC Put this file's entries in section SEC of the directory. :</screen>
- </informalexample>
-
- <note>
- <para>This program will not actually
- <emphasis>install</emphasis> info files; it merely inserts or
- deletes entries in the <filename>dir</filename> file.</para>
- </note>
-
- <para>Here's a seven-step procedure to convert ports to use
- <command>install-info</command>. I will use
- <filename>editors/emacs</filename> as an example.</para>
-
- <procedure>
- <step>
- <para>Look at the texinfo sources and make a patch to insert
- <literal>@dircategory</literal> and <literal>@direntry</literal>
- statements to files that don't have them. This is part of
- my patch:</para>
-
- <programlisting>
---- ./man/vip.texi.org Fri Jun 16 15:31:11 1995
-+++ ./man/vip.texi Tue May 20 01:28:33 1997
-@@ -2,6 +2,10 @@
-
- @setfilename ../info/vip
- @settitle VIP
-+@dircategory The Emacs editor and associated tools
-+@direntry
-+* VIP: (vip). A VI-emulation for Emacs.
-+@end direntry
-
- @iftex
- @finalout
- :</programlisting>
-
- <para>The format should be self-explanatory. Many authors
- leave a <filename>dir</filename> file in the source tree
- that contains all the entries you need, so look around
- before you try to write your own. Also, make sure you
- look into related ports and make the section names and
- entry indentations consistent (we recommend that all entry
- text start at the 4th tab stop).</para>
-
- <note>
- <para>Note that you can put only one info entry per file
- because of a bug in <command>install-info
- --delete</command> that deletes only the first entry
- if you specify multiple entries in the
- <email>@direntry</email> section.</para>
- </note>
-
- <para>You can give the <literal>dir</literal>
- entries to <command>install-info</command> as
- arguments (<option>--section</option> and
- <option>--entry</option>) instead of patching the texinfo
- sources. I do not think this is a good idea for ports
- because you need to duplicate the same information in
- <emphasis>three</emphasis> places
- (<filename>Makefile</filename> and
- <literal>@exec</literal>/<literal>@unexec</literal> of
- <filename>PLIST</filename>; see below). However, if you
- have a Japanese (or other multibyte encoding) info files,
- you will have to use the extra arguments to <command>install-info</command> because <command>makeinfo</command> can't handle those texinfo
- sources. (See <filename>Makefile</filename> and
- <filename>PLIST</filename> of
- <filename>japanese/skk</filename> for examples on how to
- do this).</para>
- </step>
-
- <step>
- <para>Go back to the port directory and do a <command>make clean; make</command> and verify that
- the info files are regenerated from the texinfo sources.
- Since the texinfo sources are newer than the info files,
- they should be rebuilt when you type <command>make</command>; but many
- <filename>Makefile</filename>s don't include correct
- dependencies for info files. In <command>emacs</command>' case, I had to
- patch the main <filename>Makefile.in</filename> so it will
- descend into the <filename>man</filename>
- subdirectory to rebuild the info pages.</para>
-
- <programlisting>
---- ./Makefile.in.org Mon Aug 19 21:12:19 1996
-+++ ./Makefile.in Tue Apr 15 00:15:28 1997
-@@ -184,7 +184,7 @@
- # Subdirectories to make recursively. `lisp' is not included
- # because the compiled lisp files are part of the distribution
- # and you cannot remake them without installing Emacs first.
--SUBDIR = lib-src src
-+SUBDIR = lib-src src man
-
- # The makefiles of the directories in $SUBDIR.
- SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile lwlib/Makefile
---- ./man/Makefile.in.org Thu Jun 27 15:27:19 1996
-+++ ./man/Makefile.in Tue Apr 15 00:29:52 1997
-@@ -66,6 +66,7 @@
- ${srcdir}/gnu1.texi \
- ${srcdir}/glossary.texi
-
-+all: info
- info: $(INFO_TARGETS)
-
- dvi: $(DVI_TARGETS)</programlisting>
-
- <para>The second hunk was necessary because the default
- target in the <filename>man</filename> subdir is called
- <maketarget>info</maketarget>, while the main
- <filename>Makefile</filename> wants to call <maketarget>all</maketarget>. I also deleted the installation
- of the <filename>info</filename> info file
- because we already have one with the same name in
- <filename>/usr/share/info</filename> (that patch is not
- shown here).</para>
- </step>
-
- <step>
- <para>If there is a place in the
- <filename>Makefile</filename> that is installing the
- <filename>dir</filename> file, delete it. Your
- port may not be doing it. Also, remove any commands that
- are otherwise mucking around with the
- <filename>dir</filename> file.</para>
-
- <programlisting>
---- ./Makefile.in.org Mon Aug 19 21:12:19 1996
-+++ ./Makefile.in Mon Apr 14 23:38:07 1997
-@@ -368,14 +368,8 @@
- if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \
- then \
- (cd ${infodir}; \
-- if [ -f dir ]; then \
-- if [ ! -f dir.old ]; then mv -f dir dir.old; \
-- else mv -f dir dir.bak; fi; \
-- fi; \
- cd ${srcdir}/info ; \
-- (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir); \
-- (cd $${thisdir}; chmod a+r ${infodir}/dir); \
- for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \
- (cd $${thisdir}; \
- ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \
- chmod a+r ${infodir}/$$f); \</programlisting>
- </step>
-
- <step>
- <para>(This step is only necessary if you are modifying an
- existing port.) Take a look at
- <filename>pkg/PLIST</filename> and delete anything that is
- trying to patch up <filename>info/dir</filename>. They
- may be in <filename>pkg/INSTALL</filename> or some other
- file, so search extensively.</para>
-
- <programlisting>
-Index: pkg/PLIST
-===================================================================
-RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v
-retrieving revision 1.15
-diff -u -r1.15 PLIST
---- PLIST 1997/03/04 08:04:00 1.15
-+++ PLIST 1997/04/15 06:32:12
-@@ -15,9 +15,6 @@
- man/man1/emacs.1.gz
- man/man1/etags.1.gz
- man/man1/ctags.1.gz
--@unexec cp %D/info/dir %D/info/dir.bak
--info/dir
--@unexec cp %D/info/dir.bak %D/info/dir
- info/cl
- info/cl-1
- info/cl-2</programlisting>
- </step>
-
- <step>
- <para>Add a <maketarget>post-install</maketarget>
- target to the <filename>Makefile</filename> to create a
- <filename>dir</filename> file if it is not there. Also,
- call <maketarget>install-info</maketarget> with the
- installed info files.</para>
-
- <programlisting>
-Index: Makefile
-===================================================================
-RCS file: /usr/cvs/ports/editors/emacs/Makefile,v
-retrieving revision 1.26
-diff -u -r1.26 Makefile
---- Makefile 1996/11/19 13:14:40 1.26
-+++ Makefile 1997/05/20 10:25:09 1.28
-@@ -20,5 +20,11 @@
- post-install:
- .for file in emacs-19.34 emacsclient etags ctags b2m
- strip ${PREFIX}/bin/${file}
- .endfor
-+ if [ ! -f ${PREFIX}/info/dir ]; then \
-+ ${SED} -ne '1,/Menu:/p' /usr/share/info/dir > ${PREFIX}/info/dir; \
-+ fi
-+.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode
-+ install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir
-+.endfor
-
- .include <bsd.port.mk></programlisting>
-
- <para>Do not use anything other than
- <filename>/usr/share/info/dir</filename> and the above
- command to create a new info file. In fact, I'd add the
- first three lines of the above patch to
- <filename>bsd.port.mk</filename> if you (the porter)
- wouldn't have to do it in <filename>PLIST</filename> by
- yourself anyway.</para>
- </step>
-
- <step>
- <para>Edit <filename>PLIST</filename> and add equivalent
- <literal>@exec</literal> statements and also
- <literal>@unexec</literal> for <command>pkg_delete</command>.
- You do not need to delete <filename>info/dir</filename>
- with <literal>@unexec</literal>.</para>
-
- <programlisting>
-Index: pkg/PLIST
-===================================================================
-RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v
-retrieving revision 1.15
-diff -u -r1.15 PLIST
---- PLIST 1997/03/04 08:04:00 1.15
-+++ PLIST 1997/05/20 10:25:12 1.17
-@@ -16,7 +14,15 @@
- man/man1/etags.1.gz
- man/man1/ctags.1.gz
-+@unexec install-info --delete %D/info/emacs %D/info/dir
- :
-+@unexec install-info --delete %D/info/ccmode %D/info/dir
- info/cl
- info/cl-1
-@@ -87,6 +94,18 @@
- info/viper-3
- info/viper-4
-+@exec [ -f %D/info/dir ] || sed -ne '1,/Menu:/p' /usr/share/info/dir > %D/info/dir
-+@exec install-info %D/info/emacs %D/info/dir
- :
-+@exec install-info %D/info/ccmode %D/info/dir
- libexec/emacs/19.34/i386--freebsd/cvtmail
- libexec/emacs/19.34/i386--freebsd/digest-doc</programlisting>
-
- <note>
- <para>The <literal>@unexec install-info
- --delete</literal> commands have to be listed before
- the info files themselves so they can read the files.
- Also, the <literal>@exec install-info</literal> commands
- have to be after the info files and the
- <literal>@exec</literal> command that creates the the
- <filename>dir</filename> file.</para>
- </note>
- </step>
-
- <step>
- <para>Test and admire your work. <!-- smiley --><emphasis>:)</emphasis> The sequence I recommend is:
- <command>make package</command>,
- <command>pkg_delete</command>, then
- <command>pkg_add</command>. Check the <filename>dir</filename> file before and after each
- step.</para>
- </step>
-
- </procedure>
-
-
- </sect3>
-
- <sect3>
- <title>Changing the <filename>PLIST</filename> based on <citerefentry>
- <refentrytitle>make</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> variables</title>
-
- <para>Some ports, particularly the <filename>p5-</filename> ports,
- need to change their <filename>PLIST</filename> depending on what
- options they are configured with (or version of perl, in the case of
- <filename>p5-</filename> ports). To make this easy, any instances in
- the <filename>PLIST</filename> of <literal>%%OSREL%%</literal>,
- <literal>%%PERL_VER%%</literal>, and
- <literal>%%PERL_VERSION%%</literal> will be substituted for
- appropriately. If you need to make other substitutions, you can set
- the <makevar>PLIST_SUB</makevar> variable with a list of
- <literal><replaceable>VAR</replaceable>=<replaceable>VALUE</replaceable></literal> pairs and instances of <literal>%%<replaceable>VAR</replaceable>%%</literal> will be substituted with <replaceable>VALUE</replaceable> in the <filename>PLIST</filename>.</para>
- </sect3>
-
- <sect3>
- <title>Licensing Problems</title>
-
- <para>Some software packages have restrictive licenses or can be
- in violation to the law (PKP's patent on public key crypto, ITAR
- (export of crypto software) to name just two of them). What we
- can do with them vary a lot, depending on the exact wordings of
- the respective licenses.</para>
-
- <note>
- <para>It is your responsibility as a porter to read the
- licensing terms of the software and make sure that the FreeBSD
- project will not be held accountable of violating them by
- redistributing the source or compiled binaries either via ftp
- or CD-ROM. If in doubt, please contact the &a.ports;.</para>
- </note>
-
- <para>There are two variables you can set in the Makefile to
- handle the situations that arise frequently:</para>
-
-
- <orderedlist>
-
- <listitem>
- <para>If the port has a “do not sell for profit” type of
- license, set the variable <makevar>NO_CDROM</makevar>. We
- will make sure such ports won't go into the CD-ROM come
- release time. The distfile and package will still be
- available via ftp.</para>
- </listitem>
-
- <listitem>
- <para>If the resulting package needs to be built uniquely
- for each site, or the resulting binary package can't be
- distributed due to licensing; set the variable
- <makevar>NO_PACKAGE</makevar>. We will make sure such
- packages won't go on the ftp site, nor into the CD-ROM
- come release time. The distfile will still be included on
- both however.</para>
- </listitem>
-
- <listitem>
- <para>If the port has legal restrictions on who can use it
- (e.g., crypto stuff) or has a “no commercial use” license,
- set the variable <makevar>RESTRICTED</makevar> to be the
- string describing the reason why. For such ports, the
- distfiles/packages will not be available even from our ftp
- sites.</para>
- </listitem>
-
- </orderedlist>
-
-
- <note>
- <para>The GNU General Public License (GPL), both version 1
- and 2, should not be a problem for ports.</para>
- </note>
-
- <note>
- <para>If you are a committer, make sure you update the
- <filename>ports/LEGAL</filename> file too.</para>
- </note>
- </sect3>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>When you notice that a port is out of date compared to the
- latest version from the original authors, first make sure you
- have the latest port. You can find them in the
- <filename>ports-current</filename> directory of the ftp mirror
- sites.</para>
-
- <para>The next step is to send a mail to the maintainer, if one is
- listed in the port's <filename>Makefile</filename>. That person may already be
- working on an upgrade, or have a reason to not upgrade the port
- right now (because of, for example, stability problems of the
- new version).</para>
-
- <para>If the maintainer asks you to do the upgrade or there isn't
- any such person to begin with, please make the upgrade and send
- the recursive diff (either unified or context diff is fine, but
- port committers appear to prefer unified diff more) of the new
- and old ports directories to us (e.g., if your modified port
- directory is called <filename>superedit</filename>
- and the original as in our tree is
- <filename>superedit.bak</filename>, then send us the result of
- <command>diff -ruN superedit.bak
- superedit</command>). Please examine the output to make
- sure all the changes make sense. The best way to send us the
- diff is by including it to <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- (category <literal>ports</literal>). Please mention any added or deleted files
- in the message, as they have to be explicitly specified to CVS
- when doing a commit. If the diff is more than about 20KB, please
- compress and uuencode it; otherwise, just include it in as is in
- the PR.</para>
-
- </sect3>
-
- <sect3>
- <title><anchor id="porting-dads">Do's and Dont's</title>
-
- <para>Here is a list of common do's and dont's that you encounter
- during the porting process.You should check your own port
- against this list, but you can also check ports in the PR
- database that others have submitted. Submit any comments on
- ports you check as described in <link linkend="contrib-general">Bug
- Reports and General Commentary</link>. Checking ports in
- the PR database will both make it faster for us to commit them,
- and prove that you know what you are doing.</para>
-
-
- <sect4>
- <title><makevar>WRKDIR</makevar></title>
-
- <para>Do not leave anything valuable lying around in the
- <filename>work</filename> subdirectory, <command>make clean</command> will
- <emphasis>nuke</emphasis> it completely! If you need
- auxiliary files that are not scripts or patches, put them in
- the <makevar>FILESDIR</makevar> subdirectory
- (<filename>files</filename> by default) and use the
- <maketarget>post-extract</maketarget> target to copy them
- to the <filename>work</filename> subdirectory.</para>
-
- </sect4>
-
- <sect4>
- <title>Portlint Clean</title>
-
- <para>Do use <command>portlint</command>! The <ulink
- url="http://www.freebsd.org/cgi/ports.cgi?portlint">portlint</ulink> program is part of the ports collection.</para>
- </sect4>
-
- <sect4>
- <title>Strip Binaries</title>
-
- <para>Do strip binaries. If the original source already strips the
- binaries, fine; otherwise you should add a
- <literal>post-install</literal> rule to to it yourself. Here is an
- example;</para>
-
- <programlisting>
-post-install:
- strip ${PREFIX}/bin/xdl</programlisting>
-
- <para>Use the <citerefentry>
- <refentrytitle>file</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> command on the installed executable to check
- whether the binary is stripped or not. If it does not say
- <literal>not stripped</literal>, it is stripped.</para>
- </sect4>
-
- <sect4>
- <title>Correctly Install Manpages</title>
-
- <para>Do use the <makevar>MAN<replaceable>n</replaceable></makevar>
- variables. These variables, will automatically add any manpages
- to <filename>pkg/PLIST</filename> (this means you must
- <emphasis>not</emphasis> list manpages in the
- <filename>PLIST</filename>) and automatically compress manpages
- (unless <makevar>NOMANCOMPRESS</makevar> is set in
- <filename>/etc/make.conf</filename>). If your port installs
- pre-compressed manpages, you must define the
- <makevar>MANCOMPRESSED</makevar> variable.</para>
-
- <programlisting>
-MAN1= foo.1 bar.1
-MAN5= foo.conf.5
-MAN8= baz.8</programlisting>
-
- <note>
- <para>This is not usually necessary with ports that are X
- applications and use <command>Imake</command> to build.</para>
- </note>
-
- <para>If your port anchors its man tree somewhere other than
- <makevar>PREFIX</makevar>, you can use the
- <makevar>MANPREFIX</makevar> to set it. Also, if only manpages in
- certain section go in a non-standard place, such as many Perl
- modules ports, you can set individual man paths using
- <makevar>MAN<replaceable>sect</replaceable>PREFIX</makevar> (where
- <replaceable>sect</replaceable> is one of <literal>1-9</literal>,
- <literal>L</literal> or <literal>N</literal>).</para>
- </sect4>
-
- <sect4>
- <title>INSTALL_* macros</title>
-
- <para>Do use the macros provided in <filename>bsd.port.mk</filename>
- to ensure correct modes and ownership of files in your own
- <maketarget>*-install</maketarget> targets. They are:</para>
-
- <itemizedlist>
- <listitem>
- <para><makevar>INSTALL_PROGRAM</makevar> is a command to install
- binary executables.</para>
- </listitem>
-
- <listitem>
- <para><makevar>INSTALL_SCRIPT</makevar> is a command to install
- executable scripts.</para>
- </listitem>
-
- <listitem>
- <para><makevar>INSTALL_DATA</makevar> is a command to install
- sharable data.</para>
- </listitem>
-
- <listitem>
- <para><makevar>INSTALL_MAN</makevar> is a command to install
- manpages and other documentation (it doesn't compress
- anything).</para>
- </listitem>
- </itemizedlist>
-
- <para>These are basically the <command>install</command> command
- with all the appropriate flags. See below for an example on how
- to use them.</para>
- </sect4>
-
- <sect4>
- <title><filename>INSTALL</filename> package script</title>
-
- <para>If your port needs execute commands when the binary package is
- installed with pkg_add you can do with via the
- <filename>pkg/INSTALL</filename> script. This script will
- automatically be added to the package, and will be run twice by
- <command>pkg_add</command>. The first time will as
- <command>INSTALL ${PKGNAME} PRE-INSTALL</command> and the second
- time as <command>INSTALL ${PKGNAME} POST-INSTALL</command>.
- <literal>$2</literal> can be tested to determine which mode
- the script is being run in.</para>
-
- <para>The <envar>PKG_PREFIX</envar> environmental variable will be
- set to the package installation directory. See <citerefentry>
- <refentrytitle>pkg_add</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> for additional information.</para>
-
- <note>
- <para>This script is not run automatically if you install the port
- with <command>make install</command>. If you are depending on it
- being run, you will have to explicitly call it on your port's
- <filename>Makefile</filename>.</para>
- </note>
- </sect4>
-
- <sect4>
- <title><filename>REQ</filename> package script</title>
-
- <para>If your port needs to determine if it should install or
- not, you can create a <filename>pkg/REQ</filename>
- “requirements” script. It will be invoked automatically at
- installation/deinstallation time to determine whether or not
- installation/deinstallation should proceed. See man
- <citerefentry><refentrytitle>pkg_create</refentrytitle><manvolnum>1</manvolnum></citerefentry> and man
- <citerefentry><refentrytitle>pkg_add</refentrytitle><manvolnum>1</manvolnum></citerefentry> for more information.</para>
-
- </sect4>
-
- <sect4>
- <title>Install additional documentation</title>
-
- <para>If your software has some documentation other than the
- standard man and info pages that you think is useful for the
- user, install it under
- <filename><makevar>PREFIX</makevar>/share/doc</filename>. This can be
- done, like the previous item, in the <maketarget>post-install</maketarget> target.</para>
-
- <para>Create a new directory for your port. The directory name
- should reflect what the port is. This usually means <makevar>PKGNAME</makevar> minus the version part.
- However, if you think the user might want different versions
- of the port to be installed at the same time, you can use the
- whole <makevar>PKGNAME</makevar>.</para>
-
- <para>Make the installation dependent to the variable
- <makevar>NOPORTDOCS</makevar> so that users can disable it in
- <filename>/etc/make.conf</filename>, like this:</para>
-
- <programlisting>
-post-install:
-.if !defined(NOPORTDOCS)
- ${MKDIR}${PREFIX}/share/doc/xv
- ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
-.endif</programlisting>
-
- <para>Do not forget to add them to
- <filename>pkg/PLIST</filename> too! (Do not worry about
- <makevar>NOPORTDOCS</makevar> here; there is currently no way
- for the packages to read variables from
- <filename>/etc/make.conf</filename>.)</para>
-
- <para>If you need to display a message to the installer, you may
- place the message in <filename>pkg/MESSAGE</filename>. This
- capibility is often useful to display additional installation
- steps to be taken after a pkg_add, or to display licensing
- information.</para>
-
- <note>
- <para><filename>MESSAGE</filename> does not need to be added
- to <filename>pkg/PLIST</filename>).</para>
- </note>
- </sect4>
-
- <sect4>
- <title><makevar>DIST_SUBDIR</makevar></title>
-
- <para>Do not let your port clutter
- <filename>/usr/ports/distfiles</filename>. If your port
- requires a lot of files to be fetched, or contains a file that
- has a name that might conflict with other ports (e.g.,
- <filename>Makefile</filename>), set <makevar>DIST_SUBDIR</makevar> to the name of the
- port (<makevar>PKGNAME</makevar> without the
- version part should work fine). This will change <makevar>DISTDIR</makevar> from the default
- <filename>/usr/ports/distfiles</filename> to
- <filename>/usr/ports/distfiles/<makevar>DIST_SUBDIR</makevar></filename>,
- and in effect puts everything that is required for your port
- into that subdirectory.</para>
-
- <para>It will also look at the subdirectory with the same name
- on the backup master site at
- <filename>ftp.freebsd.org</filename>. (Setting <makevar>DISTDIR</makevar> explicitly in your
- <makevar>Makefile</makevar> will not accomplish this, so please use <makevar>DIST_SUBDIR</makevar>.)</para>
-
- <note>
- <para>This does not affect the <makevar>MASTER_SITES</makevar> you define in your
- Makefile.</para>
- </note>
- </sect4>
-
- <sect4>
- <title>Package information</title>
-
- <para>Do include package information, i.e.
- <filename>COMMENT</filename>, <filename>DESCR</filename>, and
- <filename>PLIST</filename>, in <filename>pkg</filename>.</para>
-
- <note>
- <para>Note that these files are not used only for packaging
- anymore, and are <emphasis>mandatory</emphasis> now, even if
- <makevar>NO_PACKAGE</makevar> is
- set.</para>
- </note>
- </sect4>
-
- <sect4>
- <title>Feedback</title>
-
- <para>Do send applicable changes/patches to the original
- author/maintainer for inclusion in next release of the code.
- This will only make your job that much easier for the next
- release.</para>
-
- </sect4>
-
- <sect4>
- <title>RCS strings</title>
-
- <para>Do not put RCS strings in patches. CVS will mangle them
- when we put the files into the ports tree, and when we check
- them out again, they will come out different and the patch
- will fail. RCS strings are surrounded by dollar (<literal>$</literal>) signs, and typically start with
- <literal>$Id</literal> or <literal>$RCS</literal>.</para>
-
- </sect4>
-
- <sect4>
- <title>Recursive diff</title>
-
- <para>Using the recurse (<option>-r</option>) option to
- <command>diff</command> to generate patches is
- fine, but please take a look at the resulting patches to make
- sure you don't have any unnecessary junk in there. In
- particular, diffs between two backup files, <filename>Makefiles</filename> when the
- port uses <command>Imake</command> or GNU <command>configure</command>, etc., are unnecessary and
- should be deleted. Also, if you had to delete a file, then you
- can do it in the <maketarget>post-extract</maketarget>
- target rather than as part of the patch. Once you are happy
- with the resulting diff, please split it up into one source
- file per patch file.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>PREFIX</makevar></title>
-
- <para>Do try to make your port install relative to <makevar>PREFIX</makevar>. (The value of this
- variable will be set to <makevar>LOCALBASE</makevar> (default
- <filename>/usr/local</filename>), unless <makevar>USE_X_PREFIX</makevar> or <makevar>USE_IMAKE</makevar> is set, in which case it
- will be <makevar>X11BASE</makevar> (default
- <filename>/usr/X11R6</filename>).)</para>
-
- <para>Not hard-coding <filename>/usr/local</filename> or
- <filename>/usr/X11R6</filename> anywhere in the source will
- make the port much more flexible and able to cater to the
- needs of other sites. For X ports that use <command>imake</command>, this is
- automatic; otherwise, this can often be done by simply
- replacing the occurrences of <filename>/usr/local</filename>
- (or <filename>/usr/X11R6</filename> for X ports that do not
- use imake) in the various scripts/Makefiles in the port to
- read <makevar>PREFIX</makevar>, as this
- variable is automatically passed down to every stage of the
- build and install processes.</para>
-
- <para>Do not set <makevar>USE_X_PREFIX</makevar> unless your port
- truly require it (i.e., it links against X libs or it needs to
- reference files in <makevar>X11BASE</makevar>.</para>
-
- <para>The variable <makevar>PREFIX</makevar>
- can be reassigned in your <filename>Makefile</filename> or in the user's
- environment. However, it is strongly discouraged for
- individual ports to set this variable explicitly in the
- <filename>Makefiles</filename>.</para>
-
- <para>Also, refer to programs/files from other ports with the
- variables mentioned above, not explicit pathnames. For
- instance, if your port requires a macro
- <literal>PAGER</literal> to be the full pathname of <command>less</command>, use the compiler flag:
-
- <programlisting>
--DPAGER=\"${PREFIX}/bin/less\"</programlisting>
-
- or
-
- <programlisting>
--DPAGER=\"${LOCALBASE}/bin/less\"</programlisting>
-
- if this is an X port, instead of <literal>-DPAGER=\"/usr/local/bin/less\".</literal> This way it will have a better chance of working if the system administrator has moved the whole `/usr/local' tree somewhere else.</para>
-
- </sect4>
-
- <sect4>
- <title>Subdirectories</title>
-
- <para>Try to let the port put things in the right subdirectories
- of <makevar>PREFIX</makevar>. Some ports
- lump everything and put it in the subdirectory with the port's
- name, which is incorrect. Also, many ports put everything
- except binaries, header files and manual pages in the a
- subdirectory of <filename>lib</filename>, which does not
- bode well with the BSD paradigm. Many of the files should be
- moved to one of the following: <filename>etc</filename>
- (setup/configuration files), <filename>libexec</filename>
- (executables started internally), <filename>sbin</filename>
- (executables for superusers/managers),
- <filename>info</filename> (documentation for info browser)
- or <filename>share</filename> (architecture independent
- files). See man <citerefentry><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
- details, the rule governing <filename>/usr</filename> pretty
- much applies to <filename>/usr/local</filename> too. The
- exception are ports dealing with USENET “news”. They may use
- <filename><makevar>PREFIX</makevar>/news</filename> as a destination for
- their files.</para>
-
- </sect4>
-
- <sect4>
- <title>ldconfig</title>
-
- <para>If your port installs a shared library, add a <maketarget>post-install</maketarget> target to your Makefile
- that runs <command>/sbin/ldconfig -m</command> on
- the directory where the new library is installed (usually
- <filename><makevar>PREFIX</makevar>/lib</filename>) to register it into
- the shared library cache.</para>
-
- <para>Also, add an <literal>@exec</literal> line to your
- <filename>pkg/PLIST</filename> file so that a user who
- installed the package can start using the shared library
- immediately. This line should immediately follow the line
- for the shared library itself, as in:</para>
-
- <programlisting>
-lib/libtcl80.so.1.0
-@exec /sbin/ldconfig -m %D/lib</programlisting>
-
- <para>Never, ever, <emphasis>ever</emphasis> add a line that
- says <command>ldconfig</command> without any
- arguments to your <filename>Makefile</filename> or <filename>pkg/PLIST</filename>. This will reset the
- shared library cache to the contents of
- <filename>/usr/lib</filename> only, and will royally screw up
- the user's machine (“Help, xinit does not run anymore after I
- install this port!”). Anybody who does this will be shot and
- cut into 65,536 pieces by a rusty knife and have his liver
- chopped out by a bunch of crows and will eternally rot to
- death in the deepest bowels of hell (not necessarily in that
- order)....</para>
-
- </sect4>
-
- <sect4>
- <title>UIDs</title>
-
- <para>If your port requires a certain user to be on the
- installed system, let the <filename>pkg/INSTALL</filename>
- script call <command>pw</command> to create it
- automatically. Look at <filename>net/cvsup-mirror</filename>
- for an example.</para>
-
- <para>If your port must use the same user/group ID number when it is
- installed a binarypackage as when it was compiled, then you mus
- choose a free UID from 50 to 99 and register it below. Look at
- <filename>japanese/Wnn</filename> for an example.</para>
-
- <para>Make sure you don't use a UID already used by the system
- or other ports. This is the current list of UIDs between 50
- and 99.</para>
-
- <programlisting>
-majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent
-cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent
-gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh
-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:/nonexistent
-wnn:*:69:7:Wnn:/nonexistent:/nonexistent
-ifmail:*:70:66:Ifmail user:/nonexistent:/nonexistent
-pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh
-ircd:*:72:72:IRCd hybrid:/nonexistent:/nonexistent
-alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent
-qmaill:*:83:81:QMail user:/var/qmail:/nonexistent
-qmaild:*:82:81:QMail user:/var/qmail:/nonexistent
-qmailq:*:85:82:QMail user:/var/qmail:/nonexistent
-qmails:*:87:82:QMail user:/var/qmail:/nonexistent
-qmailp:*:84:81:QMail user:/var/qmail:/nonexistent
-qmailr:*:86:82:QMail user:/var/qmail:/nonexistent
-msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh</programlisting>
-
- <para>Please include a notice when you submit a port (or an
- upgrade) that reserves a new UID or GID in this range. This allows
- us to keep the list of reserved IDs up to date.</para>
-
- </sect4>
-
- <sect4>
- <title>Doing things rationally</title>
-
- <para>The <filename>Makefile</filename> should do things simply and
- reasonably. If you can make it a couple of lines shorter or more
- readable, then do so. Examples include using a make
- <literal>.if</literal> construct instead of a shell
- <literal>if</literal> construct, not redefining
- <maketarget>do-extract</maketarget> if you can redefine
- <makevar>EXTRACT*</makevar> instead, and using
- <makevar>GNU_CONFIGURE</makevar> instead of
- <literal>CONFIGURE_ARGS +=
- --prefix=${PREFIX}</literal>.</para>
- </sect4>
-
- <sect4>
- <title>Respect <makevar>CFLAGS</makevar></title>
-
- <para>The port should respect the <makevar>CFLAGS</makevar>
- variable. If it doesn't, please add <literal>NO_PACKAGE=ignores
- cflags</literal> to the <filename>Makefile</filename>.</para>
- </sect4>
-
- <sect4>
- <title>Miscellanea</title>
-
- <para>The files <filename>pkg/DESCR</filename>,
- <filename>pkg/COMMENT</filename>, and
- <filename>pkg/PLIST</filename> should each be double-checked. If
- you are reviewing a port and feel they can be worded better, do
- so.</para>
-
- <para>Don't copy more copies of the GNU General Public License into
- our system, please.</para>
-
- <para>Please be careful to note any legal issues! Don't let us
- illegally distribute software!</para>
- </sect4>
-
- <sect4>
- <title>If you are stuck....</title>
-
- <para>Do look at existing examples and the
- <filename>bsd.port.mk</filename> file before asking us
- questions! <!-- smiley --><emphasis>;)</emphasis></para>
-
- <para>Do ask us questions if you have any trouble! Do not just
- beat your head against a wall! <!-- smiley --><emphasis>:)</emphasis></para>
-
- </sect4>
- </sect3>
-
- <sect3 id="porting-samplem">
- <title>A Sample <filename>Makefile</filename></title>
-
- <para>Here is a sample <filename>Makefile</filename> that you can
- use to create a new port. Make sure you remove all the extra
- comments (ones between brackets)!</para>
-
- <para>It is recommended that you follow this format (ordering of
- variables, empty lines between sections, etc.). Not all of the
- existing <filename>Makefile</filename>s are in this format
- (mostly old ones), but we are trying to uniformize how they
- look. This format is designed so that the most important
- information is easy to locate.</para>
-
- <programlisting>
-[the header...just to make it easier for us to identify the ports.]
-# New ports collection makefile for: xdvi
-[the version required header should updated when upgrading a port.]
-# Version required: pl18 [things like "1.5alpha" are fine here too]
-[this is the date when the first version of this Makefile was created.
-Never change this when doing an update of the port.]
-# Date created: 26 May 1995
-[this is the person who did the original port to FreeBSD, in particular, the
-person who wrote the first version of this Makefile. Remember, this should
-not be changed when upgrading the port later.]
-# Whom: Satoshi Asami <asami@FreeBSD.ORG>
-#
-# $Id$
-[ ^^^^ This will be automatically replaced with RCS ID string by CVS
-when it is committed to our repository.]
-#
-
-[section to describe the port itself and the master site - DISTNAME
- is always first, followed by PKGNAME (if necessary), CATEGORIES,
- and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR.
- After those, one of EXTRACT_SUFX or DISTFILES can be specified too.]
-DISTNAME= xdvi
-PKGNAME= xdvi-pl18
-CATEGORIES= print
-[do not forget the trailing slash ("/")!
- if you aren't using MASTER_SITE_* macros]
-MASTER_SITES= ${MASTER_SITE_XCONTRIB}
-MASTER_SITE_SUBDIR= applications
-[set this if the source is not in the standard ".tar.gz" form]
-EXTRACT_SUFX= .tar.Z
-
-[section for distributed patches -- can be empty]
-PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/
-PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz
-
-[maintainer; *mandatory*! This is the person (preferably with commit
- privileges) who a user can contact for questions and bug reports - this
- person should be the porter or someone who can forward questions to the
- original porter reasonably promptly. If you really do not want to have
- your address here, set it to "ports@FreeBSD.ORG".]
-MAINTAINER= asami@FreeBSD.ORG
-
-[dependencies -- can be empty]
-RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript
-LIB_DEPENDS= Xpm\\.4\\.:${PORTSDIR}/graphics/xpm
-
-[this section is for other standard bsd.port.mk variables that do not
- belong to any of the above]
-[If it asks questions during configure, build, install...]
-IS_INTERACTIVE= yes
-[If it extracts to a directory other than ${DISTNAME}...]
-WRKSRC= ${WRKDIR}/xdvi-new
-[If the distributed patches were not made relative to ${WRKSRC}, you
- may need to tweak this]
-PATCH_DIST_STRIP= -p1
-[If it requires a "configure" script generated by GNU autoconf to be run]
-GNU_CONFIGURE= yes
-[If it requires GNU make, not /usr/bin/make, to build...]
-USE_GMAKE= yes
-[If it is an X application and requires "xmkmf -a" to be run...]
-USE_IMAKE= yes
-[et cetera.]
-
-[non-standard variables to be used in the rules below]
-MY_FAVORITE_RESPONSE= "yeah, right"
-
-[then the special rules, in the order they are called]
-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
-
-[and then the epilogue]
-.include <bsd.port.mk></programlisting>
-
- </sect3>
-
- <sect3>
- <title>Package Names</title>
-
- <para>The following are the conventions you should follow in
- naming your packages. This is to have our package directory
- easy to scan, as there are already lots and lots of packages and
- users are going to turn away if they hurt their eyes!</para>
-
- <para>The package name should look like <filename><replaceable>language-</replaceable>name<replaceable>-compiled.specifics</replaceable><replaceable>-version.numbers</replaceable></filename>.</para>
-
- <para>If your <makevar>DISTNAME</makevar>
- doesn't look like that, set <makevar>PKGNAME</makevar> to something in that
- format.</para>
-
-
- <orderedlist>
-
- <listitem>
- <para>FreeBSD strives to support the native language of its
- users. The <replaceable>language-</replaceable> part should be a two letter
- abbreviation of the natural language defined by ISO-639 if
- the port is specific to a certain language. Examples are
- <literal>ja</literal> for Japanese, <literal>ru</literal> for Russian, <literal>vi</literal> for Vietnamese,
- <literal>zh</literal> for Chinese, <literal>ko</literal> for Korean and <literal>de</literal> for German.</para>
- </listitem>
-
- <listitem>
- <para>The <filename>name</filename> part
- should be all lowercases, except for a really large
- package (with lots of programs in it). Things like
- XFree86 (yes there really is a package of it, check it
- out) and ImageMagick fall into this category. Otherwise,
- convert the name (or at least the first letter) to
- lowercase. If the capital letters are
- important to the name (for example, with one-letter names
- like <literal>R</literal> or <literal>V</literal>) you may use capital letters at your discretion.
- There is a tradition of naming Perl 5 modules by prepending
- <literal>p5-</literal> and converting the double-colon separator to a hyphen;
- for example, the <literal>Data::Dumper</literal> module becomes
- <literal>p5-Data-Dumper</literal>. If the software in question has numbers,
- hyphens, or underscores in its name, you may include them as
- well (like <literal>kinput2</literal>).</para>
- </listitem>
-
- <listitem>
- <para>If the port can be built with different hardcoded
- defaults (usually specified as environment variables or on
- the <command>make</command> command line), the
- <replaceable>-compiled.specifics</replaceable> part should state the
- compiled-in defaults (the hyphen is optional). Examples
- are papersize and font units.</para>
- </listitem>
-
- <listitem>
- <para>The version string should be a period-separated list
- of integers and single lowercase alphabetics. The only
- exception is the string <literal>pl</literal> (meaning `patchlevel'), which
- can be used <emphasis>only</emphasis> when there are no
- major and minor version numbers in the software.</para>
- </listitem>
-
- </orderedlist>
-
-
- <para>Here are some (real) examples on how to convert a <makevar>DISTNAME</makevar> into a suitable <makevar>PKGNAME</makevar>:</para>
-
- <informaltable frame="none">
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Distribution Name</entry>
- <entry>Package Name</entry>
- <entry>Reason</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>mule-2.2.2.</entry>
- <entry>mule-2.2.2</entry>
- <entry>No changes required</entry>
- </row>
-
- <row>
- <entry>XFree86-3.1.2</entry>
- <entry>XFree86-3.1.2</entry>
- <entry>No changes required</entry>
- </row>
-
- <row>
- <entry>EmiClock-1.0.2</entry>
- <entry>emiclock-1.0.2</entry>
- <entry>No uppercase names for single programs</entry>
- </row>
-
- <row>
- <entry>gmod1.4</entry>
- <entry>gmod-1.4</entry>
- <entry>Need a hyphen before version numbers</entry>
- </row>
-
- <row>
- <entry>xmris.4.0.2</entry>
- <entry>xmris-4.0.2</entry>
- <entry>Need a hyphen before version numbers</entry>
- </row>
-
- <row>
- <entry>rdist-1.3alpha</entry>
- <entry>rdist-1.3a</entry>
- <entry>No strings like <literal>alpha</literal>
- allowed</entry>
- </row>
-
- <row>
- <entry>es-0.9-beta1</entry>
- <entry>es-0.9b1</entry>
- <entry>No strings like <literal>beta</literal>
- allowed</entry>
- </row>
-
- <row>
- <entry>v3.3beta021.src</entry>
- <entry>tiff-3.3</entry>
- <entry>What the heck was that anyway?</entry>
- </row>
-
- <row>
- <entry>tvtwm</entry>
- <entry>tvtwm-pl11</entry>
- <entry>Version string always required</entry>
- </row>
-
- <row>
- <entry>piewm</entry>
- <entry>piewm-1.0</entry>
- <entry>Version string always required</entry>
- </row>
-
- <row>
- <entry>xvgr-2.10pl1</entry>
- <entry>xvgr-2.10.1</entry>
- <entry><literal>pl</literal> allowed only when no
- major/minor version numbers</entry>
- </row>
-
- <row>
- <entry>gawk-2.15.6</entry>
- <entry>ja-gawk-2.15.6</entry>
- <entry>Japanese language version</entry>
- </row>
-
- <row>
- <entry>psutils-1.13</entry>
- <entry>psutils-letter-1.13</entry>
- <entry>Papersize hardcoded at package build time</entry>
- </row>
-
- <row>
- <entry>pkfonts</entry>
- <entry>pkfonts300-1.0</entry>
- <entry>Package for 300dpi fonts</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>If there is absolutely no trace of version information in
- the original source and it is unlikely that the original author
- will ever release another version, just set the version string
- to <literal>1.0</literal> (like the piewm example above). Otherwise, ask the
- original author or use the date string (<literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>) as the
- version.</para>
-
- </sect3>
-
- <sect3>
- <title>Changes to this document and the ports system</title>
-
- <para>If you maintain a lot of ports, you should consider following
- the <email>ports@FreeBSD.ORG</email> mailing-list. Important changes to
- the way ports work will be announced there. You can always
- find more detailed information on the latest changes by
- looking at <ulink
- url="http://www.FreeBSD.ORG/cgi/cvsweb.cgi/src/share/mk/bsd.port.mk">
- the bsd.port.mk CVS log</ulink>.</para>
- </sect3>
-
- <sect3>
- <title>That is It, Folks!</title>
-
- <para>Boy, this sure was a long tutorial, wasn't it? Thanks for
- following us to here, really.</para>
-
- <para>Well, now that you know how to do a port, let us go at it
- and convert everything in the world into ports! That is the
- easiest way to start contributing to the FreeBSD Project!
- <!-- smiley --><emphasis>:)</emphasis></para>
-
- </sect3>
- </sect2>
-
<sect2>
<title>Money, Hardware or Internet access</title>
@@ -3763,18 +1240,14 @@ box can be opened)</para>
<para>Ari Suutari <email>ari@suutari.iki.fi</email></para>
</listitem>
- <listitem>
- <para>Brent J. Nordquist <email>bjn@visi.com</email></para>
- </listitem>
-
+ <listitem>
+ <para>Ben Hutchinson <email>benhutch@xfiles.org.uk</email></para>
+ </listitem>
+
<listitem>
<para>Bernd Rosauer <email>br@schiele-ct.de</email></para>
</listitem>
- <listitem>
- <para>Bill Fumerola <email>billf@jade.chc-chimes.com</email></para>
- </listitem>
-
<listitem>
<para>Bill Kish <email>kish@osf.org</email></para>
</listitem>
@@ -3899,7 +1372,11 @@ box can be opened)</para>
<listitem>
<para>Chuck Hein <email>chein@cisco.com</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Clive Lin <email>clive@CiRX.ORG</email></para>
+ </listitem>
+
<listitem>
<para>Conrad Sabatier <email>conrads@neosoft.com</email></para>
</listitem>
@@ -4102,6 +1579,10 @@ box can be opened)</para>
<email>ginga@amalthea.phys.s.u-tokyo.ac.jp</email></para>
</listitem>
+ <listitem>
+ <para>Glenn Johnson <email>gljohns@bellsouth.net</email></para>
+ </listitem>
+
<listitem>
<para>Greg Ungerer <email>gerg@stallion.oz.au</email></para>
</listitem>
@@ -4141,7 +1622,11 @@ box can be opened)</para>
<listitem>
<para>Hironori Ikura <email>hikura@kaisei.org</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Hiroyuki NAKAJI <email>nakaji@zeisei3.dpri.kyoto-u.ac.jp</email></para>
+ </listitem>
+
<listitem>
<para>Holger Veit <email>Holger.Veit@gmd.de</email></para>
</listitem>
@@ -4182,10 +1667,6 @@ box can be opened)</para>
<para>Ishii Masahiro</para>
</listitem>
- <listitem>
- <para>Issei Suzuki <email>issei@t-cnet.or.jp</email></para>
- </listitem>
-
<listitem>
<para>Iseei Suzuki <email>issei@jp.FreeBSD.ORG</email></para>
</listitem>
@@ -4242,6 +1723,10 @@ box can be opened)</para>
<para>Jeffrey Wheat <email>jeff@cetlink.net</email></para>
</listitem>
+ <listitem>
+ <para>Jeremy Lea <email>reg@shale.csir.co.za</email></para>
+ </listitem>
+
<listitem>
<para>Jerry Hicks <email>jhicks@glenatl.glenayre.com</email></para>
</listitem>
@@ -4686,7 +2171,11 @@ box can be opened)</para>
<listitem>
<para>Randall Hopper <email>rhh@stealth.ct.picker.com</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Ricardas Cepas <email>rch@richard.eu.org</email></para>
+ </listitem>
+
<listitem>
<para>Richard Hwang <email>rhwang@bigpanda.com</email></para>
</listitem>
@@ -4739,10 +2228,6 @@ box can be opened)</para>
<para>Ruslan Shevchenko <email>rssh@cki.ipri.kiev.ua</email></para>
</listitem>
- <listitem>
- <para>SADA Kenji <email>sada@e-mail.ne.jp</email></para>
- </listitem>
-
<listitem>
<para>SURANYI Peter <email>suranyip@jks.is.tsukuba.ac.jp</email></para>
</listitem>
@@ -4986,7 +2471,11 @@ box can be opened)</para>
<listitem>
<para>Yen-Shuo Su <email>yssu@CCCA.NCTU.edu.tw</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Ying-Chieh Liao <email>ijliao@csie.NCTU.edu.tw</email></para>
+ </listitem>
+
<listitem>
<para>Yoshiaki Uchikawa <email>yoshiaki@kt.rim.or.jp</email></para>
</listitem>
@@ -4998,7 +2487,11 @@ box can be opened)</para>
<listitem>
<para>Yukihiro Nakai <email>nakai@technologist.com</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Yusuke Nawano <email>azuki@azkey.org</email></para>
+ </listitem>
+
<listitem>
<para>Yuval Yarom <email>yval@cs.huji.ac.il</email></para>
</listitem>
@@ -5133,7 +2626,7 @@ box can be opened)</para>
</listitem>
<listitem>
- <para>Guido van Rooij <email>guido@gvr.win.tue.nl</email></para>
+ <para>Guido van Rooij <email>guido@gvr.org</email></para>
</listitem>
<listitem>
@@ -5216,7 +2709,11 @@ box can be opened)</para>
<listitem>
<para>Julian Stacey <email>jhs@freebsd.org</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Karl Dietz <email>Karl.Dietz@triplan.com</email></para>
+ </listitem>
+
<listitem>
<para>Karl Lehenbauer <email>karl@NeoSoft.com</email> <email>karl@one.neosoft.com</email></para>
</listitem>
@@ -5391,9 +2888,7 @@ box can be opened)</para>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
index f4d06bba3a..796252e1d3 100644
--- a/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml
@@ -660,9 +660,7 @@ text_addr = 0xf5109020? (y or n) <userinput>y</userinput>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml
index cd77ca0ba2..500b2b1d46 100644
--- a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml
@@ -301,9 +301,7 @@ obrien@freebsd.org - 30 March 1997</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
index 4fbe1987b1..4f00275b26 100644
--- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
@@ -976,9 +976,7 @@ ISDN BRI line</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/authors.ent b/en_US.ISO8859-1/books/handbook/authors.ent
index a8c95c2ac6..80e0daca31 100644
--- a/en_US.ISO8859-1/books/handbook/authors.ent
+++ b/en_US.ISO8859-1/books/handbook/authors.ent
@@ -7,7 +7,7 @@
Please keep this list in alphabetical order by entity names.
- $Id: authors.ent,v 1.3 1998-11-12 01:26:17 nik Exp $
+ $Id: authors.ent,v 1.4 1998-12-10 20:43:39 nik Exp $
-->
<!ENTITY a.abial "Andrzej Bialecki <email>abial@FreeBSD.ORG</email>">
@@ -30,10 +30,12 @@
<!ENTITY a.awebster "Andrew Webster <email>awebster@pubnix.net</email>">
-<!ENTITY a.brandon "Brandon Gillespie <email>brandon@FreeBSD.ORG</email>">
-
<!ENTITY a.bde "Bruce Evans <email>bde@FreeBSD.ORG</email>">
+<!ENTITY a.billf "Bill Fumerola <email>billf@FreeBSD.ORG</email>">
+
+<!ENTITY a.brandon "Brandon Gillespie <email>brandon@FreeBSD.ORG</email>">
+
<!ENTITY a.brian "Brian Somers <email>brian@FreeBSD.ORG</email>">
<!ENTITY a.cawimm "Charles A. Wimmer <email>cawimm@FreeBSD.ORG</email>">
@@ -88,6 +90,8 @@
<!ENTITY a.fenner "Bill Fenner <email>fenner@FreeBSD.ORG</email>">
+<!ENTITY a.flathill "Seiichirou Hiraoka <email>flathill@FreeBSD.ORG</email>">
+
<!ENTITY a.fsmp "Steve Passe <email>fsmp@FreeBSD.ORG</email>">
<!ENTITY a.gclarkii "Gary Clark II <email>gclarkii@FreeBSD.ORG</email>">
@@ -98,6 +102,8 @@
<!ENTITY a.gibbs "Justin T. Gibbs <email>gibbs@FreeBSD.ORG</email>">
+<!ENTITY a.mjacob "Matthew Jacob <email>mjacob@FreeBSD.ORG</email>">
+
<!ENTITY a.gj "Gary Jennejohn <email>gj@FreeBSD.ORG</email>">
<!ENTITY a.gpalmer "Gary Palmer <email>gpalmer@FreeBSD.ORG</email>">
@@ -218,6 +224,8 @@
<!ENTITY a.nectar "Jacques Vidrine <email>nectar@FreeBSD.ORG</email>">
+<!ENTITY a.nhibma "Nick Hibma <email>n_hibma@FreeBSD.ORG</email>">
+
<!ENTITY a.nik "Nik Clayton <email>nik@FreeBSD.ORG</email>">
<!ENTITY a.nsj "Nate Johnson <email>nsj@FreeBSD.ORG</email>">
@@ -258,6 +266,8 @@
<!ENTITY a.rse "Ralf S. Engelschall <email>rse@FreeBSD.ORG</email>">
+<!ENTITY a.sada "Kenji SADA <email>sada@FreeBSD.ORG</email>">
+
<!ENTITY a.scrappy "Marc G. Fournier <email>scrappy@FreeBSD.ORG</email>">
<!ENTITY a.se "Stefan Esser <email>se@FreeBSD.ORG</email>">
@@ -288,6 +298,8 @@
<!ENTITY a.torstenb "Torsten Blum <email>torstenb@FreeBSD.ORG</email>">
+<!ENTITY a.truckman "Don “Truck” Lewis <email>truckman@FreeBSD.ORG</email>">
+
<!ENTITY a.ugen "Ugen J.S.Antsilevich <email>ugen@FreeBSD.ORG</email>">
<!ENTITY a.uhclem "Frank Durda IV <email>uhclem@FreeBSD.ORG</email>">
@@ -296,6 +308,8 @@
<!ENTITY a.vanilla "Vanilla I. Shu <email>vanilla@FreeBSD.ORG</email>">
+<!ENTITY a.wes "Wes Peters <email>wes@FreeBSD.ORG</email>">
+
<!ENTITY a.whiteside "Don Whiteside <email>whiteside@acm.org</email>">
<!ENTITY a.wilko "Wilko Bulte <email>wilko@yedi.iaf.nl</email>">
diff --git a/en_US.ISO8859-1/books/handbook/basics/chapter.sgml b/en_US.ISO8859-1/books/handbook/basics/chapter.sgml
index 574ee8a3f7..761f1146f4 100644
--- a/en_US.ISO8859-1/books/handbook/basics/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/basics/chapter.sgml
@@ -141,9 +141,7 @@
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/bibliography/chapter.sgml b/en_US.ISO8859-1/books/handbook/bibliography/chapter.sgml
index 429b519caf..a549e0ca67 100644
--- a/en_US.ISO8859-1/books/handbook/bibliography/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/bibliography/chapter.sgml
@@ -499,9 +499,7 @@ url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/book.sgml b/en_US.ISO8859-1/books/handbook/book.sgml
index 78ff7e72ca..a4c9c067df 100644
--- a/en_US.ISO8859-1/books/handbook/book.sgml
+++ b/en_US.ISO8859-1/books/handbook/book.sgml
@@ -3,7 +3,10 @@
<!ENTITY % authors SYSTEM "authors.ent"> %authors;
<!ENTITY % mailing-lists SYSTEM "mailing-lists.ent"> %mailing-lists;
-<!ENTITY rel.current CDATA "3.0">
+<!-- The currently released version of FreeBSD. This value is used to
+ create some links on web sites and such, so do NOT change it until
+ it's really release time -->
+<!ENTITY rel.current CDATA "2.2.8">
]>
<book>
@@ -103,8 +106,6 @@ url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/docs/">FreeBSD FTP server</ulink> or one
mode: sgml
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/contrib/chapter.sgml b/en_US.ISO8859-1/books/handbook/contrib/chapter.sgml
index c04d625c12..2dffa913a2 100644
--- a/en_US.ISO8859-1/books/handbook/contrib/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/contrib/chapter.sgml
@@ -1,5 +1,4 @@
-
- <chapter id="contrib">
+<chapter id="contrib">
<title>Contributing to FreeBSD</title>
<para><emphasis>Contributed by &a.jkh;.</emphasis></para>
@@ -724,2529 +723,7 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</sect2>
- <sect2 id="porting">
- <title>Porting an existing piece of free software</title>
-
- <para><emphasis>Contributed by &a.jkh;, &a.gpalmer;, &a.asami; and
- &a.obrien;.<!-- <br> -->28 August 1996.</emphasis></para>
-
- <para>The porting of freely available software, while perhaps not as
- gratifying as developing your own from scratch, is still a vital
- part of FreeBSD's growth and of great usefulness to those who
- would not otherwise know where to turn for it. All ported
- software is organized into a carefully organized hierarchy known
- as “the ports collection”. The collection enables a new user to
- get a quick and complete overview of what is available for FreeBSD
- in an easy-to-compile form. It also saves considerable space by
- not actually containing the majority of the sources being ported,
- but merely those differences required for running under FreeBSD.</para>
-
- <para>What follows are some guidelines for creating a new port for
- FreeBSD. The bulk of the work is done by
- <filename>/usr/share/mk/bsd.port.mk</filename>, which all port
- Makefiles include. Please refer to that file for more details on
- the inner workings of the ports collection. Even if you don't
- hack Makefiles daily, it is well commented, and you will still
- gain much knowledge from it.</para>
-
-
- <sect3 id="porting-starting">
- <title>Before Starting the Port</title>
- <note>
- <para>Only a fraction of the overridable variables
- are mentioned in
- this document. Most (if not all) are documented at the start
- of <filename>bsd.port.mk</filename>. This file uses a
- non-standard tab setting. <command>Emacs</command> and
- <command>Vim</command> should recognize the setting on loading
- the file. <command>vi</command> or <command>ex</command> can
- be set to using the correct value by typing <literal>:set
- tabstop=4</literal> once the file has been loaded.</para>
- </note>
-
- <para>You may come across code that needs modifications or
- conditional compilation based upon what version of UNIX it is
- running under. If you need to make such changes to the code for
- conditional compilation, make sure you make the changes as
- general as possible so that we can back-port code to FreeBSD 1.x
- systems and cross-port to other BSD systems such as 4.4BSD from
- CSRG, BSD/386, 386BSD, NetBSD, and OpenBSD.</para>
-
- <para>The preferred way to tell 4.3BSD/Reno (1990) and newer
- versions of the BSD code apart is by using the
- <acronym>BSD</acronym> macro defined in
- <filename><sys/param.h></filename>. Hopefully that file
- is already included; if not, add the code:</para>
-
- <programlisting>
-#if (defined(__unix__) || defined(unix)) && !defined(USG)
-#include <sys/param.h>
-#endif</programlisting>
-
- <para>to the proper place in the <filename>.c</filename> file. We
- believe that every system that defines these to symbols has
- <filename>sys/param.h</filename>. If you find a system that
- doesn't, we would like to know. Please send mail to
- &a.ports;.</para>
-
- <para>Another way is to use the GNU Autoconf style of doing
- this:</para>
-
- <programlisting>
-#ifdef HAVE_SYS_PARAM_H
-#include <sys/param.h>
-#endif</programlisting>
-
- <para>Don't forget to add <literal>-DHAVE_SYS_PARAM_H</literal> to
- the <makevar>CFLAGS</makevar> in the Makefile for this
- method.</para>
-
- <para>Once you have <filename>sys/param.h</filename>
- included, you may use:</para>
-
- <programlisting>
-#if (defined(BSD) && (BSD >= 199103))</programlisting>
-
- <para>to detect if the code is being compiled on a 4.3 Net2 code
- base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD,
- BSD/386 1.1 and below).</para>
-
- <para>Use:</para>
-
- <programlisting>
-#if (defined(BSD) && (BSD >= 199306))</programlisting>
-
- <para>to detect if the code is being compiled on a 4.4 code base
- or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or
- above).</para>
-
- <para>The value of the BSD macro is 199506 for the 4.4BSD-Lite2
- code base. This is stated for informational purposes only. It
- should not be used to distinguish between version of FreeBSD
- based only on 4.4-Lite vs. versions that have merged in changes
- from 4.4-Lite2. The __FreeBSD__ macro should be used
- instead.</para>
-
- <para>Use sparingly:</para>
-
-
- <itemizedlist>
-
- <listitem>
- <para><literal>__FreeBSD__</literal> is defined in all
- versions of FreeBSD. Use it if the change you are making
- ONLY affects FreeBSD. Porting gotchas like the use of
- <literal>sys_errlist[]</literal> vs
- <function>strerror()</function> are Berkeleyisms, not
- FreeBSD changes.</para>
- </listitem>
-
- <listitem>
- <para>In FreeBSD 2.x, <literal>__FreeBSD__</literal> is
- defined to be <literal>2</literal>. In earlier
- versions, it is <literal>1</literal>. Later
- versions will bump it to match their major version number.</para>
- </listitem>
-
- <listitem>
- <para>If you need to tell the difference between a FreeBSD
- 1.x system and a FreeBSD 2.x or 3.x system, usually the
- right answer is to use the <acronym>BSD</acronym> macros
- described above. If there actually is a FreeBSD specific
- change (such as special shared library options when using
- <command>ld</command>) then it is OK to use
- <literal>__FreeBSD__</literal> and <literal>#if
- __FreeBSD__ > 1</literal> to detect a FreeBSD 2.x
- and later system. If you need more granularity in
- detecting FreeBSD systems since 2.0-RELEASE you can use
- the following:</para>
-
- <programlisting>
-#if __FreeBSD__ >= 2
-#include <osreldate.h>
-# if __FreeBSD_version >= 199504
- /* 2.0.5+ release specific code here */
-# endif
-#endif</programlisting>
-
- <informaltable frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Release</entry>
- <entry><literal>_FreeBSD_version</literal></entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>2.0-RELEASE</entry>
- <entry>119411</entry>
- </row>
-
- <row>
- <entry>2.1-currents</entry>
- <entry>199501, 199503</entry>
- </row>
-
- <row>
- <entry>2.0.5-RELEASE</entry>
- <entry>199504</entry>
- </row>
-
- <row>
- <entry>2.2-current before 2.1</entry>
- <entry>199508</entry>
- </row>
-
- <row>
- <entry>2.1.0-RELEASE</entry>
- <entry>199511</entry>
- </row>
-
- <row>
- <entry>2.2-current before 2.1.5</entry>
- <entry>199512</entry>
- </row>
-
- <row>
- <entry>2.1.5-RELEASE</entry>
- <entry>199607</entry>
- </row>
-
- <row>
- <entry>2.2-current before 2.1.6</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 (no change)</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after 2.2.1-RELEASE</entry>
- <entry>220000 (no change)</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after texinfo-3.9</entry>
- <entry>221001</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after top</entry>
- <entry>221002</entry>
- </row>
-
- <row>
- <entry>2.2.2-RELEASE</entry>
- <entry>222000</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after 2.2.2-RELEASE</entry>
- <entry>222001</entry>
- </row>
-
- <row>
- <entry>2.2.5-RELEASE</entry>
- <entry>225000</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after 2.2.5-RELEASE</entry>
- <entry>225001</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after ldconfig -R merge</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-STABLE after 2.2.7-RELEASE</entry>
- <entry>227001</entry>
- </row>
-
- <row>
- <entry>3.0-current before mount(2) change</entry>
- <entry>300000</entry>
- </row>
-
- <row>
- <entry>3.0-current as of November 1996</entry>
- <entry>300001</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </listitem>
- </itemizedlist>
-
- <note>
- <para>Note that 2.2-STABLE sometimes identifies itself as
- “2.2.5-STABLE” after the 2.2.5-RELEASE. The pattern used to
- be year followed by the month, but we decided to change it
- to a more straightforward major/minor system starting from
- 2.2. This is because the parallel development on several
- branches made it infeasible to classify the releases simply
- by their real release dates. If you are making a port now,
- you don't have to worry about old -current's; they are
- listed here just for your reference.</para>
- </note>
-
-
- <para>In the hundreds of ports that have been done, there have
- only been one or two cases where <literal>__FreeBSD__</literal>
- should have been used. Just because an earlier port screwed up
- and used it in the wrong place does not mean you should do so
- too.</para>
-
- </sect3>
-
- <sect3>
- <title>Quick Porting</title>
-
- <para>This section tells you how to do a quick port. In many
- cases, it is not enough, but we will see.</para>
-
- <para>First, get the original tarball and put it into <makevar>DISTDIR</makevar>, which defaults to
- <filename>/usr/ports/distfiles</filename>.</para>
-
- <note>
- <para>The following assumes that the software compiled
- out-of-the-box, i.e., there was absolutely no change required
- for the port to work on your FreeBSD box. If you needed to
- change something, you will have to refer to the next section
- too.</para>
- </note>
-
- <sect4>
- <title>Writing the <filename>Makefile</filename></title>
-
- <para>The minimal <filename>Makefile</filename> would
- look something like this:</para>
-
- <programlisting>
-# New ports collection makefile for: oneko
-# Version required: 1.1b
-# Date created: 5 December 1994
-# Whom: asami
-#
-# $Id$
-#
-
-DISTNAME= oneko-1.1b
-CATEGORIES= games
-MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
-
-MAINTAINER= asami@FreeBSD.ORG
-
-MAN1= oneko.1
-MANCOMPRESSED= yes
-USE_IMAKE= yes
-
-.include <bsd.port.mk></programlisting>
-
- <para>See if you can figure it out. Do not worry about the
- contents of the <literal>$Id$</literal>
- line, it will be filled in automatically by CVS when the port
- is imported to our main ports tree. You can find a more
- detailed example in the <link
- linkend="porting-samplem">sample Makefile</link>
- section.</para>
-
- </sect4>
-
- <sect4>
- <title>Writing the description files</title>
-
- <para>There are three required description files that are
- required for any port, whether they actually package or not.
- They are <filename>COMMENT</filename>,
- <filename>DESCR</filename>, and <filename>PLIST</filename>,
- and reside in the <filename>pkg</filename>
- subdirectory.</para>
-
-
- <sect5>
- <title><filename>COMMENT</filename></title>
-
- <para>This is the one-line description of the port.
- <emphasis>Please</emphasis> do not include the package name (or version
- number of the software) in the comment. Here is
- an example:</para>
-
- <programlisting>
-A cat chasing a mouse all over the screen.</programlisting>
-
- </sect5>
-
- <sect5>
- <title><filename>DESCR</filename></title>
-
- <para>This is a longer description of the port. One to a few
- paragraphs concisely explaining what the port does is
- sufficient.</para>
-
- <note>
- <para>This is <emphasis>not</emphasis> a manual or an
- in-depth description on how to use or compile the port!
- <emphasis>Please be careful if you are copying from the
- <filename>README</filename> or manpage</emphasis>; too often
- they are not a concise description of the port or are in an
- awkward format (e.g., manpages have justified spacing). If the
- ported software has an official WWW homepage, you should list
- it here.</para>
- </note>
-
- <para>It is recommended that you sign the name at the end of
- this file, as in:</para>
-
- <programlisting>
-This is a port of oneko, in which a cat chases a poor mouse all over
-the screen.
- :
-(etc.)
-
-http://www.oneko.org/
-
-- Satoshi
-asami@cs.berkeley.edu</programlisting>
-
- </sect5>
-
- <sect5>
- <title><filename>PLIST</filename></title>
-
- <para>This file lists all the files installed by the port. It
- is also called the `packing list' because the package is
- generated by packing the files listed here. The pathnames
- are relative to the installation prefix (usually
- <filename>/usr/local</filename> or
- <filename>/usr/X11R6</filename>). If you are using the
- <makevar>MAN<replaceable>n</replaceable></makevar> variables (as
- you should be), do not list any manpages here.</para>
-
- <para>Here is a small example:</para>
-
- <programlisting>
-bin/oneko
-lib/X11/app-defaults/Oneko
-lib/X11/oneko/cat1.xpm
-lib/X11/oneko/cat2.xpm
-lib/X11/oneko/mouse.xpm</programlisting>
-
- <para>Refer to the <citerefentry><refentrytitle>pkg_create</refentrytitle><manvolnum>1</manvolnum></citerefentry> man page
- for details on the packing list.</para>
-
- </sect5>
- </sect4>
-
- <sect4>
- <title>Creating the checksum file</title>
-
- <para>Just type <command>make makesum</command>.
- The ports make rules will automatically generate the file
- <filename>files/md5</filename>.</para>
-
- </sect4>
-
- <sect4>
- <title>Testing the port</title>
-
- <para>You should make sure that the port rules do exactly what
- you want it to do, including packaging up the port. Try doing
- <command>make install</command>, <command>make package</command> and then <command>make deinstall</command> and see if all the files
- and directories are correctly deleted. Then do a <command>pkg_add `make package-name`.tgz</command> and see
- if everything re-appears and works correctly. Then do another
- <command>make deinstall</command> and then
- <command>make reinstall; make package</command>
- to make sure you haven't included in the packing list any
- files that are not installed by your port.</para>
-
- </sect4>
-
- <sect4 id="porting-submitting">
- <title>Submitting the port</title>
-
- <para>First, make sure you have read the <link
- linkend="porting-dads">Do's and Dont's</link> section.</para>
-
- <para>Now that you are happy with your port, the only thing
- remaining is to put it in the main FreeBSD ports tree and make
- everybody else happy about it too. We do not need your
- <filename>work</filename> directory or the
- <filename>pkgname.tgz</filename> package, so delete them
- now. Next, simply include the output of <command>shar `find
- port_dir`</command> in a bug report and send it with the
- <citerefentry>
- <refentrytitle>send-pr</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> program. If the uncompressed port is larger than
- 20KB, you should compress it into a tarfile and use <citerefentry>
- <refentrytitle>uuencode</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> before including it in the bug report (uuencoded
- tarfiles are acceptable even if the bug report is smaller than
- 20KB but are not preferred). Be sure to classify the bug report as
- category <literal>ports</literal> and class
- <literal>change-request</literal>.</para>
-
- <para>One more time, <emphasis>do not include the original source
- distfile, the <filename>work</filename> directory, or the
- package you built with <command>make
- package</command></emphasis>.</para>
-
- <para>See <link linkend="contrib-general">Bug Reports and General
- Commentary</link> for more information.</para>
-
- <para>We will look at your port,
- get back to you if necessary, and put it in the
- tree. Your name will also appear in the list of “Additional
- FreeBSD contributors” on the FreeBSD Handbook and other files.
- Isn't that great?!? <!-- smiley -->:)</para>
-
- </sect4>
- </sect3>
-
- <sect3>
- <title>Slow Porting</title>
-
- <para>Ok, so it was not that simple, and the port required some
- modifications to get it to work. In this section, we will
- explain, step by step, how to modify it to get it to work with
- the ports paradigm.</para>
-
-
- <sect4>
- <title>How things work</title>
-
- <para>First, this is the sequence of events which occurs when
- the user first types <command>make</command> in
- your port's directory, and you may find that having
- <filename>bsd.port.mk</filename> in another window while you
- read this really helps to understand it.</para>
-
- <para>But do not worry if you do not really understand what
- <filename>bsd.port.mk</filename> is doing, not many people
- do... <!-- smiley --><emphasis>:></emphasis></para>
-
-
- <procedure>
-
- <step>
- <para>The <maketarget>fetch</maketarget> target is run. The <maketarget>fetch</maketarget> target is
- responsible for making sure that the tarball exists
- locally in <makevar>DISTDIR</makevar>.
- If <maketarget>fetch</maketarget> cannot find the required files in <makevar>DISTDIR</makevar> it will look up the
- URL <makevar>MASTER_SITES</makevar>,
- which is set in the Makefile, as well as our main ftp
- site at <ulink
- URL="ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/">ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/,</ulink> where we put sanctioned distfiles as backup. It will then attempt to fetch the named distribution file with <makevar>FETCH</makevar>, assuming that the requesting site has direct access to the Internet. If that succeeds, it will save the file in <makevar>DISTDIR</makevar> for future use and proceed.</para>
- </step>
-
- <step>
- <para>The <maketarget>extract</maketarget> target is run. It looks for your port's
- distribution file in <makevar>DISTDIR</makevar> (typically a gzip'd
- tarball) and unpacks it into a temporary subdirectory
- specified by <makevar>WRKDIR</makevar>
- (defaults to <filename>work</filename>).</para>
- </step>
-
- <step>
- <para>The <maketarget>patch</maketarget> target is run. First, any patches defined
- in <makevar>PATCHFILES</makevar> are
- applied. Second, if any patches are found in <makevar>PATCHDIR</makevar> (defaults to the
- <filename>patches</filename> subdirectory), they are
- applied at this time in alphabetical order.</para>
- </step>
-
- <step>
- <para>The <maketarget>configure</maketarget> target is run. This can do any one of
- many different things.</para>
-
- <orderedlist>
-
- <listitem>
- <para>If it exists,
- <filename>scripts/configure</filename> is run.</para>
- </listitem>
-
- <listitem>
- <para>If <makevar>HAS_CONFIGURE</makevar> or
- <makevar>GNU_CONFIGURE</makevar>
- is set,
- <filename><makevar>WRKSRC</makevar>/configure</filename> is
- run.</para>
- </listitem>
-
- <listitem>
- <para>If <makevar>USE_IMAKE</makevar> is set,
- <makevar>XMKMF</makevar>
- (default: <command>xmkmf
- -a</command>) is run.</para>
- </listitem>
-
- </orderedlist>
-
- </step>
-
- <step>
- <para>The <maketarget>build</maketarget> target is run. This is responsible for
- descending into the ports' private working directory
- (<makevar>WRKSRC</makevar>) and
- building it. If <makevar>USE_GMAKE</makevar> is set, GNU
- <command>make</command> will be used,
- otherwise the system <command>make</command>
- will be used.</para>
- </step>
-
- </procedure>
-
-
- <para>The above are the default actions. In addition, you can
- define targets <maketarget>pre-<replaceable>something</replaceable></maketarget> or <maketarget>post-<replaceable>something</replaceable></maketarget>, or put scripts
- with those names, in the <filename>scripts</filename>
- subdirectory, and they will be run before or after the default
- actions are done.</para>
-
- <para>For example, if you have a <maketarget>post-extract</maketarget> target defined in your
- Makefile, and a file <filename>pre-build</filename> in the
- <filename>scripts</filename> subdirectory, the
- <maketarget>post-extract</maketarget> target will be
- called after the regular extraction actions, and the
- <filename>pre-build</filename> script will be executed before
- the default build rules are done. It is recommended that you
- use <filename>Makefile</filename> targets if the actions are
- simple enough, because it will be easier for someone to figure
- out what kind of non-default action the port requires.</para>
-
- <para>The default actions are done by the
- <filename>bsd.port.mk</filename> targets <maketarget>do-<replaceable>something</replaceable></maketarget>. For example, the
- commands to extract a port are in the target <maketarget>do-extract</maketarget>. If you are not happy with
- the default target, you can fix it by redefining the
- <maketarget>do-<replaceable>something</replaceable></maketarget> target in
- your <filename>Makefile</filename>.</para>
-
- <note>
- <para>The “main” targets (e.g., <maketarget>extract</maketarget>, <maketarget>configure</maketarget>, etc.) do nothing more than
- make sure all the stages up to that one is completed and
- call the real targets or scripts, and they are not intended
- to be changed. If you want to fix the extraction, fix
- <maketarget>do-extract</maketarget>, but never ever
- touch <maketarget>extract</maketarget>!</para>
- </note>
-
- <para>Now that you understand what goes on when the user types
- <command>make</command>, let us go through the
- recommended steps to create the perfect port.</para>
-
- </sect4>
-
- <sect4>
- <title>Getting the original sources</title>
-
- <para>Get the original sources (normally) as a compressed
- tarball (<filename><replaceable>foo</replaceable>.tar.gz</filename> or
- <filename><replaceable>foo</replaceable>.tar.Z</filename>) and copy it into
- <makevar>DISTDIR</makevar>. Always use
- <emphasis>mainstream</emphasis> sources when and where you
- can.</para>
-
- <para>If you cannot find a ftp/http site that is well-connected
- to the net, or can only find sites that have irritatingly
- non-standard formats, you might want to put a copy on a
- reliable http or ftp server that you control. If you are a FreeBSD
- committer, your <filename>public_html</filename> directory on
- <hostid>freefall</hostid> is ideal. Make sure you set
- <makevar>MASTER_SITE</makevar> to reflect your choice. If you
- cannot find somewhere convenient and reliable to put the distfile,
- we can “house” it ourselves by putting
- it on <filename>ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/LOCAL_PORTS/</filename> as the last resort. Please refer to this
- location as <makevar>MASTER_SITE_LOCAL</makevar>. Send mail to
- the &a.ports;if you are not sure what to do.</para>
-
- <para>If your port requires some additional `patches' that are
- available on the Internet, fetch them too and put them in
- <makevar>DISTDIR</makevar>. Do not worry if
- they come from site other than where you got the main source
- tarball, we have a way to handle these situations (see the
- description of <link
- linkend="porting-patchfiles">PATCHFILES</link> below).</para>
-
- </sect4>
-
- <sect4>
- <title>Modifying the port</title>
-
- <para>Unpack a copy of the tarball in a private directory and
- make whatever changes are necessary to get the port to compile
- properly under the current version of FreeBSD. Keep
- <emphasis>careful track</emphasis> of everything you do, as
- you will be automating the process shortly. Everything,
- including the deletion, addition or modification of files
- should be doable using an automated script or patch file when
- your port is finished.</para>
-
- <para>If your port requires significant user
- interaction/customization to compile or install, you should
- take a look at one of Larry Wall's classic <application>Configure</application> scripts
- and perhaps do something similar yourself. The goal of the
- new ports collection is to make each port as “plug-and-play”
- as possible for the end-user while using a minimum of disk
- space.</para>
-
- <note>
- <para>Unless explicitly stated, patch files, scripts, and
- other files you have created and contributed to the FreeBSD
- ports collection are assumed to be covered by the standard
- BSD copyright conditions.</para>
- </note>
- </sect4>
-
- <sect4>
- <title>Patching</title>
-
- <para>In the preparation of the port, files that have been added
- or changed can be picked up with a recursive diff for later
- feeding to patch. Each set of patches you wish to apply
- should be collected into a file named
- <filename>patch-<replaceable>xx</replaceable></filename> where
- <replaceable>xx</replaceable> denotes the sequence in which
- the patches will be applied — these are done in
- <emphasis>alphabetical order</emphasis>, thus
- <literal>aa</literal> first, <literal>ab</literal> second and so on. These files
- should be stored in <makevar>PATCHDIR</makevar>, from where they will be
- automatically applied. All patches should be relative to
- <makevar>WRKSRC</makevar> (generally the
- directory your port's tarball unpacks itself into, that being
- where the build is done). To make fixes and upgrades easier
- you should avoid having more than one patch fix the same file
- (e.g., patch-aa and patch-ab both changing <makevar>WRKSRC</makevar>/foobar.c).</para>
-
- </sect4>
-
- <sect4>
- <title>Configuring</title>
-
- <para>Include any additional customization commands to your
- <filename>configure</filename> script and save it in the
- <filename>scripts</filename> subdirectory. As mentioned
- above, you can also do this as <filename>Makefile</filename>
- targets and/or scripts with the name
- <filename>pre-configure</filename> or
- <filename>post-configure</filename>.</para>
-
- </sect4>
-
- <sect4>
- <title>Handling user input</title>
-
- <para>If your port requires user input to build, configure or
- install, then set <makevar>IS_INTERACTIVE</makevar> in your
- Makefile. This will allow “overnight builds” to skip your port
- if the user sets the variable <envar>BATCH</envar> in his
- environment (and if the user sets the variable
- <envar>INTERACTIVE</envar>, then <emphasis>only</emphasis>
- those ports requiring interaction are built).</para>
-
- </sect4>
- </sect3>
-
- <sect3>
- <title>Configuring the Makefile</title>
-
- <para>Configuring the Makefile is pretty simple, and again we
- suggest that you look at existing examples before starting.
- Also, there is a <link linkend="porting-samplem">sample
- Makefile</link> in this handbook, so take a look and please follow
- the ordering of variables and sections in that template to make
- your port easier for others to read.</para>
-
- <para>Now, consider the following problems in sequence as you
- design your new Makefile:</para>
-
-
- <sect4>
- <title>The original source</title>
-
- <para>Does it live in <makevar>DISTDIR</makevar> as a standard gzip'd
- tarball? If so, you can go on to the next step. If not, you
- should look at overriding any of the <makevar>EXTRACT_CMD</makevar>, <makevar>EXTRACT_BEFORE_ARGS</makevar>, <makevar>EXTRACT_AFTER_ARGS</makevar>, <makevar>EXTRACT_SUFX</makevar>, or <makevar>DISTFILES</makevar> variables, depending on
- how alien a format your port's distribution file is. (The
- most common case is <literal>EXTRACT_SUFX=.tar.Z</literal>,
- when the tarball is condensed by regular compress, not
- gzip.)</para>
-
- <para>In the worst case, you can simply create your own
- <maketarget>do-extract</maketarget> target to override
- the default, though this should be rarely, if ever,
- necessary.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>DISTNAME</makevar></title>
-
- <para>You should set <makevar>DISTNAME</makevar> to be the base name of
- your port. The default rules expect the distribution file
- list (<makevar>DISTFILES</makevar>) to be
- named <makevar>DISTNAME</makevar><makevar>EXTRACT_SUFX</makevar> by
- default which, if it is a normal tarball, is going to be
- something like <literal>foozolix-1.0.tar.gz</literal> for a setting of
- <programlisting>
-DISTNAME=foozolix-1.0</programlisting>.</para>
-
- <para>The default rules also expect the tarball(s) to extract
- into a subdirectory called
- <filename>work/<makevar>DISTNAME</makevar></filename>, e.g. <filename>work/foozolix-1.0/</filename>.</para>
-
- <para>All this behavior can be overridden, of course; it simply
- represents the most common time-saving defaults. For a port
- requiring multiple distribution files, simply set <makevar>DISTFILES</makevar> explicitly. If only a
- subset of <makevar>DISTFILES</makevar> are
- actual extractable archives, then set them up in <makevar>EXTRACT_ONLY</makevar>, which will override
- the <makevar>DISTFILES</makevar> list when
- it comes to extraction, and the rest will be just left in
- <makevar>DISTDIR</makevar> for later
- use.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>CATEGORIES</makevar></title>
-
- <para>When a package is created, it is put under
- <filename>/usr/ports/packages/All</filename> and links are
- made from one or more subdirectories of
- <filename>/usr/ports/packages</filename>. The names of these
- subdirectories are specified by the variable <makevar>CATEGORIES</makevar>. It is intended to
- make life easier for the user when he is wading through the
- pile of packages on the ftp site or the CD-ROM. Please take a
- look at the existing categories (you can find them in <ulink
- URL="http://www.freebsd.org/ports/">the ports
- page</ulink>) and pick the ones that are suitable for your
- port. If your port truly belongs to something that is
- different from all the existing ones, you can even create a
- new category name.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>MASTER_SITES</makevar></title>
-
- <para>Record the directory part of the ftp/http-URL pointing at
- the original tarball in <makevar>MASTER_SITES</makevar>. Do not forget the
- trailing slash (<filename>/</filename>)!</para>
-
- <para>The <command>make</command> macros will try to use this specification for
- grabbing the distribution file with <makevar>FETCH</makevar> if they cannot find it
- already on the system.</para>
-
- <para>It is recommended that you put multiple sites on this
- list, preferably from different continents. This will
- safeguard against wide-area network problems, and we are even
- planning to add support for automatically determining the
- closest master site and fetching from there!</para>
-
- <para>If the original tarball is part of one of the following
- popular archives: X-contrib, GNU, Perl CPAN, TeX CTAN, or
- Linux Sunsite, you refer to those sites in an easy compact
- form using <makevar>MASTER_SITE_XCONTRIB</makevar>, <makevar>MASTER_SITE_GNU</makevar>,
- <makevar>MASTER_SITE_PERL_CPAN</makevar>, <makevar>MASTER_SITE_TEX_CTAN</makevar>, and
- <makevar>MASTER_SITE_SUNSITE</makevar>. Simply set <makevar>MASTER_SITE_SUBDIR</makevar> to the
- path with in the archive. Here is an example:</para>
-
- <programlisting>
-MASTER_SITES= ${MASTER_SITE_XCONTRIB}
-MASTER_SITE_SUBDIR= applications</programlisting>
-
- <para>The user can also set the <makevar>MASTER_SITE_*</makevar> variables in
- <filename>/etc/make.conf</filename> to override our choices,
- and use their favorite mirrors of these popular archives
- instead.</para>
-
- </sect4>
-
- <sect4 id="porting-patchfiles">
- <title><makevar>PATCHFILES</makevar></title>
-
- <para>If your port requires some additional patches that are
- available by ftp or http, set <makevar>PATCHFILES</makevar> to the names of the
- files and <makevar>PATCH_SITES</makevar> to
- the URL of the directory that contains them (the format is the
- same as <makevar>MASTER_SITES</makevar>).</para>
-
- <para>If the patch is not relative to the top of the source tree
- (i.e., <makevar>WKRSRC</makevar>) because it
- contains some extra pathnames, set <makevar>PATCH_DIST_STRIP</makevar> accordingly.
- For instance, if all the pathnames in the patch has an extra
- <literal>foozolix-1.0/</literal> in front of the
- filenames, then set
- <literal>PATCH_DIST_STRIP=-p1</literal>.</para>
-
- <para>Do not worry if the patches are compressed, they will be
- decompressed automatically if the filenames end with
- <filename>.gz</filename> or
- <filename>.Z</filename>.</para>
-
- <para>If the patch is distributed with some other files, such as
- documentation, in a gzip'd tarball, you can't just use
- <makevar>PATCHFILES</makevar>. If that is
- the case, add the name and the location of the patch tarball
- to <makevar>DISTFILES</makevar> and
- <makevar>MASTER_SITES</makevar>. Then, from
- the <maketarget>pre-patch</maketarget> target, apply the
- patch either by running the patch command from there, or
- copying the patch file into the <makevar>PATCHDIR</makevar> directory and calling it
- <filename>patch-<replaceable>xx</replaceable></filename>.</para>
-
- <note>
- <para>Note the tarball will have been extracted alongside the
- regular source by then, so there is no need to explicitly
- extract it if it is a regular gzip'd or compress'd tarball.
- If you do the latter, take extra care not to overwrite
- something that already exists in that directory. Also do
- not forget to add a command to remove the copied patch in
- the <maketarget>pre-clean</maketarget> target.</para>
- </note>
-
- </sect4>
-
- <sect4>
- <title><makevar>MAINTAINER</makevar></title>
-
- <para>Set your mail-address here. Please. <!-- smiley --><emphasis>:)</emphasis></para>
-
- <para>For detailed description of the responsibility of
- maintainers, refer to <link
- linkend="policies-maintainer">MAINTAINER
- on Makefiles</link> section.</para>
-
- </sect4>
-
- <sect4>
- <title>Dependencies</title>
-
- <para>Many ports depend on other ports. There are five
- variables that you can use to ensure that all the required
- bits will be on the user's machine.</para>
-
-
- <sect5>
- <title><makevar>LIB_DEPENDS</makevar></title>
-
- <para>This variable specifies the shared libraries this port
- depends on. It is a list of <replaceable>lib</replaceable>:<replaceable>dir</replaceable> pairs where
- <replaceable>lib</replaceable> is the name of the shared library,
- and <replaceable>dir</replaceable> is the directory in which to
- find it in case it is not available. For example,
-
- <programlisting>
-LIB_DEPENDS= jpeg\\.6\\.:${PORTSDIR}/graphics/jpeg</programlisting>
-
- will check for a shared jpeg library with
- major version 6, and descend into the
- <filename>graphics/jpeg</filename> subdirectory of your
- ports tree to build and install it if it is not
- found.</para>
-
- <note>
- <para>The <replaceable>lib</replaceable> part is just an argument
- given to <command>ldconfig -r | grep</command>, so
- periods should be escaped by two backslashes like in the
- example above.</para>
- </note>
-
- <para>The dependency is checked from within the <maketarget>extract</maketarget> target. Also, the name of the
- dependency is put in to the package so that
- <command>pkg_add</command> will automatically install it if it
- is not on the user's system.</para>
-
- </sect5>
-
- <sect5>
- <title><makevar>RUN_DEPENDS</makevar></title>
-
- <para>This variable specifies executables or files this port
- depends on during run-time. It is a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable> pairs where
- <replaceable>path</replaceable> is the name of the executable or
- file, and <replaceable>dir</replaceable> is the directory in which
- to find it in case it is not available. If
- <replaceable>path</replaceable> starts with a slash
- (<literal>/</literal>), it is treated as a file and its
- existence is tested with <command>test -e</command>;
- otherwise, it is assumed to be an executable, and
- <command>which -s</command> is used to determine if the
- program exists in the user's search path.</para>
-
- <para>For example,
-
- <programlisting>
-RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \
- wish:${PORTSDIR}/x11/tk</programlisting>
-
- will check if the file
- <filename>/usr/local/etc/innd</filename> exists, and build
- and install it from the <filename>news/inn</filename>
- subdirectory of the ports tree if it is not found. It will
- also see if an executable called <command>wish</command> is in your search path, and
- descend into the <filename>x11/tk</filename> subdirectory of
- your ports tree to build and install it if it is not
- found.</para>
-
- <note>
- <para>In this case, <command>innd</command> is actually an
- executable; if an executable is in a place that is not
- expected to be in a normal user's search path, you should
- use the full pathname.</para>
- </note>
-
- <para>The dependency is checked from within the <maketarget>install</maketarget> target. Also, the name of the
- dependency is put in to the package so that
- <command>pkg_add</command> will automatically install it if it
- is not on the user's system.</para>
-
- </sect5>
-
- <sect5>
- <title><makevar>BUILD_DEPENDS</makevar></title>
-
- <para>This variable specifies executables or files this port
- requires to build. Like <makevar>RUN_DEPENDS</makevar>, it is
- a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable> pairs.
- For example,
-
- <programlisting>
-BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>
-
- will check for an executable called
- <command>unzip</command>, and descend into the
- <filename>archivers/unzip</filename> subdirectory of your
- ports tree to build and install it if it is not
- found.</para>
-
- <note>
- <para>“build” here means everything from extracting to
- compilation. The dependency is checked from within the
- <maketarget>extract</maketarget> target.</para>
- </note>
- </sect5>
-
- <sect5>
- <title><makevar>FETCH_DEPENDS</makevar></title>
-
- <para>This variable specifies executables or files this port
- requires to fetch. Like the previous two, it is a list of
- <replaceable>path</replaceable>:<replaceable>dir</replaceable> pairs. For
- example,
-
- <programlisting>
-FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting>
-
- will check for an executable called
- <command>ncftp2</command>, and descend into the
- <filename>net/ncftp2</filename> subdirectory of your ports
- tree to build and install it if it is not found.</para>
-
- <para>The dependency is checked from within the <maketarget>fetch</maketarget> target.</para>
-
- </sect5>
-
- <sect5>
- <title><makevar>DEPENDS</makevar></title>
-
- <para>If there is a dependency that does not fall into either
- of the above four categories, or your port requires to have
- the source of the other port extracted (i.e., having them
- installed is not enough), then use this variable. This is
- just a list of directories, as there is nothing to check,
- unlike the previous four.</para>
-
- </sect5>
- </sect4>
-
- <sect4>
- <title>Building mechanisms</title>
-
- <para>If your package uses GNU <command>make</command>, set
- <literal>USE_GMAKE=yes</literal>. If your package uses GNU
- <command>configure</command>, set
- <literal>GNU_CONFIGURE=yes</literal>. If you want to give
- some extra arguments to GNU <command>configure</command> (other than the default
- <literal>--prefix=${PREFIX}</literal>), set those extra
- arguments in <makevar>CONFIGURE_ARGS</makevar>.</para>
-
- <para>If your package is an X application that creates
- <filename>Makefile</filename>s from
- <filename>Imakefile</filename>s using <command>imake</command>, then set
- <literal>USE_IMAKE=yes</literal>. This will cause the
- configure stage to automatically do an <command>xmkmf
- -a</command>. If the <option>-a</option> flag is a
- problem for your port, set
- <literal>XMKMF=xmkmf</literal>.</para>
-
- <para>If your port's source <filename>Makefile</filename> has
- something else than <maketarget>all</maketarget> as the
- main build target, set <makevar>ALL_TARGET</makevar> accordingly. Same
- goes for <maketarget>install</maketarget> and <makevar>INSTALL_TARGET</makevar>.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>NO_INSTALL_MANPAGES</makevar></title>
-
- <para>If the port uses <command>imake</command> but does not understand the
- <filename>install.man</filename> target,
- <literal>NO_INSTALL_MANPAGES=yes</literal> should be set.
- In addition, the author of the original port should be shot.
- <!-- smiley --><emphasis>:></emphasis></para>
-
- </sect4>
- </sect3>
-
- <sect3>
- <title>Ports that require Motif</title>
-
- <para>There are many programs that require a Motif library
- (available from several commercial vendors, while there is (at
- least) one effort to create a free clone) to compile. Since it
- is a popular toolkit and their licenses usually permit
- redistribution of statically linked binaries, we have made
- special provisions for handling ports that require Motif in a
- way that we can easily compile binaries linked either
- dynamically or statically.</para>
-
-
- <sect4>
- <title><makevar>REQUIRES_MOTIF</makevar></title>
-
- <para>If your port requires Motif, define this variable in the
- Makefile. This will prevent people who don't own a copy of
- Motif from even attempting to build it.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>MOTIFLIB</makevar></title>
-
- <para>This variable will be set by
- <filename>bsd.port.mk</filename> to be the appropriate
- reference to the Motif library. Please patch the source to
- use this wherever the Motif library is referenced in the
- Makefile or Imakefile.</para>
-
- <para>There are two common cases:</para>
-
- <orderedlist>
-
- <listitem>
- <para>If the port refers to the Motif library as
- <option>-lXm</option> in its Makefile or Imakefile,
- simply substitute <makevar>MOTIFLIB</makevar> for it.</para>
- </listitem>
-
- <listitem>
- <para>If the port uses <literal>XmClientLibs</literal> in its Imakefile,
- change it to <literal>${MOTIFLIB}
- ${XTOOLLIB} ${XLIB}</literal>.</para>
- </listitem>
-
- </orderedlist>
-
- <note>
- <para><makevar>MOTIFLIB</makevar> (usually)
- expands to <literal>-L/usr/X11R6/lib -lXm</literal> or
- <literal>/usr/X11R6/lib/libXm.a</literal>, so there is
- no need to add <option>-L</option> or
- <option>-l</option> in front.</para>
- </note>
- </sect4>
- </sect3>
-
- <sect3>
- <title>ELF support</title>
-
- <para>Since FreeBSD is moving to ELF from 3.0-release onwards,
- 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 that there will
- be one more release (2.2.8) from the 2.2 branch. 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 awhile for reference
- in case you have come across some old port you wish to
- upgrade.</para>
-
- <sect4>
- <title>Moving a.out libraries out of the way</title>
-
- <para>A.out libraries should be moved out of
- <filename>/usr/local/lib</filename> and similar to an
- <filename>aout</filename> subdirectory. (If you don't move them
- out of the way, ELF ports will happily overwrite a.out libraries.)
- The <maketarget>move-aout-libs</maketarget> target in the -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>
- </sect4>
-
- <sect4>
- <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>
- </sect4>
-
- <sect4>
- <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's always going to be
- <literal>aout</literal> in -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>
- </sect4>
-
- <sect4>
- <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 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>PLIST</filename> too, and it won't 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>
- </sect4>
-
- <sect4>
- <title><makevar>LIB_DEPENDS</makevar></title>
-
- <para>All port Makefiles 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>
- </sect4>
-
- <sect4>
- <title><filename>PLIST</filename></title>
-
- <para><filename>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>PLIST</filename> mentioned in the previous
- paragraph.</para>
- </sect4>
-
- <sect4>
- <title><literal>ldconfig</literal></title>
-
- <para>The <literal>ldconfig/ line in Makefiles should read:</literal></para>
-
- <programlisting>
-${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....</programlisting>
-
- <para>In <filename>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>
- </sect4>
- </sect3>
-
- <sect3>
- <title>Info files</title>
-
- <para>The new version of texinfo (included in 2.2.2-RELEASE and
- onwards) contains a utility called <command>install-info</command> to add and delete entries to
- the <filename>dir</filename> file. If your port installs any
- info documents, please follow these instructions so your
- port/package will correctly update the user's
- <filename>${PREFIX}/info/dir</filename> file. (Sorry for
- the length of this section, but it is imperative to weave all
- the info files together. If done correctly, it will produce a
- <emphasis>beautiful</emphasis> listing, so please bear with me!
- <!-- smiley --><emphasis>:)</emphasis></para>
-
- <para>First, this is what you (as a porter) need to know:</para>
-
- <informalexample>
- <screen>&prompt.user; <userinput>install-info --help</userinput>
-install-info [OPTION]... [INFO-FILE [DIR-FILE]]
- Install INFO-FILE in the Info directory file DIR-FILE.
-
-Options:
---delete Delete existing entries in INFO-FILE;
- don't insert any new entries.
- :
---entry=TEXT Insert TEXT as an Info directory entry.
- :
---section=SEC Put this file's entries in section SEC of the directory. :</screen>
- </informalexample>
-
- <note>
- <para>This program will not actually
- <emphasis>install</emphasis> info files; it merely inserts or
- deletes entries in the <filename>dir</filename> file.</para>
- </note>
-
- <para>Here's a seven-step procedure to convert ports to use
- <command>install-info</command>. I will use
- <filename>editors/emacs</filename> as an example.</para>
-
- <procedure>
- <step>
- <para>Look at the texinfo sources and make a patch to insert
- <literal>@dircategory</literal> and <literal>@direntry</literal>
- statements to files that don't have them. This is part of
- my patch:</para>
-
- <programlisting>
---- ./man/vip.texi.org Fri Jun 16 15:31:11 1995
-+++ ./man/vip.texi Tue May 20 01:28:33 1997
-@@ -2,6 +2,10 @@
-
- @setfilename ../info/vip
- @settitle VIP
-+@dircategory The Emacs editor and associated tools
-+@direntry
-+* VIP: (vip). A VI-emulation for Emacs.
-+@end direntry
-
- @iftex
- @finalout
- :</programlisting>
-
- <para>The format should be self-explanatory. Many authors
- leave a <filename>dir</filename> file in the source tree
- that contains all the entries you need, so look around
- before you try to write your own. Also, make sure you
- look into related ports and make the section names and
- entry indentations consistent (we recommend that all entry
- text start at the 4th tab stop).</para>
-
- <note>
- <para>Note that you can put only one info entry per file
- because of a bug in <command>install-info
- --delete</command> that deletes only the first entry
- if you specify multiple entries in the
- <email>@direntry</email> section.</para>
- </note>
-
- <para>You can give the <literal>dir</literal>
- entries to <command>install-info</command> as
- arguments (<option>--section</option> and
- <option>--entry</option>) instead of patching the texinfo
- sources. I do not think this is a good idea for ports
- because you need to duplicate the same information in
- <emphasis>three</emphasis> places
- (<filename>Makefile</filename> and
- <literal>@exec</literal>/<literal>@unexec</literal> of
- <filename>PLIST</filename>; see below). However, if you
- have a Japanese (or other multibyte encoding) info files,
- you will have to use the extra arguments to <command>install-info</command> because <command>makeinfo</command> can't handle those texinfo
- sources. (See <filename>Makefile</filename> and
- <filename>PLIST</filename> of
- <filename>japanese/skk</filename> for examples on how to
- do this).</para>
- </step>
-
- <step>
- <para>Go back to the port directory and do a <command>make clean; make</command> and verify that
- the info files are regenerated from the texinfo sources.
- Since the texinfo sources are newer than the info files,
- they should be rebuilt when you type <command>make</command>; but many
- <filename>Makefile</filename>s don't include correct
- dependencies for info files. In <command>emacs</command>' case, I had to
- patch the main <filename>Makefile.in</filename> so it will
- descend into the <filename>man</filename>
- subdirectory to rebuild the info pages.</para>
-
- <programlisting>
---- ./Makefile.in.org Mon Aug 19 21:12:19 1996
-+++ ./Makefile.in Tue Apr 15 00:15:28 1997
-@@ -184,7 +184,7 @@
- # Subdirectories to make recursively. `lisp' is not included
- # because the compiled lisp files are part of the distribution
- # and you cannot remake them without installing Emacs first.
--SUBDIR = lib-src src
-+SUBDIR = lib-src src man
-
- # The makefiles of the directories in $SUBDIR.
- SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile lwlib/Makefile
---- ./man/Makefile.in.org Thu Jun 27 15:27:19 1996
-+++ ./man/Makefile.in Tue Apr 15 00:29:52 1997
-@@ -66,6 +66,7 @@
- ${srcdir}/gnu1.texi \
- ${srcdir}/glossary.texi
-
-+all: info
- info: $(INFO_TARGETS)
-
- dvi: $(DVI_TARGETS)</programlisting>
-
- <para>The second hunk was necessary because the default
- target in the <filename>man</filename> subdir is called
- <maketarget>info</maketarget>, while the main
- <filename>Makefile</filename> wants to call <maketarget>all</maketarget>. I also deleted the installation
- of the <filename>info</filename> info file
- because we already have one with the same name in
- <filename>/usr/share/info</filename> (that patch is not
- shown here).</para>
- </step>
-
- <step>
- <para>If there is a place in the
- <filename>Makefile</filename> that is installing the
- <filename>dir</filename> file, delete it. Your
- port may not be doing it. Also, remove any commands that
- are otherwise mucking around with the
- <filename>dir</filename> file.</para>
-
- <programlisting>
---- ./Makefile.in.org Mon Aug 19 21:12:19 1996
-+++ ./Makefile.in Mon Apr 14 23:38:07 1997
-@@ -368,14 +368,8 @@
- if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \
- then \
- (cd ${infodir}; \
-- if [ -f dir ]; then \
-- if [ ! -f dir.old ]; then mv -f dir dir.old; \
-- else mv -f dir dir.bak; fi; \
-- fi; \
- cd ${srcdir}/info ; \
-- (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir); \
-- (cd $${thisdir}; chmod a+r ${infodir}/dir); \
- for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \
- (cd $${thisdir}; \
- ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \
- chmod a+r ${infodir}/$$f); \</programlisting>
- </step>
-
- <step>
- <para>(This step is only necessary if you are modifying an
- existing port.) Take a look at
- <filename>pkg/PLIST</filename> and delete anything that is
- trying to patch up <filename>info/dir</filename>. They
- may be in <filename>pkg/INSTALL</filename> or some other
- file, so search extensively.</para>
-
- <programlisting>
-Index: pkg/PLIST
-===================================================================
-RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v
-retrieving revision 1.15
-diff -u -r1.15 PLIST
---- PLIST 1997/03/04 08:04:00 1.15
-+++ PLIST 1997/04/15 06:32:12
-@@ -15,9 +15,6 @@
- man/man1/emacs.1.gz
- man/man1/etags.1.gz
- man/man1/ctags.1.gz
--@unexec cp %D/info/dir %D/info/dir.bak
--info/dir
--@unexec cp %D/info/dir.bak %D/info/dir
- info/cl
- info/cl-1
- info/cl-2</programlisting>
- </step>
-
- <step>
- <para>Add a <maketarget>post-install</maketarget>
- target to the <filename>Makefile</filename> to create a
- <filename>dir</filename> file if it is not there. Also,
- call <maketarget>install-info</maketarget> with the
- installed info files.</para>
-
- <programlisting>
-Index: Makefile
-===================================================================
-RCS file: /usr/cvs/ports/editors/emacs/Makefile,v
-retrieving revision 1.26
-diff -u -r1.26 Makefile
---- Makefile 1996/11/19 13:14:40 1.26
-+++ Makefile 1997/05/20 10:25:09 1.28
-@@ -20,5 +20,11 @@
- post-install:
- .for file in emacs-19.34 emacsclient etags ctags b2m
- strip ${PREFIX}/bin/${file}
- .endfor
-+ if [ ! -f ${PREFIX}/info/dir ]; then \
-+ ${SED} -ne '1,/Menu:/p' /usr/share/info/dir > ${PREFIX}/info/dir; \
-+ fi
-+.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode
-+ install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir
-+.endfor
-
- .include <bsd.port.mk></programlisting>
-
- <para>Do not use anything other than
- <filename>/usr/share/info/dir</filename> and the above
- command to create a new info file. In fact, I'd add the
- first three lines of the above patch to
- <filename>bsd.port.mk</filename> if you (the porter)
- wouldn't have to do it in <filename>PLIST</filename> by
- yourself anyway.</para>
- </step>
-
- <step>
- <para>Edit <filename>PLIST</filename> and add equivalent
- <literal>@exec</literal> statements and also
- <literal>@unexec</literal> for <command>pkg_delete</command>.
- You do not need to delete <filename>info/dir</filename>
- with <literal>@unexec</literal>.</para>
-
- <programlisting>
-Index: pkg/PLIST
-===================================================================
-RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v
-retrieving revision 1.15
-diff -u -r1.15 PLIST
---- PLIST 1997/03/04 08:04:00 1.15
-+++ PLIST 1997/05/20 10:25:12 1.17
-@@ -16,7 +14,15 @@
- man/man1/etags.1.gz
- man/man1/ctags.1.gz
-+@unexec install-info --delete %D/info/emacs %D/info/dir
- :
-+@unexec install-info --delete %D/info/ccmode %D/info/dir
- info/cl
- info/cl-1
-@@ -87,6 +94,18 @@
- info/viper-3
- info/viper-4
-+@exec [ -f %D/info/dir ] || sed -ne '1,/Menu:/p' /usr/share/info/dir > %D/info/dir
-+@exec install-info %D/info/emacs %D/info/dir
- :
-+@exec install-info %D/info/ccmode %D/info/dir
- libexec/emacs/19.34/i386--freebsd/cvtmail
- libexec/emacs/19.34/i386--freebsd/digest-doc</programlisting>
-
- <note>
- <para>The <literal>@unexec install-info
- --delete</literal> commands have to be listed before
- the info files themselves so they can read the files.
- Also, the <literal>@exec install-info</literal> commands
- have to be after the info files and the
- <literal>@exec</literal> command that creates the the
- <filename>dir</filename> file.</para>
- </note>
- </step>
-
- <step>
- <para>Test and admire your work. <!-- smiley --><emphasis>:)</emphasis> The sequence I recommend is:
- <command>make package</command>,
- <command>pkg_delete</command>, then
- <command>pkg_add</command>. Check the <filename>dir</filename> file before and after each
- step.</para>
- </step>
-
- </procedure>
-
-
- </sect3>
-
- <sect3>
- <title>Changing the <filename>PLIST</filename> based on <citerefentry>
- <refentrytitle>make</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> variables</title>
-
- <para>Some ports, particularly the <filename>p5-</filename> ports,
- need to change their <filename>PLIST</filename> depending on what
- options they are configured with (or version of perl, in the case of
- <filename>p5-</filename> ports). To make this easy, any instances in
- the <filename>PLIST</filename> of <literal>%%OSREL%%</literal>,
- <literal>%%PERL_VER%%</literal>, and
- <literal>%%PERL_VERSION%%</literal> will be substituted for
- appropriately. If you need to make other substitutions, you can set
- the <makevar>PLIST_SUB</makevar> variable with a list of
- <literal><replaceable>VAR</replaceable>=<replaceable>VALUE</replaceable></literal> pairs and instances of <literal>%%<replaceable>VAR</replaceable>%%</literal> will be substituted with <replaceable>VALUE</replaceable> in the <filename>PLIST</filename>.</para>
- </sect3>
-
- <sect3>
- <title>Licensing Problems</title>
-
- <para>Some software packages have restrictive licenses or can be
- in violation to the law (PKP's patent on public key crypto, ITAR
- (export of crypto software) to name just two of them). What we
- can do with them vary a lot, depending on the exact wordings of
- the respective licenses.</para>
-
- <note>
- <para>It is your responsibility as a porter to read the
- licensing terms of the software and make sure that the FreeBSD
- project will not be held accountable of violating them by
- redistributing the source or compiled binaries either via ftp
- or CD-ROM. If in doubt, please contact the &a.ports;.</para>
- </note>
-
- <para>There are two variables you can set in the Makefile to
- handle the situations that arise frequently:</para>
-
-
- <orderedlist>
-
- <listitem>
- <para>If the port has a “do not sell for profit” type of
- license, set the variable <makevar>NO_CDROM</makevar>. We
- will make sure such ports won't go into the CD-ROM come
- release time. The distfile and package will still be
- available via ftp.</para>
- </listitem>
-
- <listitem>
- <para>If the resulting package needs to be built uniquely
- for each site, or the resulting binary package can't be
- distributed due to licensing; set the variable
- <makevar>NO_PACKAGE</makevar>. We will make sure such
- packages won't go on the ftp site, nor into the CD-ROM
- come release time. The distfile will still be included on
- both however.</para>
- </listitem>
-
- <listitem>
- <para>If the port has legal restrictions on who can use it
- (e.g., crypto stuff) or has a “no commercial use” license,
- set the variable <makevar>RESTRICTED</makevar> to be the
- string describing the reason why. For such ports, the
- distfiles/packages will not be available even from our ftp
- sites.</para>
- </listitem>
-
- </orderedlist>
-
-
- <note>
- <para>The GNU General Public License (GPL), both version 1
- and 2, should not be a problem for ports.</para>
- </note>
-
- <note>
- <para>If you are a committer, make sure you update the
- <filename>ports/LEGAL</filename> file too.</para>
- </note>
- </sect3>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>When you notice that a port is out of date compared to the
- latest version from the original authors, first make sure you
- have the latest port. You can find them in the
- <filename>ports-current</filename> directory of the ftp mirror
- sites.</para>
-
- <para>The next step is to send a mail to the maintainer, if one is
- listed in the port's <filename>Makefile</filename>. That person may already be
- working on an upgrade, or have a reason to not upgrade the port
- right now (because of, for example, stability problems of the
- new version).</para>
-
- <para>If the maintainer asks you to do the upgrade or there isn't
- any such person to begin with, please make the upgrade and send
- the recursive diff (either unified or context diff is fine, but
- port committers appear to prefer unified diff more) of the new
- and old ports directories to us (e.g., if your modified port
- directory is called <filename>superedit</filename>
- and the original as in our tree is
- <filename>superedit.bak</filename>, then send us the result of
- <command>diff -ruN superedit.bak
- superedit</command>). Please examine the output to make
- sure all the changes make sense. The best way to send us the
- diff is by including it to <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- (category <literal>ports</literal>). Please mention any added or deleted files
- in the message, as they have to be explicitly specified to CVS
- when doing a commit. If the diff is more than about 20KB, please
- compress and uuencode it; otherwise, just include it in as is in
- the PR.</para>
-
- </sect3>
-
- <sect3>
- <title><anchor id="porting-dads">Do's and Dont's</title>
-
- <para>Here is a list of common do's and dont's that you encounter
- during the porting process.You should check your own port
- against this list, but you can also check ports in the PR
- database that others have submitted. Submit any comments on
- ports you check as described in <link linkend="contrib-general">Bug
- Reports and General Commentary</link>. Checking ports in
- the PR database will both make it faster for us to commit them,
- and prove that you know what you are doing.</para>
-
-
- <sect4>
- <title><makevar>WRKDIR</makevar></title>
-
- <para>Do not leave anything valuable lying around in the
- <filename>work</filename> subdirectory, <command>make clean</command> will
- <emphasis>nuke</emphasis> it completely! If you need
- auxiliary files that are not scripts or patches, put them in
- the <makevar>FILESDIR</makevar> subdirectory
- (<filename>files</filename> by default) and use the
- <maketarget>post-extract</maketarget> target to copy them
- to the <filename>work</filename> subdirectory.</para>
-
- </sect4>
-
- <sect4>
- <title>Portlint Clean</title>
-
- <para>Do use <command>portlint</command>! The <ulink
- url="http://www.freebsd.org/cgi/ports.cgi?portlint">portlint</ulink> program is part of the ports collection.</para>
- </sect4>
-
- <sect4>
- <title>Strip Binaries</title>
-
- <para>Do strip binaries. If the original source already strips the
- binaries, fine; otherwise you should add a
- <literal>post-install</literal> rule to to it yourself. Here is an
- example;</para>
-
- <programlisting>
-post-install:
- strip ${PREFIX}/bin/xdl</programlisting>
-
- <para>Use the <citerefentry>
- <refentrytitle>file</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> command on the installed executable to check
- whether the binary is stripped or not. If it does not say
- <literal>not stripped</literal>, it is stripped.</para>
- </sect4>
-
- <sect4>
- <title>Correctly Install Manpages</title>
-
- <para>Do use the <makevar>MAN<replaceable>n</replaceable></makevar>
- variables. These variables, will automatically add any manpages
- to <filename>pkg/PLIST</filename> (this means you must
- <emphasis>not</emphasis> list manpages in the
- <filename>PLIST</filename>) and automatically compress manpages
- (unless <makevar>NOMANCOMPRESS</makevar> is set in
- <filename>/etc/make.conf</filename>). If your port installs
- pre-compressed manpages, you must define the
- <makevar>MANCOMPRESSED</makevar> variable.</para>
-
- <programlisting>
-MAN1= foo.1 bar.1
-MAN5= foo.conf.5
-MAN8= baz.8</programlisting>
-
- <note>
- <para>This is not usually necessary with ports that are X
- applications and use <command>Imake</command> to build.</para>
- </note>
-
- <para>If your port anchors its man tree somewhere other than
- <makevar>PREFIX</makevar>, you can use the
- <makevar>MANPREFIX</makevar> to set it. Also, if only manpages in
- certain section go in a non-standard place, such as many Perl
- modules ports, you can set individual man paths using
- <makevar>MAN<replaceable>sect</replaceable>PREFIX</makevar> (where
- <replaceable>sect</replaceable> is one of <literal>1-9</literal>,
- <literal>L</literal> or <literal>N</literal>).</para>
- </sect4>
-
- <sect4>
- <title>INSTALL_* macros</title>
-
- <para>Do use the macros provided in <filename>bsd.port.mk</filename>
- to ensure correct modes and ownership of files in your own
- <maketarget>*-install</maketarget> targets. They are:</para>
-
- <itemizedlist>
- <listitem>
- <para><makevar>INSTALL_PROGRAM</makevar> is a command to install
- binary executables.</para>
- </listitem>
-
- <listitem>
- <para><makevar>INSTALL_SCRIPT</makevar> is a command to install
- executable scripts.</para>
- </listitem>
-
- <listitem>
- <para><makevar>INSTALL_DATA</makevar> is a command to install
- sharable data.</para>
- </listitem>
-
- <listitem>
- <para><makevar>INSTALL_MAN</makevar> is a command to install
- manpages and other documentation (it doesn't compress
- anything).</para>
- </listitem>
- </itemizedlist>
-
- <para>These are basically the <command>install</command> command
- with all the appropriate flags. See below for an example on how
- to use them.</para>
- </sect4>
-
- <sect4>
- <title><filename>INSTALL</filename> package script</title>
-
- <para>If your port needs execute commands when the binary package is
- installed with pkg_add you can do with via the
- <filename>pkg/INSTALL</filename> script. This script will
- automatically be added to the package, and will be run twice by
- <command>pkg_add</command>. The first time will as
- <command>INSTALL ${PKGNAME} PRE-INSTALL</command> and the second
- time as <command>INSTALL ${PKGNAME} POST-INSTALL</command>.
- <literal>$2</literal> can be tested to determine which mode
- the script is being run in.</para>
-
- <para>The <envar>PKG_PREFIX</envar> environmental variable will be
- set to the package installation directory. See <citerefentry>
- <refentrytitle>pkg_add</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> for additional information.</para>
-
- <note>
- <para>This script is not run automatically if you install the port
- with <command>make install</command>. If you are depending on it
- being run, you will have to explicitly call it on your port's
- <filename>Makefile</filename>.</para>
- </note>
- </sect4>
-
- <sect4>
- <title><filename>REQ</filename> package script</title>
-
- <para>If your port needs to determine if it should install or
- not, you can create a <filename>pkg/REQ</filename>
- “requirements” script. It will be invoked automatically at
- installation/deinstallation time to determine whether or not
- installation/deinstallation should proceed. See man
- <citerefentry><refentrytitle>pkg_create</refentrytitle><manvolnum>1</manvolnum></citerefentry> and man
- <citerefentry><refentrytitle>pkg_add</refentrytitle><manvolnum>1</manvolnum></citerefentry> for more information.</para>
-
- </sect4>
-
- <sect4>
- <title>Install additional documentation</title>
-
- <para>If your software has some documentation other than the
- standard man and info pages that you think is useful for the
- user, install it under
- <filename><makevar>PREFIX</makevar>/share/doc</filename>. This can be
- done, like the previous item, in the <maketarget>post-install</maketarget> target.</para>
-
- <para>Create a new directory for your port. The directory name
- should reflect what the port is. This usually means <makevar>PKGNAME</makevar> minus the version part.
- However, if you think the user might want different versions
- of the port to be installed at the same time, you can use the
- whole <makevar>PKGNAME</makevar>.</para>
-
- <para>Make the installation dependent to the variable
- <makevar>NOPORTDOCS</makevar> so that users can disable it in
- <filename>/etc/make.conf</filename>, like this:</para>
-
- <programlisting>
-post-install:
-.if !defined(NOPORTDOCS)
- ${MKDIR}${PREFIX}/share/doc/xv
- ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
-.endif</programlisting>
-
- <para>Do not forget to add them to
- <filename>pkg/PLIST</filename> too! (Do not worry about
- <makevar>NOPORTDOCS</makevar> here; there is currently no way
- for the packages to read variables from
- <filename>/etc/make.conf</filename>.)</para>
-
- <para>If you need to display a message to the installer, you may
- place the message in <filename>pkg/MESSAGE</filename>. This
- capibility is often useful to display additional installation
- steps to be taken after a pkg_add, or to display licensing
- information.</para>
-
- <note>
- <para><filename>MESSAGE</filename> does not need to be added
- to <filename>pkg/PLIST</filename>).</para>
- </note>
- </sect4>
-
- <sect4>
- <title><makevar>DIST_SUBDIR</makevar></title>
-
- <para>Do not let your port clutter
- <filename>/usr/ports/distfiles</filename>. If your port
- requires a lot of files to be fetched, or contains a file that
- has a name that might conflict with other ports (e.g.,
- <filename>Makefile</filename>), set <makevar>DIST_SUBDIR</makevar> to the name of the
- port (<makevar>PKGNAME</makevar> without the
- version part should work fine). This will change <makevar>DISTDIR</makevar> from the default
- <filename>/usr/ports/distfiles</filename> to
- <filename>/usr/ports/distfiles/<makevar>DIST_SUBDIR</makevar></filename>,
- and in effect puts everything that is required for your port
- into that subdirectory.</para>
-
- <para>It will also look at the subdirectory with the same name
- on the backup master site at
- <filename>ftp.freebsd.org</filename>. (Setting <makevar>DISTDIR</makevar> explicitly in your
- <makevar>Makefile</makevar> will not accomplish this, so please use <makevar>DIST_SUBDIR</makevar>.)</para>
-
- <note>
- <para>This does not affect the <makevar>MASTER_SITES</makevar> you define in your
- Makefile.</para>
- </note>
- </sect4>
-
- <sect4>
- <title>Package information</title>
-
- <para>Do include package information, i.e.
- <filename>COMMENT</filename>, <filename>DESCR</filename>, and
- <filename>PLIST</filename>, in <filename>pkg</filename>.</para>
-
- <note>
- <para>Note that these files are not used only for packaging
- anymore, and are <emphasis>mandatory</emphasis> now, even if
- <makevar>NO_PACKAGE</makevar> is
- set.</para>
- </note>
- </sect4>
-
- <sect4>
- <title>Feedback</title>
-
- <para>Do send applicable changes/patches to the original
- author/maintainer for inclusion in next release of the code.
- This will only make your job that much easier for the next
- release.</para>
-
- </sect4>
-
- <sect4>
- <title>RCS strings</title>
-
- <para>Do not put RCS strings in patches. CVS will mangle them
- when we put the files into the ports tree, and when we check
- them out again, they will come out different and the patch
- will fail. RCS strings are surrounded by dollar (<literal>$</literal>) signs, and typically start with
- <literal>$Id</literal> or <literal>$RCS</literal>.</para>
-
- </sect4>
-
- <sect4>
- <title>Recursive diff</title>
-
- <para>Using the recurse (<option>-r</option>) option to
- <command>diff</command> to generate patches is
- fine, but please take a look at the resulting patches to make
- sure you don't have any unnecessary junk in there. In
- particular, diffs between two backup files, <filename>Makefiles</filename> when the
- port uses <command>Imake</command> or GNU <command>configure</command>, etc., are unnecessary and
- should be deleted. Also, if you had to delete a file, then you
- can do it in the <maketarget>post-extract</maketarget>
- target rather than as part of the patch. Once you are happy
- with the resulting diff, please split it up into one source
- file per patch file.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>PREFIX</makevar></title>
-
- <para>Do try to make your port install relative to <makevar>PREFIX</makevar>. (The value of this
- variable will be set to <makevar>LOCALBASE</makevar> (default
- <filename>/usr/local</filename>), unless <makevar>USE_X_PREFIX</makevar> or <makevar>USE_IMAKE</makevar> is set, in which case it
- will be <makevar>X11BASE</makevar> (default
- <filename>/usr/X11R6</filename>).)</para>
-
- <para>Not hard-coding <filename>/usr/local</filename> or
- <filename>/usr/X11R6</filename> anywhere in the source will
- make the port much more flexible and able to cater to the
- needs of other sites. For X ports that use <command>imake</command>, this is
- automatic; otherwise, this can often be done by simply
- replacing the occurrences of <filename>/usr/local</filename>
- (or <filename>/usr/X11R6</filename> for X ports that do not
- use imake) in the various scripts/Makefiles in the port to
- read <makevar>PREFIX</makevar>, as this
- variable is automatically passed down to every stage of the
- build and install processes.</para>
-
- <para>Do not set <makevar>USE_X_PREFIX</makevar> unless your port
- truly require it (i.e., it links against X libs or it needs to
- reference files in <makevar>X11BASE</makevar>.</para>
-
- <para>The variable <makevar>PREFIX</makevar>
- can be reassigned in your <filename>Makefile</filename> or in the user's
- environment. However, it is strongly discouraged for
- individual ports to set this variable explicitly in the
- <filename>Makefiles</filename>.</para>
-
- <para>Also, refer to programs/files from other ports with the
- variables mentioned above, not explicit pathnames. For
- instance, if your port requires a macro
- <literal>PAGER</literal> to be the full pathname of <command>less</command>, use the compiler flag:
-
- <programlisting>
--DPAGER=\"${PREFIX}/bin/less\"</programlisting>
-
- or
-
- <programlisting>
--DPAGER=\"${LOCALBASE}/bin/less\"</programlisting>
-
- if this is an X port, instead of <literal>-DPAGER=\"/usr/local/bin/less\".</literal> This way it will have a better chance of working if the system administrator has moved the whole `/usr/local' tree somewhere else.</para>
-
- </sect4>
-
- <sect4>
- <title>Subdirectories</title>
-
- <para>Try to let the port put things in the right subdirectories
- of <makevar>PREFIX</makevar>. Some ports
- lump everything and put it in the subdirectory with the port's
- name, which is incorrect. Also, many ports put everything
- except binaries, header files and manual pages in the a
- subdirectory of <filename>lib</filename>, which does not
- bode well with the BSD paradigm. Many of the files should be
- moved to one of the following: <filename>etc</filename>
- (setup/configuration files), <filename>libexec</filename>
- (executables started internally), <filename>sbin</filename>
- (executables for superusers/managers),
- <filename>info</filename> (documentation for info browser)
- or <filename>share</filename> (architecture independent
- files). See man <citerefentry><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
- details, the rule governing <filename>/usr</filename> pretty
- much applies to <filename>/usr/local</filename> too. The
- exception are ports dealing with USENET “news”. They may use
- <filename><makevar>PREFIX</makevar>/news</filename> as a destination for
- their files.</para>
-
- </sect4>
-
- <sect4>
- <title>ldconfig</title>
-
- <para>If your port installs a shared library, add a <maketarget>post-install</maketarget> target to your Makefile
- that runs <command>/sbin/ldconfig -m</command> on
- the directory where the new library is installed (usually
- <filename><makevar>PREFIX</makevar>/lib</filename>) to register it into
- the shared library cache.</para>
-
- <para>Also, add an <literal>@exec</literal> line to your
- <filename>pkg/PLIST</filename> file so that a user who
- installed the package can start using the shared library
- immediately. This line should immediately follow the line
- for the shared library itself, as in:</para>
-
- <programlisting>
-lib/libtcl80.so.1.0
-@exec /sbin/ldconfig -m %D/lib</programlisting>
-
- <para>Never, ever, <emphasis>ever</emphasis> add a line that
- says <command>ldconfig</command> without any
- arguments to your <filename>Makefile</filename> or <filename>pkg/PLIST</filename>. This will reset the
- shared library cache to the contents of
- <filename>/usr/lib</filename> only, and will royally screw up
- the user's machine (“Help, xinit does not run anymore after I
- install this port!”). Anybody who does this will be shot and
- cut into 65,536 pieces by a rusty knife and have his liver
- chopped out by a bunch of crows and will eternally rot to
- death in the deepest bowels of hell (not necessarily in that
- order)....</para>
-
- </sect4>
-
- <sect4>
- <title>UIDs</title>
-
- <para>If your port requires a certain user to be on the
- installed system, let the <filename>pkg/INSTALL</filename>
- script call <command>pw</command> to create it
- automatically. Look at <filename>net/cvsup-mirror</filename>
- for an example.</para>
-
- <para>If your port must use the same user/group ID number when it is
- installed a binarypackage as when it was compiled, then you mus
- choose a free UID from 50 to 99 and register it below. Look at
- <filename>japanese/Wnn</filename> for an example.</para>
-
- <para>Make sure you don't use a UID already used by the system
- or other ports. This is the current list of UIDs between 50
- and 99.</para>
-
- <programlisting>
-majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent
-cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent
-gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh
-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:/nonexistent
-wnn:*:69:7:Wnn:/nonexistent:/nonexistent
-ifmail:*:70:66:Ifmail user:/nonexistent:/nonexistent
-pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh
-ircd:*:72:72:IRCd hybrid:/nonexistent:/nonexistent
-alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent
-qmaill:*:83:81:QMail user:/var/qmail:/nonexistent
-qmaild:*:82:81:QMail user:/var/qmail:/nonexistent
-qmailq:*:85:82:QMail user:/var/qmail:/nonexistent
-qmails:*:87:82:QMail user:/var/qmail:/nonexistent
-qmailp:*:84:81:QMail user:/var/qmail:/nonexistent
-qmailr:*:86:82:QMail user:/var/qmail:/nonexistent
-msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh</programlisting>
-
- <para>Please include a notice when you submit a port (or an
- upgrade) that reserves a new UID or GID in this range. This allows
- us to keep the list of reserved IDs up to date.</para>
-
- </sect4>
-
- <sect4>
- <title>Doing things rationally</title>
-
- <para>The <filename>Makefile</filename> should do things simply and
- reasonably. If you can make it a couple of lines shorter or more
- readable, then do so. Examples include using a make
- <literal>.if</literal> construct instead of a shell
- <literal>if</literal> construct, not redefining
- <maketarget>do-extract</maketarget> if you can redefine
- <makevar>EXTRACT*</makevar> instead, and using
- <makevar>GNU_CONFIGURE</makevar> instead of
- <literal>CONFIGURE_ARGS +=
- --prefix=${PREFIX}</literal>.</para>
- </sect4>
-
- <sect4>
- <title>Respect <makevar>CFLAGS</makevar></title>
-
- <para>The port should respect the <makevar>CFLAGS</makevar>
- variable. If it doesn't, please add <literal>NO_PACKAGE=ignores
- cflags</literal> to the <filename>Makefile</filename>.</para>
- </sect4>
-
- <sect4>
- <title>Miscellanea</title>
-
- <para>The files <filename>pkg/DESCR</filename>,
- <filename>pkg/COMMENT</filename>, and
- <filename>pkg/PLIST</filename> should each be double-checked. If
- you are reviewing a port and feel they can be worded better, do
- so.</para>
-
- <para>Don't copy more copies of the GNU General Public License into
- our system, please.</para>
-
- <para>Please be careful to note any legal issues! Don't let us
- illegally distribute software!</para>
- </sect4>
-
- <sect4>
- <title>If you are stuck....</title>
-
- <para>Do look at existing examples and the
- <filename>bsd.port.mk</filename> file before asking us
- questions! <!-- smiley --><emphasis>;)</emphasis></para>
-
- <para>Do ask us questions if you have any trouble! Do not just
- beat your head against a wall! <!-- smiley --><emphasis>:)</emphasis></para>
-
- </sect4>
- </sect3>
-
- <sect3 id="porting-samplem">
- <title>A Sample <filename>Makefile</filename></title>
-
- <para>Here is a sample <filename>Makefile</filename> that you can
- use to create a new port. Make sure you remove all the extra
- comments (ones between brackets)!</para>
-
- <para>It is recommended that you follow this format (ordering of
- variables, empty lines between sections, etc.). Not all of the
- existing <filename>Makefile</filename>s are in this format
- (mostly old ones), but we are trying to uniformize how they
- look. This format is designed so that the most important
- information is easy to locate.</para>
-
- <programlisting>
-[the header...just to make it easier for us to identify the ports.]
-# New ports collection makefile for: xdvi
-[the version required header should updated when upgrading a port.]
-# Version required: pl18 [things like "1.5alpha" are fine here too]
-[this is the date when the first version of this Makefile was created.
-Never change this when doing an update of the port.]
-# Date created: 26 May 1995
-[this is the person who did the original port to FreeBSD, in particular, the
-person who wrote the first version of this Makefile. Remember, this should
-not be changed when upgrading the port later.]
-# Whom: Satoshi Asami <asami@FreeBSD.ORG>
-#
-# $Id$
-[ ^^^^ This will be automatically replaced with RCS ID string by CVS
-when it is committed to our repository.]
-#
-
-[section to describe the port itself and the master site - DISTNAME
- is always first, followed by PKGNAME (if necessary), CATEGORIES,
- and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR.
- After those, one of EXTRACT_SUFX or DISTFILES can be specified too.]
-DISTNAME= xdvi
-PKGNAME= xdvi-pl18
-CATEGORIES= print
-[do not forget the trailing slash ("/")!
- if you aren't using MASTER_SITE_* macros]
-MASTER_SITES= ${MASTER_SITE_XCONTRIB}
-MASTER_SITE_SUBDIR= applications
-[set this if the source is not in the standard ".tar.gz" form]
-EXTRACT_SUFX= .tar.Z
-
-[section for distributed patches -- can be empty]
-PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/
-PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz
-
-[maintainer; *mandatory*! This is the person (preferably with commit
- privileges) who a user can contact for questions and bug reports - this
- person should be the porter or someone who can forward questions to the
- original porter reasonably promptly. If you really do not want to have
- your address here, set it to "ports@FreeBSD.ORG".]
-MAINTAINER= asami@FreeBSD.ORG
-
-[dependencies -- can be empty]
-RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript
-LIB_DEPENDS= Xpm\\.4\\.:${PORTSDIR}/graphics/xpm
-
-[this section is for other standard bsd.port.mk variables that do not
- belong to any of the above]
-[If it asks questions during configure, build, install...]
-IS_INTERACTIVE= yes
-[If it extracts to a directory other than ${DISTNAME}...]
-WRKSRC= ${WRKDIR}/xdvi-new
-[If the distributed patches were not made relative to ${WRKSRC}, you
- may need to tweak this]
-PATCH_DIST_STRIP= -p1
-[If it requires a "configure" script generated by GNU autoconf to be run]
-GNU_CONFIGURE= yes
-[If it requires GNU make, not /usr/bin/make, to build...]
-USE_GMAKE= yes
-[If it is an X application and requires "xmkmf -a" to be run...]
-USE_IMAKE= yes
-[et cetera.]
-
-[non-standard variables to be used in the rules below]
-MY_FAVORITE_RESPONSE= "yeah, right"
-
-[then the special rules, in the order they are called]
-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
-
-[and then the epilogue]
-.include <bsd.port.mk></programlisting>
-
- </sect3>
-
- <sect3>
- <title>Package Names</title>
-
- <para>The following are the conventions you should follow in
- naming your packages. This is to have our package directory
- easy to scan, as there are already lots and lots of packages and
- users are going to turn away if they hurt their eyes!</para>
-
- <para>The package name should look like <filename><replaceable>language-</replaceable>name<replaceable>-compiled.specifics</replaceable><replaceable>-version.numbers</replaceable></filename>.</para>
-
- <para>If your <makevar>DISTNAME</makevar>
- doesn't look like that, set <makevar>PKGNAME</makevar> to something in that
- format.</para>
-
-
- <orderedlist>
-
- <listitem>
- <para>FreeBSD strives to support the native language of its
- users. The <replaceable>language-</replaceable> part should be a two letter
- abbreviation of the natural language defined by ISO-639 if
- the port is specific to a certain language. Examples are
- <literal>ja</literal> for Japanese, <literal>ru</literal> for Russian, <literal>vi</literal> for Vietnamese,
- <literal>zh</literal> for Chinese, <literal>ko</literal> for Korean and <literal>de</literal> for German.</para>
- </listitem>
-
- <listitem>
- <para>The <filename>name</filename> part
- should be all lowercases, except for a really large
- package (with lots of programs in it). Things like
- XFree86 (yes there really is a package of it, check it
- out) and ImageMagick fall into this category. Otherwise,
- convert the name (or at least the first letter) to
- lowercase. If the capital letters are
- important to the name (for example, with one-letter names
- like <literal>R</literal> or <literal>V</literal>) you may use capital letters at your discretion.
- There is a tradition of naming Perl 5 modules by prepending
- <literal>p5-</literal> and converting the double-colon separator to a hyphen;
- for example, the <literal>Data::Dumper</literal> module becomes
- <literal>p5-Data-Dumper</literal>. If the software in question has numbers,
- hyphens, or underscores in its name, you may include them as
- well (like <literal>kinput2</literal>).</para>
- </listitem>
-
- <listitem>
- <para>If the port can be built with different hardcoded
- defaults (usually specified as environment variables or on
- the <command>make</command> command line), the
- <replaceable>-compiled.specifics</replaceable> part should state the
- compiled-in defaults (the hyphen is optional). Examples
- are papersize and font units.</para>
- </listitem>
-
- <listitem>
- <para>The version string should be a period-separated list
- of integers and single lowercase alphabetics. The only
- exception is the string <literal>pl</literal> (meaning `patchlevel'), which
- can be used <emphasis>only</emphasis> when there are no
- major and minor version numbers in the software.</para>
- </listitem>
-
- </orderedlist>
-
-
- <para>Here are some (real) examples on how to convert a <makevar>DISTNAME</makevar> into a suitable <makevar>PKGNAME</makevar>:</para>
-
- <informaltable frame="none">
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Distribution Name</entry>
- <entry>Package Name</entry>
- <entry>Reason</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>mule-2.2.2.</entry>
- <entry>mule-2.2.2</entry>
- <entry>No changes required</entry>
- </row>
-
- <row>
- <entry>XFree86-3.1.2</entry>
- <entry>XFree86-3.1.2</entry>
- <entry>No changes required</entry>
- </row>
-
- <row>
- <entry>EmiClock-1.0.2</entry>
- <entry>emiclock-1.0.2</entry>
- <entry>No uppercase names for single programs</entry>
- </row>
-
- <row>
- <entry>gmod1.4</entry>
- <entry>gmod-1.4</entry>
- <entry>Need a hyphen before version numbers</entry>
- </row>
-
- <row>
- <entry>xmris.4.0.2</entry>
- <entry>xmris-4.0.2</entry>
- <entry>Need a hyphen before version numbers</entry>
- </row>
-
- <row>
- <entry>rdist-1.3alpha</entry>
- <entry>rdist-1.3a</entry>
- <entry>No strings like <literal>alpha</literal>
- allowed</entry>
- </row>
-
- <row>
- <entry>es-0.9-beta1</entry>
- <entry>es-0.9b1</entry>
- <entry>No strings like <literal>beta</literal>
- allowed</entry>
- </row>
-
- <row>
- <entry>v3.3beta021.src</entry>
- <entry>tiff-3.3</entry>
- <entry>What the heck was that anyway?</entry>
- </row>
-
- <row>
- <entry>tvtwm</entry>
- <entry>tvtwm-pl11</entry>
- <entry>Version string always required</entry>
- </row>
-
- <row>
- <entry>piewm</entry>
- <entry>piewm-1.0</entry>
- <entry>Version string always required</entry>
- </row>
-
- <row>
- <entry>xvgr-2.10pl1</entry>
- <entry>xvgr-2.10.1</entry>
- <entry><literal>pl</literal> allowed only when no
- major/minor version numbers</entry>
- </row>
-
- <row>
- <entry>gawk-2.15.6</entry>
- <entry>ja-gawk-2.15.6</entry>
- <entry>Japanese language version</entry>
- </row>
-
- <row>
- <entry>psutils-1.13</entry>
- <entry>psutils-letter-1.13</entry>
- <entry>Papersize hardcoded at package build time</entry>
- </row>
-
- <row>
- <entry>pkfonts</entry>
- <entry>pkfonts300-1.0</entry>
- <entry>Package for 300dpi fonts</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>If there is absolutely no trace of version information in
- the original source and it is unlikely that the original author
- will ever release another version, just set the version string
- to <literal>1.0</literal> (like the piewm example above). Otherwise, ask the
- original author or use the date string (<literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>) as the
- version.</para>
-
- </sect3>
-
- <sect3>
- <title>Changes to this document and the ports system</title>
-
- <para>If you maintain a lot of ports, you should consider following
- the <email>ports@FreeBSD.ORG</email> mailing-list. Important changes to
- the way ports work will be announced there. You can always
- find more detailed information on the latest changes by
- looking at <ulink
- url="http://www.FreeBSD.ORG/cgi/cvsweb.cgi/src/share/mk/bsd.port.mk">
- the bsd.port.mk CVS log</ulink>.</para>
- </sect3>
-
- <sect3>
- <title>That is It, Folks!</title>
-
- <para>Boy, this sure was a long tutorial, wasn't it? Thanks for
- following us to here, really.</para>
-
- <para>Well, now that you know how to do a port, let us go at it
- and convert everything in the world into ports! That is the
- easiest way to start contributing to the FreeBSD Project!
- <!-- smiley --><emphasis>:)</emphasis></para>
-
- </sect3>
- </sect2>
-
<sect2>
<title>Money, Hardware or Internet access</title>
@@ -3763,18 +1240,14 @@ box can be opened)</para>
<para>Ari Suutari <email>ari@suutari.iki.fi</email></para>
</listitem>
- <listitem>
- <para>Brent J. Nordquist <email>bjn@visi.com</email></para>
- </listitem>
-
+ <listitem>
+ <para>Ben Hutchinson <email>benhutch@xfiles.org.uk</email></para>
+ </listitem>
+
<listitem>
<para>Bernd Rosauer <email>br@schiele-ct.de</email></para>
</listitem>
- <listitem>
- <para>Bill Fumerola <email>billf@jade.chc-chimes.com</email></para>
- </listitem>
-
<listitem>
<para>Bill Kish <email>kish@osf.org</email></para>
</listitem>
@@ -3899,7 +1372,11 @@ box can be opened)</para>
<listitem>
<para>Chuck Hein <email>chein@cisco.com</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Clive Lin <email>clive@CiRX.ORG</email></para>
+ </listitem>
+
<listitem>
<para>Conrad Sabatier <email>conrads@neosoft.com</email></para>
</listitem>
@@ -4102,6 +1579,10 @@ box can be opened)</para>
<email>ginga@amalthea.phys.s.u-tokyo.ac.jp</email></para>
</listitem>
+ <listitem>
+ <para>Glenn Johnson <email>gljohns@bellsouth.net</email></para>
+ </listitem>
+
<listitem>
<para>Greg Ungerer <email>gerg@stallion.oz.au</email></para>
</listitem>
@@ -4141,7 +1622,11 @@ box can be opened)</para>
<listitem>
<para>Hironori Ikura <email>hikura@kaisei.org</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Hiroyuki NAKAJI <email>nakaji@zeisei3.dpri.kyoto-u.ac.jp</email></para>
+ </listitem>
+
<listitem>
<para>Holger Veit <email>Holger.Veit@gmd.de</email></para>
</listitem>
@@ -4182,10 +1667,6 @@ box can be opened)</para>
<para>Ishii Masahiro</para>
</listitem>
- <listitem>
- <para>Issei Suzuki <email>issei@t-cnet.or.jp</email></para>
- </listitem>
-
<listitem>
<para>Iseei Suzuki <email>issei@jp.FreeBSD.ORG</email></para>
</listitem>
@@ -4242,6 +1723,10 @@ box can be opened)</para>
<para>Jeffrey Wheat <email>jeff@cetlink.net</email></para>
</listitem>
+ <listitem>
+ <para>Jeremy Lea <email>reg@shale.csir.co.za</email></para>
+ </listitem>
+
<listitem>
<para>Jerry Hicks <email>jhicks@glenatl.glenayre.com</email></para>
</listitem>
@@ -4686,7 +2171,11 @@ box can be opened)</para>
<listitem>
<para>Randall Hopper <email>rhh@stealth.ct.picker.com</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Ricardas Cepas <email>rch@richard.eu.org</email></para>
+ </listitem>
+
<listitem>
<para>Richard Hwang <email>rhwang@bigpanda.com</email></para>
</listitem>
@@ -4739,10 +2228,6 @@ box can be opened)</para>
<para>Ruslan Shevchenko <email>rssh@cki.ipri.kiev.ua</email></para>
</listitem>
- <listitem>
- <para>SADA Kenji <email>sada@e-mail.ne.jp</email></para>
- </listitem>
-
<listitem>
<para>SURANYI Peter <email>suranyip@jks.is.tsukuba.ac.jp</email></para>
</listitem>
@@ -4986,7 +2471,11 @@ box can be opened)</para>
<listitem>
<para>Yen-Shuo Su <email>yssu@CCCA.NCTU.edu.tw</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Ying-Chieh Liao <email>ijliao@csie.NCTU.edu.tw</email></para>
+ </listitem>
+
<listitem>
<para>Yoshiaki Uchikawa <email>yoshiaki@kt.rim.or.jp</email></para>
</listitem>
@@ -4998,7 +2487,11 @@ box can be opened)</para>
<listitem>
<para>Yukihiro Nakai <email>nakai@technologist.com</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Yusuke Nawano <email>azuki@azkey.org</email></para>
+ </listitem>
+
<listitem>
<para>Yuval Yarom <email>yval@cs.huji.ac.il</email></para>
</listitem>
@@ -5133,7 +2626,7 @@ box can be opened)</para>
</listitem>
<listitem>
- <para>Guido van Rooij <email>guido@gvr.win.tue.nl</email></para>
+ <para>Guido van Rooij <email>guido@gvr.org</email></para>
</listitem>
<listitem>
@@ -5216,7 +2709,11 @@ box can be opened)</para>
<listitem>
<para>Julian Stacey <email>jhs@freebsd.org</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Karl Dietz <email>Karl.Dietz@triplan.com</email></para>
+ </listitem>
+
<listitem>
<para>Karl Lehenbauer <email>karl@NeoSoft.com</email> <email>karl@one.neosoft.com</email></para>
</listitem>
@@ -5391,9 +2888,7 @@ box can be opened)</para>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
index 51cb7a5561..93ceb6062b 100644
--- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
@@ -275,14 +275,21 @@ subscribe cvs-all</programlisting>
<programlisting>
subscribe freebsd-stable</programlisting> In the body of your
- message. Optionally, you can also say `help' and Majordomo
+ message. Optionally, you can also say <literal>help</literal> and Majordomo
will send you full help on how to subscribe and unsubscribe
to the various other mailing lists we support.</para>
</listitem>
<listitem>
- <para>Grab the sources from <hostid role="fqdn">ftp.FreeBSD.ORG</hostid>. You can do
- this in three ways:</para>
+ <para>If you are installing a new system and want it to be as stable
+ as possible, you can simply grab the latest dated branch snapshot
+ from <ulink
+ url="ftp://releng22.freebsd.org/pub/FreeBSD/">ftp://releng22.freebsd.org/pub/FreeBSD/</ulink> and install it like any other release.</para>
+
+ <para>If you are already running a previous release of 2.2 and wish
+ to upgrade via sources then you can easily do so from <hostid
+ role="fqdn">ftp.FreeBSD.ORG</hostid>. This can be done in one of
+ three ways:</para>
<orderedlist>
@@ -295,7 +302,11 @@ subscribe freebsd-stable</programlisting> In the body of your
<listitem>
<para>Use the <link linkend="cvsup">cvsup</link>
program with <ulink
- URL="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/stable-supfile">this supfile</ulink>. This is the second most recommended method, since it allows you to grab the entire collection once and then only what has changed from then on. Many people run cvsup from cron to keep their sources up-to-date automatically.</para>
+ URL="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/stable-supfile">this supfile</ulink>. This is the second most recommended method, since it allows you to grab the entire collection once and then only what has changed from then on. Many people run cvsup from cron to keep their sources up-to-date automatically. For a fairly easy interface to this, simply type;</para>
+
+ <informalexample>
+ <screen>&prompt.root; <userinput>pkg_add -f ftp://ftp.freebsd.org/pub/FreeBSD/CVSup/cvsupit.tgz</userinput></screen>
+ </informalexample>
</listitem>
<listitem>
@@ -2479,9 +2490,7 @@ cvs-crypto</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/eresources/chapter.sgml b/en_US.ISO8859-1/books/handbook/eresources/chapter.sgml
index 65f8af855a..c1fcd45ce2 100644
--- a/en_US.ISO8859-1/books/handbook/eresources/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/eresources/chapter.sgml
@@ -320,101 +320,11 @@
</thead>
<tbody>
- <row>
- <entry>cvs-CVSROOT</entry>
- <entry>/usr/src/[A-Z]*</entry>
- <entry>Top level /usr/src file changes</entry>
- </row>
-
<row>
<entry>cvs-all</entry>
<entry>/usr/src</entry>
<entry>All changes to the tree (superset)</entry>
</row>
-
- <row>
- <entry>cvs-bin</entry>
- <entry>/usr/src/bin</entry>
- <entry>System binaries</entry>
- </row>
-
- <row>
- <entry>cvs-etc</entry>
- <entry>/usr/src/etc</entry>
- <entry>System files</entry>
- </row>
-
- <row>
- <entry>cvs-games</entry>
- <entry>/usr/src/games</entry>
- <entry>Games</entry>
- </row>
-
- <row>
- <entry>cvs-gnu</entry>
- <entry>/usr/src/gnu</entry>
- <entry>GPL'd utilities</entry>
- </row>
-
- <row>
- <entry>cvs-include</entry>
- <entry>/usr/src/include</entry>
- <entry>Include files</entry>
- </row>
-
- <row>
- <entry>cvs-kerberosIV</entry>
- <entry>/usr/src/kerberosIV</entry>
- <entry>Kerberos encryption code</entry>
- </row>
-
- <row>
- <entry>cvs-lib</entry>
- <entry>/usr/src/lib</entry>
- <entry>System libraries</entry>
- </row>
-
- <row>
- <entry>cvs-libexec</entry>
- <entry>/usr/src/libexec</entry>
- <entry>System binaries</entry>
- </row>
-
- <row>
- <entry>cvs-ports</entry>
- <entry>/usr/ports</entry>
- <entry>Ported software</entry>
- </row>
-
- <row>
- <entry>cvs-sbin</entry>
- <entry>/usr/src/sbin</entry>
- <entry>System binaries</entry>
- </row>
-
- <row>
- <entry>cvs-share</entry>
- <entry>/usr/src/share</entry>
- <entry>System shared files</entry>
- </row>
-
- <row>
- <entry>cvs-sys</entry>
- <entry>/usr/src/sys</entry>
- <entry>Kernel</entry>
- </row>
-
- <row>
- <entry>cvs-usrbin</entry>
- <entry>/usr/src/usr.bin</entry>
- <entry>Use binaries</entry>
- </row>
-
- <row>
- <entry>cvs-usrsbin</entry>
- <entry>/usr/src/usr.sbin</entry>
- <entry>System binaries</entry>
- </row>
</tbody>
</tgroup>
</informaltable>
@@ -1226,9 +1136,7 @@ help
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/hw/chapter.sgml b/en_US.ISO8859-1/books/handbook/hw/chapter.sgml
index 111cde9410..867deea2f8 100644
--- a/en_US.ISO8859-1/books/handbook/hw/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/hw/chapter.sgml
@@ -5677,9 +5677,7 @@ scsi -f $2 -s 100 -c "1b 0 0 $cdb3 $cdb4 $cdb5"</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/install/chapter.sgml b/en_US.ISO8859-1/books/handbook/install/chapter.sgml
index 52485fd470..b11bbc33d0 100644
--- a/en_US.ISO8859-1/books/handbook/install/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/install/chapter.sgml
@@ -1225,9 +1225,7 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml b/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml
index a65b2bd0a8..163e13428a 100644
--- a/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml
@@ -615,9 +615,7 @@
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
index 42ce6deda9..94265ff68d 100644
--- a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
@@ -1695,9 +1695,7 @@ controller wcd0</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/kerneldebug/chapter.sgml b/en_US.ISO8859-1/books/handbook/kerneldebug/chapter.sgml
index f4d06bba3a..796252e1d3 100644
--- a/en_US.ISO8859-1/books/handbook/kerneldebug/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/kerneldebug/chapter.sgml
@@ -660,9 +660,7 @@ text_addr = 0xf5109020? (y or n) <userinput>y</userinput>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/kernelopts/chapter.sgml b/en_US.ISO8859-1/books/handbook/kernelopts/chapter.sgml
index 30f5e9f461..0e6defe0cb 100644
--- a/en_US.ISO8859-1/books/handbook/kernelopts/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/kernelopts/chapter.sgml
@@ -166,9 +166,7 @@ options notyet,notdef</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml b/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml
index 4fda3de2f8..7ab182a604 100644
--- a/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml
@@ -357,9 +357,7 @@ XkbKeymap "xfree86(ru)"</programlisting> line into
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
index 187301676e..0e2bc3b76d 100644
--- a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
@@ -853,9 +853,7 @@ richc.isdn.bcm.tmc.edu 9845-03452-90255</screen>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/mail/chapter.sgml b/en_US.ISO8859-1/books/handbook/mail/chapter.sgml
index e4c2d14f9e..18b2d73610 100644
--- a/en_US.ISO8859-1/books/handbook/mail/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/mail/chapter.sgml
@@ -586,9 +586,7 @@ an A record in the DNS for "customer.com".</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml b/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml
index bfef299630..0f4423b959 100644
--- a/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml
@@ -29,7 +29,13 @@
<para><ulink
URL="ftp://ftp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.FreeBSD.ORG/pub/FreeBSD</ulink>.</para>
</blockquote></para>
-
+
+ <para>The <ulink
+ url="http://www.itworks.com.au/~gavin/FBSDsites.php3">FreeBSD mirror
+ sites database</ulink> is more accurate than the mirror listing in the
+ handbook, as it gets its information form the DNS rather than relying
+ on static lists of hosts.</para>
+
<para>Additionally, FreeBSD is available via anonymous FTP from the
following mirror sites. If you choose to obtain FreeBSD via
anonymous FTP, please try to use a site near you.</para>
@@ -76,7 +82,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ar.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ar.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.ar.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ar.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -95,22 +101,22 @@
<listitem>
<para><ulink
- URL="ftp://ftp.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.au.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.au.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.au.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.au.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.au.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.au.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp4.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.au.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp4.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.au.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -129,37 +135,37 @@
<listitem>
<para><ulink
- URL="ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp4.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp4.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp5.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp5.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp6.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp6.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp7.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp7.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp7.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp7.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -178,7 +184,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ca.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ca.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.ca.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ca.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -194,7 +200,7 @@
<listitem>
<para><ulink
- URL="ftp://sunsite.mff.cuni.cz/OS/FreeBSD">ftp://sunsite.mff.cuni.cz/OS/FreeBSD</ulink><!-- <br> --> Contact: <email>jj@sunsite.mff.cuni.cz</email>.</para>
+ URL="ftp://sunsite.mff.cuni.cz/OS/FreeBSD">ftp://sunsite.mff.cuni.cz/OS/FreeBSD</ulink> Contact: <email>jj@sunsite.mff.cuni.cz</email>.</para>
</listitem>
</itemizedlist>
@@ -213,7 +219,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.dk.freeBSD.ORG/pub/FreeBSD">ftp://ftp.dk.freeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.dk.freeBSD.ORG/pub/FreeBSD">ftp://ftp.dk.freeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -232,7 +238,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ee.freebsd.ORG/pub/FreeBSD">ftp://ftp.ee.freebsd.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.ee.freebsd.ORG/pub/FreeBSD">ftp://ftp.ee.freebsd.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -251,7 +257,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.fi.freebsd.ORG/pub/FreeBSD">ftp://ftp.fi.freebsd.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.fi.freebsd.ORG/pub/FreeBSD">ftp://ftp.fi.freebsd.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -267,7 +273,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ibp.fr/pub/FreeBSD">ftp://ftp.ibp.fr/pub/FreeBSD</ulink><!-- <br> --> Contact: <email>Remy.Card@ibp.fr</email>.</para>
+ URL="ftp://ftp.ibp.fr/pub/FreeBSD">ftp://ftp.ibp.fr/pub/FreeBSD</ulink> Contact: <email>Remy.Card@ibp.fr</email>.</para>
</listitem>
</itemizedlist>
@@ -286,37 +292,37 @@
<listitem>
<para><ulink
- URL="ftp://ftp.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp4.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp4.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp5.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp5.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp6.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp6.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp7.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp7.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp7.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp7.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -332,7 +338,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.hk.super.net/pub/FreeBSD">ftp://ftp.hk.super.net/pub/FreeBSD</ulink><!-- <br> --> Contact: <email>ftp-admin@HK.Super.NET</email>.</para>
+ URL="ftp://ftp.hk.super.net/pub/FreeBSD">ftp://ftp.hk.super.net/pub/FreeBSD</ulink> Contact: <email>ftp-admin@HK.Super.NET</email>.</para>
</listitem>
</itemizedlist>
@@ -351,7 +357,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ie.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ie.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.ie.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ie.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -370,12 +376,12 @@
<listitem>
<para><ulink
- URL="ftp://ftp.il.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.il.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.il.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.il.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.il.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.il.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.il.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.il.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -394,32 +400,32 @@
<listitem>
<para><ulink
- URL="ftp://ftp.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.jp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.jp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.jp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.jp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.jp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.jp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp4.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.jp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp4.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.jp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp5.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.jp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp5.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.jp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp6.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.jp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp6.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.jp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -438,14 +444,25 @@
<listitem>
<para><ulink
- URL="ftp://ftp.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.kr.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.kr.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.kr.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.kr.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
-
+
+ <listitem>
+ <para><ulink url="ftp://ftp3.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.kr.FreeBSD.ORG/pub/FreeBSD</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="ftp://ftp4.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.kr.FreeBSD.ORG/pub/FreeBSD</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="ftp://ftp5.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.kr.FreeBSD.ORG/pub/FreeBSD</ulink></para>
+ </listitem>
</itemizedlist>
</listitem>
@@ -462,7 +479,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.nl.freebsd.ORG/pub/FreeBSD">ftp://ftp.nl.freebsd.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.nl.freebsd.ORG/pub/FreeBSD">ftp://ftp.nl.freebsd.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -481,7 +498,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.pl.freebsd.ORG/pub/FreeBSD">ftp://ftp.pl.freebsd.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.pl.freebsd.ORG/pub/FreeBSD">ftp://ftp.pl.freebsd.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -500,12 +517,12 @@
<listitem>
<para><ulink
- URL="ftp://ftp.pt.freebsd.org/pub/FreeBSD">ftp://ftp.pt.freebsd.org/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.pt.freebsd.org/pub/FreeBSD">ftp://ftp.pt.freebsd.org/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.pt.freebsd.org/pub/FreeBSD">ftp://ftp2.pt.freebsd.org/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.pt.freebsd.org/pub/FreeBSD">ftp://ftp2.pt.freebsd.org/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -524,17 +541,17 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ru.freebsd.org/pub/FreeBSD">ftp://ftp.ru.freebsd.org/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.ru.freebsd.org/pub/FreeBSD">ftp://ftp.ru.freebsd.org/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.ru.freebsd.org/pub/FreeBSD">ftp://ftp2.ru.freebsd.org/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.ru.freebsd.org/pub/FreeBSD">ftp://ftp2.ru.freebsd.org/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.ru.freebsd.org/pub/FreeBSD">ftp://ftp3.ru.freebsd.org/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.ru.freebsd.org/pub/FreeBSD">ftp://ftp3.ru.freebsd.org/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
@@ -556,17 +573,17 @@
<listitem>
<para><ulink
- URL="ftp://ftp.za.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.za.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.za.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.za.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.za.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.za.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.za.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.za.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.za.FreeBSD.ORG/FreeBSD">ftp://ftp3.za.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.za.FreeBSD.ORG/FreeBSD">ftp://ftp3.za.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -600,7 +617,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.si.freebsd.ORG/pub/FreeBSD">ftp://ftp.si.freebsd.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.si.freebsd.ORG/pub/FreeBSD">ftp://ftp.si.freebsd.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -634,9 +651,19 @@
<listitem>
<para><ulink
- URL="ftp://ftp.se.freebsd.ORG/pub/FreeBSD">ftp://ftp.se.freebsd.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.se.freebsd.ORG/pub/FreeBSD">ftp://ftp.se.freebsd.ORG/pub/FreeBSD</ulink></para>
</listitem>
-
+
+ <listitem>
+ <para><ulink
+ URL="ftp://ftp2.se.freebsd.ORG/pub/FreeBSD">ftp://ftp2.se.freebsd.ORG/pub/FreeBSD</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ URL="ftp://ftp3.se.freebsd.ORG/pub/FreeBSD">ftp://ftp3.se.freebsd.ORG/pub/FreeBSD</ulink></para>
+ </listitem>
+
</itemizedlist>
</listitem>
@@ -653,17 +680,17 @@
<listitem>
<para><ulink
- URL="ftp://ftp.tw.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.tw.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.tw.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.tw.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.tw.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.tw.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.tw.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.tw.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.tw.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.tw.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.tw.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.tw.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -679,7 +706,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.nectec.or.th/pub/FreeBSD">ftp://ftp.nectec.or.th/pub/FreeBSD</ulink><!-- <br> --> Contact: <email>ftpadmin@ftp.nectec.or.th</email>.</para>
+ URL="ftp://ftp.nectec.or.th/pub/FreeBSD">ftp://ftp.nectec.or.th/pub/FreeBSD</ulink> Contact: <email>ftpadmin@ftp.nectec.or.th</email>.</para>
</listitem>
</itemizedlist>
@@ -695,7 +722,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ua.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ua.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --> Contact: <email>archer@lucky.net</email>.</para>
+ URL="ftp://ftp.ua.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ua.FreeBSD.ORG/pub/FreeBSD</ulink> Contact: <email>archer@lucky.net</email>.</para>
</listitem>
</itemizedlist>
@@ -714,22 +741,22 @@
<listitem>
<para><ulink
- URL="ftp://ftp.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.uk.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.uk.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.uk.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.uk.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.uk.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.uk.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp4.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.uk.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp4.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.uk.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -748,32 +775,32 @@
<listitem>
<para><ulink
- URL="ftp://ftp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp4.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp4.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp5.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp5.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp6.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp6.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -800,12 +827,12 @@
<listitem>
<para><ulink
- URL="ftp://ftp.internat.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.internat.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.internat.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.internat.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.internat.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.internat.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.internat.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.internat.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -824,7 +851,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -840,7 +867,7 @@
<listitem>
<para><ulink
- URL="ftp://nic.funet.fi/pub/unix/FreeBSD/eurocrypt">ftp://nic.funet.fi/pub/unix/FreeBSD/eurocrypt</ulink><!-- <br> --> Contact: <email>count@nic.funet.fi</email>.</para>
+ URL="ftp://nic.funet.fi/pub/unix/FreeBSD/eurocrypt">ftp://nic.funet.fi/pub/unix/FreeBSD/eurocrypt</ulink> Contact: <email>count@nic.funet.fi</email>.</para>
</listitem>
</itemizedlist>
@@ -871,7 +898,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.freebsd.org/pub/FreeBSD/CTM">ftp://ftp.freebsd.org/pub/FreeBSD/CTM</ulink><!-- <br> --></para>
+ URL="ftp://ftp.freebsd.org/pub/FreeBSD/CTM">ftp://ftp.freebsd.org/pub/FreeBSD/CTM</ulink></para>
</listitem>
</itemizedlist>
@@ -887,7 +914,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.uni-trier.de/pub/unix/systems/BSD/FreeBSD/CTM">ftp://ftp.uni-trier.de/pub/unix/systems/BSD/FreeBSD/CTM</ulink><!-- <br> --></para>
+ URL="ftp://ftp.uni-trier.de/pub/unix/systems/BSD/FreeBSD/CTM">ftp://ftp.uni-trier.de/pub/unix/systems/BSD/FreeBSD/CTM</ulink></para>
</listitem>
</itemizedlist>
@@ -904,7 +931,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.internat.freebsd.org/pub/FreeBSD/CTM">ftp://ftp.internat.freebsd.org/pub/FreeBSD/CTM</ulink><!-- <br> --></para>
+ URL="ftp://ftp.internat.freebsd.org/pub/FreeBSD/CTM">ftp://ftp.internat.freebsd.org/pub/FreeBSD/CTM</ulink></para>
</listitem>
</itemizedlist>
@@ -920,17 +947,17 @@
<listitem>
<para><ulink
- URL="ftp://ctm.tw.freebsd.org/pub/FreeBSD/CTM">ftp://ctm.tw.freebsd.org/pub/FreeBSD/CTM</ulink><!-- <br> --></para>
+ URL="ftp://ctm.tw.freebsd.org/pub/FreeBSD/CTM">ftp://ctm.tw.freebsd.org/pub/FreeBSD/CTM</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ctm2.tw.freebsd.org/pub/FreeBSD/CTM">ftp://ctm2.tw.freebsd.org/pub/FreeBSD/CTM</ulink><!-- <br> --></para>
+ URL="ftp://ctm2.tw.freebsd.org/pub/FreeBSD/CTM">ftp://ctm2.tw.freebsd.org/pub/FreeBSD/CTM</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ctm3.tw.freebsd.org/pub/freebsd/CTM">ftp://ctm3.tw.freebsd.org/pub/freebsd/CTM</ulink><!-- <br> --></para>
+ URL="ftp://ctm3.tw.freebsd.org/pub/freebsd/CTM">ftp://ctm3.tw.freebsd.org/pub/freebsd/CTM</ulink></para>
</listitem>
</itemizedlist>
@@ -1147,7 +1174,19 @@
</listitem>
</varlistentry>
-
+
+ <varlistentry>
+ <term>Poland</term>
+
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para>cvsup.pl.FreeBSD.ORG (maintainer <email>Mariusz@kam.pl</email>)</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
<varlistentry><term>Russia</term>
<listitem>
@@ -1163,6 +1202,14 @@
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>Sweden</term>
+
+ <listitem>
+ <para>cvsup.se.FreeBSD.ORG (maintainer <email>pantzer@ludd.luth.se</email>)</para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>Slovak Republic</term>
@@ -1338,6 +1385,45 @@
</sect1>
+
+ <sect1 id="mirrors-afs">
+ <title>AFS Sites</title>
+
+ <para>AFS servers for FreeBSD are running at the following sites;</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Sweden</term>
+
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para><hostid role="fqdn">stacken.kth.se</hostid>, Stacken
+ Computer Club, KTH, Sweden</para>
+ </listitem>
+
+ <listitem>
+ <para><hostid role="ipaddr">130.237.234.3</hostid>, <hostid
+ role="fqdn">milko.stacken.kth.se</hostid></para>
+ </listitem>
+
+ <listitem>
+ <para><hostid role="ipaddr">130.237.234.43</hostid>, <hostid
+ role="fqdn">hot.stacken.kth.se</hostid></para>
+ </listitem>
+
+ <listitem>
+ <para><hostid role="ipaddr">130.237.234.44</hostid>, <hostid role="fqdn">dog.stacken.kth.se</hostid></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Maintainer <email>ftp@stacken.kth.se</email></para>
+ </listitem>
+
+
+ </varlistentry>
+ </variablelist>
+ </sect1>
</chapter>
@@ -1347,9 +1433,7 @@
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/pgpkeys/chapter.sgml b/en_US.ISO8859-1/books/handbook/pgpkeys/chapter.sgml
index bb512fb1bc..cb1b9b9d1f 100644
--- a/en_US.ISO8859-1/books/handbook/pgpkeys/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/pgpkeys/chapter.sgml
@@ -503,9 +503,7 @@ vvlVQ0UbcR0N2+5F6Mb5GqrXZpIesn7jFJpkQKPU
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/policies/chapter.sgml b/en_US.ISO8859-1/books/handbook/policies/chapter.sgml
index cd77ca0ba2..500b2b1d46 100644
--- a/en_US.ISO8859-1/books/handbook/policies/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/policies/chapter.sgml
@@ -301,9 +301,7 @@ obrien@freebsd.org - 30 March 1997</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/ports/chapter.sgml b/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
index aa5d962c4a..092d021ad9 100644
--- a/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
@@ -88,7 +88,7 @@
<title>How Does the Ports Collection Work?</title>
<para>Programs are typically distributed on the Internet as a
- <xref linkend="ports-tarball" remap="tarball"> consisting of a
+ <link linkend="ports-tarball">tarball</link> consisting of a
Makefile and the source code for the program and usually some
instructions (which are unfortunately not always as instructive as
they could be), with perhaps a configuration script.</para>
@@ -100,18 +100,18 @@
from the source.</para>
<para>FreeBSD ports still use the tarball mechanism, but use a
- <xref linkend="ports-skeleton" remap="skeleton"> to hold the
+ <link linkend="ports-skeleton">skeleton</link> to hold the
"knowledge" of how to get the program working on FreeBSD,
rather than expecting the user to be able to work it out. They also
supply their own customised
- <xref linkend="ports-makefile" remap="Makefile">, so that almost
+ <link linkend="ports-makefile">Makefile</link>, so that almost
every port can be built in the same way.</para>
<para>If you look at a port skeleton (either on <ulink
URL="file://localhost/usr/ports/devel/ElectricFence">your FreeBSD
system</ulink> or <ulink
- URL="ftp://ftp.freebsd.org/pub/FreeBSD/ports/devel/ElectricFence">the FTP site</ulink>) and expect to find all sorts of pointy-headed rocket science lurking there, you may be disappointed by the one or two rather unexciting-looking files and directories you find there. (We will discuss in a minute how to go about <xref
- linkend="ports-getting" remap="Getting a port">).</para>
+ URL="ftp://ftp.freebsd.org/pub/FreeBSD/ports/devel/ElectricFence">the FTP site</ulink>) and expect to find all sorts of pointy-headed rocket science lurking there, you may be disappointed by the one or two rather unexciting-looking files and directories you find there. (We will discuss in a minute how to go about <link
+ linkend="ports-getting">Getting a port</link>).</para>
<para>“How on earth can this do anything?” I hear you cry. “There
is no source code there!”</para>
@@ -171,13 +171,12 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<procedure>
<step>
- <para>Locate the source code <xref linkend="ports-tarball"
- remap="tarball."> If it is not available locally, try to
+ <para>Locate the source code <link linkend="ports-tarball">tarball.</link> If it is not available locally, try to
grab it from an FTP site.</para>
</step>
<step>
- <para>Run a <xref linkend="ports-checksum" remap="checksum">
+ <para>Run a <link linkend="ports-checksum">checksum</link>
test on the tarball to make sure it has not been tampered
with, accidentally truncated, downloaded in ASCII mode, struck
by neutrinos while in transit, etc.</para>
@@ -188,7 +187,7 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
</step>
<step>
- <para>Apply any <xref linkend="ports-patch" remap="patches">
+ <para>Apply any <link linkend="ports-patch">patches</link>
needed to get the source to compile and run under FreeBSD.</para>
</step>
@@ -212,8 +211,8 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<step>
<para>Register the installation in a database. This means that,
- if you do not like the program, you can cleanly <xref
- linkend="ports-remove" remap="remove"> all traces of it from
+ if you do not like the program, you can cleanly <link
+ linkend="ports-remove">remove</link> all traces of it from
your system.</para>
</step>
@@ -230,85 +229,28 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<title>Getting a FreeBSD Port</title>
<para>There are two ways of getting hold of the FreeBSD port for a
- program. One requires a <xref linkend="ports-cd" remap="FreeBSD
- CDROM">, the other involves using an <xref linkend="ports-inet"
- remap="Internet Connection."></para>
+ program. One requires a <link linkend="ports-cd">FreeBSD
+ CDROM</link>, the other involves using an <link linkend="ports-inet">Internet Connection.</link></para>
<sect2 id="ports-cd">
<title>Compiling ports from CDROM</title>
-
- <para>If you answered yes to the question “Do you want to link the
- ports collection to your CDROM” during the FreeBSD installation,
- the initial setting up will already have been done for you.</para>
-
- <para>If not, make sure the <emphasis>FreeBSD</emphasis> CDROM is in
- the drive and mounted on, say, <filename>/cdrom</filename>. Then
- do</para>
-
- <informalexample>
- <screen>&prompt.root; <userinput>mkdir /usr/ports</userinput>
-&prompt.root; <userinput>cd /usr/ports</userinput>
-&prompt.root; <userinput>ln -s /cdrom/ports/distfiles distfiles</userinput></screen>
- </informalexample>
-
- <para>to enable the ports make mechanism to find the tarballs (it
- expects to find them in <filename>/usr/ports/distfiles</filename>,
- which is why we sym-linked the CDROM's tarball directory to that
- directory).</para>
-
- <para>Now, suppose you want to install the gnats program from the
- databases directory. Here is how to do it:-</para>
-
- <informalexample>
- <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
-&prompt.root; <userinput>mkdir databases</userinput>
-&prompt.root; <userinput>cp -R /cdrom/ports/databases/gnats databases</userinput>
-&prompt.root; <userinput>cd databases/gnats</userinput>
-&prompt.root; <userinput>make install</userinput></screen>
- </informalexample>
-
- <para>Or if you are a serious database user and you want to compare
- all the ones available in the Ports collection, do</para>
-
- <informalexample>
- <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
-&prompt.root; <userinput>cp -R /cdrom/ports/databases .</userinput>
-&prompt.root; <userinput>cd databases</userinput>
-&prompt.root; <userinput>make install</userinput></screen>
- </informalexample>
-
- <para>(yes, that really is a dot on its own after the <command>cp</command> command and
- not a mistake. It is Unix-ese for “the current
- directory”) and the ports make mechanism will automatically compile and
- install all the ports in the databases directory for you!</para>
-
- <para>If you do not like this method, here is a completely different
- way of doing it:-</para>
-
- <para>Create a “link tree” to it using the
- <citerefentry><refentrytitle>lndir</refentrytitle><manvolnum>1</manvolnum></citerefentry> command that comes with the
- <emphasis>XFree86</emphasis> distribution. Find a location with
- some free space, create a directory there and then cd to it. Then
- invoke the <citerefentry><refentrytitle>lndir</refentrytitle><manvolnum>1</manvolnum></citerefentry> command with the full
- pathname of the <filename>ports</filename> directory on the CDROM as the first
- argument and . (the current directory) as the second. This might
- be, for example, something like:</para>
- <informalexample>
- <screen>&prompt.root; <userinput>lndir /cdrom/ports .</userinput></screen>
- </informalexample>
-
- <para>Then you can build ports directly off the CDROM by building
- them in the link tree you have created.</para>
-
- <para>Note that there are some ports for which we cannot provide the
+ <para>Assuming that your FreeBSD CDROM is in the drive and mounted on
+ <filename>/cdrom</filename> (and the mount point
+ <emphasis>must</emphasis> be <filename>/cdrom</filename>), you should
+ then be able to build ports just as you normally do and the port
+ collection's built in search path should find the tarballs in
+ <filename>/cdrom/ports/distfiles/</filename> (if they exist there)
+ rather than downloading them over the net.</para>
+
+ <note>
+ <para>There are some ports for which we cannot provide the
original source in the CDROM due to licensing limitations. In
- that case, you will need to look at the section on <xref
- linkend="ports-inet"
- remap="Compiling ports using an Internet connection."></para>
-
- </sect2>
+ that case, you will need to look at the section on <link
+ linkend="ports-inet">Compiling ports using an Internet connection.</link></para>
+ </note>
+ </sect2>
<sect2 id="ports-inet">
<title>Compiling ports from the Internet</title>
@@ -316,13 +258,20 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<para>If you do not have a CDROM, or you want to make sure you get
the very latest version of the port you want, you will need to
download the
- <xref linkend="ports-skeleton" remap="skeleton"> for the port. Now
+ <link linkend="ports-skeleton">skeleton</link> for the port. Now
this might sound like rather a fiddly job full of pitfalls, but
it is actually very easy.</para>
-
- <para>The key to it is that the FreeBSD FTP server can create
+
+ <para>First, if you are running a release version of FreeBSD, make
+ sure you get the appropriate “upgradekiet” for your
+ replease from the <ulink url="http://www.freebsd.org/ports/">ports
+ web page</ulink>. These packages include files that have been
+ updated since the release that you may need to compile new
+ ports.</para>
+
+ <para>The key to the skeletons is that the FreeBSD FTP server can create
on-the-fly
- <xref linkend="ports-tarball" remap="tarballs"> for you. Here is
+ <link linkend="ports-tarball">tarballs</link> for you. Here is
how it works, with the gnats program in the databases directory as
an example (the bits in square brackets are comments. Do not type
them in if you are trying this yourself!):-</para>
@@ -347,14 +296,12 @@ password. Remember to use binary (also known as image) mode!]
<para>What happened here? We connected to the FTP server in the
usual way and went to its <filename>databases</filename> sub-directory. When we gave it
- the command <command>get gnats.tar</command>, the FTP server <xref
- linkend="ports-tarball"
- remap="tarred"> up the gnats directory for us.</para>
+ the command <command>get gnats.tar</command>, the FTP server <link
+ linkend="ports-tarball">tarred</link> up the gnats directory for us.</para>
<para>We then extracted the gnats skeleton and went into the gnats
- directory to build the port. As we explained <xref
- linkend="ports-fetch"
- remap="earlier">, the make process noticed we did not have a
+ directory to build the port. As we explained <link
+ linkend="ports-fetch">earlier</link>, the make process noticed we did not have a
copy of the source locally, so it fetched one before extracting,
patching and building it.</para>
@@ -436,16 +383,17 @@ do-install:
the benefit of human readers (as in most Unix script
files).</para>
- <para><literal>DISTNAME</literal> specifies the name of the <xref
- linkend="ports-tarball" remap="tarball">, but without the
+ <para><literal>DISTNAME</literal> specifies the name of the <link
+ linkend="ports-tarball">tarball</link>, but without the
extension.</para>
<para><literal>CATEGORIES</literal> states what kind of program this is. In
- this case, a utility for developers.</para>
+ this case, a utility for developers. See the <link
+ linkend="porting-categories">categories</link> section of this
+ handbook for a complete list.</para>
<para><literal>MASTER_SITES</literal> is the URL(s) of the master FTP site,
- which is used to retrieve the <xref linkend="ports-tarball"
- remap="tarball"> if it is not available on the local system.
+ which is used to retrieve the <link linkend="ports-tarball">tarball</link> if it is not available on the local system.
This is a site which is regarded as reputable, and is normally the
one from which the program is officially distributed (in so far
as any software is "officially" distributed on the
@@ -477,8 +425,7 @@ do-install:
<sect2>
<title>The <filename>files</filename> directory</title>
- <para>The file containing the <xref linkend="ports-checksum"
- remap="checksum"> for the port is called
+ <para>The file containing the <link linkend="ports-checksum">checksum</link> for the port is called
<filename>md5</filename>, after the MD5 algorithm used for ports
checksums. It lives in a directory with the slightly confusing
name of <filename>files</filename>.</para>
@@ -491,8 +438,7 @@ do-install:
<sect2>
<title>The <filename>patches</filename> directory</title>
- <para>This directory contains the <xref linkend="ports-patch"
- remap="patches"> needed to make everything work properly under
+ <para>This directory contains the <link linkend="ports-patch">patches</link> needed to make everything work properly under
FreeBSD.</para>
</sect2>
@@ -536,7 +482,7 @@ do-install:
<listitem>
<para>Fix it yourself. Technical details on how ports work can
be found in
- <xref linkend="porting" remap="Porting applications."></para>
+ <link linkend="porting">Porting applications.</link></para>
</listitem>
<listitem>
@@ -568,15 +514,6 @@ do-install:
</sect1>
- <sect1>
- <title>I Want to Make a Port!</title>
-
- <para>Great! Please see the <xref linkend="porting"
- remap="guidelines"> for detailed instructions on how to do
- this.</para>
-
- </sect1>
-
<sect1>
<title>Some Questions and Answers</title>
@@ -707,8 +644,7 @@ do-install:
</listitem>
<listitem>
- <para>Q. I did what you said for <xref linkend="ports-cd"
- remap="compiling ports from a CDROM"> and it worked great
+ <para>Q. I did what you said for <link linkend="ports-cd">compiling ports from a CDROM</link> and it worked great
until I tried to install the kermit port:-</para>
<informalexample>
@@ -884,7 +820,16 @@ do-install:
<para>Q. There are so many ports it is hard to find the one I
want. Is there a list anywhere of what ports are available?</para>
- <para>A. Look in the <filename>INDEX</filename> file in <filename>/usr/ports</filename>.</para>
+ <para>A. Look in the <filename>INDEX</filename> file in
+ <filename>/usr/ports</filename>. If you would like to search the
+ ports collection for a keyword, you can do that too. For example,
+ you can find ports relevant to the LISP programming language
+ using:</para>
+
+ <informalexample>
+ <screen>&prompt.user; <userinput>cd /usr/ports</userinput>
+&prompt.user; <userinput>make search key=lisp</userinput></screen>
+ </informalexample>
</listitem>
<listitem>
@@ -1044,6 +989,3524 @@ grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arc
</sect1>
+
+ <sect1 id="porting">
+ <title>Making a port yourself</title>
+
+ <para><emphasis>Contributed by &a.jkh;, &a.gpalmer;, &a.asami;
+ &a.obrien; and &a.hoek;. 28 August 1996.</emphasis></para>
+
+ <para>So, now you are interested in making your own port?
+ Great!</para>
+
+ <para>What follows are some guidelines for creating a new port for
+ FreeBSD. The bulk of the work is done by
+ <filename>/usr/share/mk/bsd.port.mk</filename>, which all port
+ Makefiles include. Please refer to that file for more details on
+ the inner workings of the ports collection. Even if you don't
+ hack Makefiles daily, it is well commented, and you will still
+ gain much knowledge from it.</para>
+
+ <note>
+ <para>Only a fraction of the overridable variables
+ (<makevar><replaceable>VAR</replaceable></makevar>) are mentioned
+ in this document. Most (if not all) are documented at the start of
+ <filename>bsd.port.mk</filename>. This file users a non-standard
+ tab setting. <application>Emacs</application> and
+ <application>Vim</application> should recognise the setting on
+ loading the file. <command>vi</command> or <command>ex</command>
+ can be set to use the correct value by typing <command>:set
+ tabstop=4</command> once the file has been loaded.</para>
+ </note>
+
+ <sect2>
+ <title>Quick Porting</title>
+
+ <para>This section tells you how to do a quick port. In many
+ cases, it is not enough, but we will see.</para>
+
+ <para>First, get the original tarball and put it into <makevar>DISTDIR</makevar>, which defaults to
+ <filename>/usr/ports/distfiles</filename>.</para>
+
+ <note>
+ <para>The following assumes that the software compiled
+ out-of-the-box, i.e., there was absolutely no change required
+ for the port to work on your FreeBSD box. If you needed to
+ change something, you will have to refer to the next section
+ too.</para>
+ </note>
+
+ <sect3>
+ <title>Writing the <filename>Makefile</filename></title>
+
+ <para>The minimal <filename>Makefile</filename> would
+ look something like this:</para>
+
+ <programlisting>
+# New ports collection makefile for: oneko
+# Version required: 1.1b
+# Date created: 5 December 1994
+# Whom: asami
+#
+# $Id$
+#
+
+DISTNAME= oneko-1.1b
+CATEGORIES= games
+MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
+
+MAINTAINER= asami@FreeBSD.ORG
+
+MAN1= oneko.1
+MANCOMPRESSED= yes
+USE_IMAKE= yes
+
+.include <bsd.port.mk></programlisting>
+
+ <para>See if you can figure it out. Do not worry about the
+ contents of the <literal>$Id$</literal>
+ line, it will be filled in automatically by CVS when the port
+ is imported to our main ports tree. You can find a more
+ detailed example in the <link
+ linkend="porting-samplem">sample Makefile</link>
+ section.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Writing the description files</title>
+
+ <para>There are three description files that are
+ required for any port, whether they actually package or not.
+ They are <filename>COMMENT</filename>,
+ <filename>DESCR</filename>, and <filename>PLIST</filename>,
+ and reside in the <filename>pkg</filename>
+ subdirectory.</para>
+
+
+ <sect4>
+ <title><filename>COMMENT</filename></title>
+
+ <para>This is the one-line description of the port.
+ <emphasis>Please</emphasis> do not include the package name (or version
+ number of the software) in the comment. Here is
+ an example:</para>
+
+ <programlisting>
+A cat chasing a mouse all over the screen.</programlisting>
+
+ </sect4>
+
+ <sect4>
+ <title><filename>DESCR</filename></title>
+
+ <para>This is a longer description of the port. One to a few
+ paragraphs concisely explaining what the port does is
+ sufficient.</para>
+
+ <note>
+ <para>This is <emphasis>not</emphasis> a manual or an
+ in-depth description on how to use or compile the port!
+ <emphasis>Please be careful if you are copying from the
+ <filename>README</filename> or manpage</emphasis>; too often
+ they are not a concise description of the port or are in an
+ awkward format (e.g., manpages have justified spacing). If the
+ ported software has an official WWW homepage, you should list
+ it here.</para>
+ </note>
+
+ <para>It is recommended that you sign the name at the end of
+ this file, as in:</para>
+
+ <programlisting>
+This is a port of oneko, in which a cat chases a poor mouse all over
+the screen.
+ :
+(etc.)
+
+http://www.oneko.org/
+
+- Satoshi
+asami@cs.berkeley.edu</programlisting>
+
+ </sect4>
+
+ <sect4>
+ <title><filename>PLIST</filename></title>
+
+ <para>This file lists all the files installed by the port. It
+ is also called the “packing list” because the package is
+ generated by packing the files listed here. The pathnames
+ are relative to the installation prefix (usually
+ <filename>/usr/local</filename> or
+ <filename>/usr/X11R6</filename>). If you are using the
+ <makevar>MAN<replaceable>n</replaceable></makevar> variables (as
+ you should be), do not list any manpages here.</para>
+
+ <para>Here is a small example:</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>Refer to the <citerefentry><refentrytitle>pkg_create</refentrytitle><manvolnum>1</manvolnum></citerefentry> man page
+ for details on the packing list.</para>
+
+ <note>
+ <para>You should list all the files, but not the name
+ directories, in the list. Also, if the port creates
+ directories for itself during installtion, make sure to add
+ <literal>@dirrm</literal> lines as necessary to remove them
+ when the port is deleted.</para>
+
+ <para>It is recommended that you keep all the filenames in
+ this file sorted alphabetically. It will make verifying the
+ changes when you upgrade the port much easier.</para>
+ </note>
+ </sect4>
+ </sect3>
+
+ <sect3>
+ <title>Creating the checksum file</title>
+
+ <para>Just type <command>make makesum</command>.
+ The ports make rules will automatically generate the file
+ <filename>files/md5</filename>.</para>
+
+ </sect3>
+
+ <sect3 id="porting-testing">
+ <title>Testing the port</title>
+
+ <para>You should make sure that the port rules do exactly what
+ you want it to do, including packaging up the port. These are
+ the important points you need to verify.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename>PLIST</filename> does not contain anything not
+ installed by your port</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>PLIST</filename> contains everything that is
+ installed by your port</para>
+ </listitem>
+
+ <listitem>
+ <para>Your port can be installed multiple times using the
+ <maketarget>reinstall</maketarget> target</para>
+ </listitem>
+
+ <listitem>
+ <para>Your port <link linkend="porting-cleaning">cleans
+ up</link> after itself upon deinstall</para>
+ </listitem>
+ </itemizedlist>
+
+ <procedure>
+ <title>Recommended test ordering</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 `make package-name`</command></para>
+ </step>
+
+ <step>
+ <para><command>make deinstall</command></para>
+ </step>
+
+ <step>
+ <para><command>make reinstall</command></para>
+ </step>
+
+ <step>
+ <para><command>make package</command></para>
+ </step>
+ </procedure>
+
+ <para>Make sure that there aren't any warnings issued in any of
+ the <maketarget>package</maketarget> and
+ <maketarget>deinstall</maketarget> stages, After step 3, check
+ to see if all the new directories are correctly deleted. Also,
+ try using the software after step 4, to ensure that is works
+ correctly when installed from a package.</para>
+ </sect3>
+
+ <sect3 id="porting-portlint">
+ <title>Checking your port with <command>portlint</command></title>
+
+ <para>Please use <command>portlint</command> to see if your port
+ conforms to our guidelines. The <command>portlint</command>
+ program is part of the ports collection. In particular, your may
+ want to check if the <link
+ linkend="porting-samplem">Makefile</link> is in the right
+ shape and the <link linkend="porting-pkgname">package</link> is
+ named appropriately.</para>
+ </sect3>
+
+ <sect3 id="porting-submitting">
+ <title>Submitting the port</title>
+
+ <para>First, make sure you have read the <link
+ linkend="porting-dads">Do's and Dont's</link> section.</para>
+
+ <para>Now that you are happy with your port, the only thing
+ remaining is to put it in the main FreeBSD ports tree and make
+ everybody else happy about it too. We do not need your
+ <filename>work</filename> directory or the
+ <filename>pkgname.tgz</filename> package, so delete them
+ now. Next, simply include the output of <command>shar `find
+ port_dir`</command> in a bug report and send it with the
+ <citerefentry>
+ <refentrytitle>send-pr</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry> program (see <link linkend="contrib-general">Bug
+ Reports and General Commentary</link> for more information
+ about <citerefentry>
+ <refentrytitle>send-pr</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>. If the uncompressed port is larger than
+ 20KB, you should compress it into a tarfile and use <citerefentry>
+ <refentrytitle>uuencode</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry> before including it in the bug report (uuencoded
+ tarfiles are acceptable even if the bug report is smaller than
+ 20KB but are not preferred). Be sure to classify the bug report as
+ category <literal>ports</literal> and class
+ <literal>change-request</literal>. (Do not mark the report
+ <literal>confidential</literal>!)</para>
+
+ <para>One more time, <emphasis>do not include the original source
+ distfile, the <filename>work</filename> directory, or the
+ package you built with <command>make
+ package</command></emphasis>.</para>
+
+ <note>
+ <para>In the past, we asked you to upload new port submissions
+ in our ftp site (<hostid
+ role="fqdn">ftp.freebsd.org</hostid>). This is no longer
+ recommended as read access is turned off on that
+ <filename>incoming/</filename> directory of that site due to
+ the large amount of pirated software showing up there.</para>
+ </note>
+
+ <para>We will look at your port,
+ get back to you if necessary, and put it in the
+ tree. Your name will also appear in the list of “Additional
+ FreeBSD contributors” on the FreeBSD Handbook and other files.
+ Isn't that great?!? <!-- smiley -->:)</para>
+
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Slow Porting</title>
+
+ <para>Ok, so it was not that simple, and the port required some
+ modifications to get it to work. In this section, we will
+ explain, step by step, how to modify it to get it to work with
+ the ports paradigm.</para>
+
+
+ <sect3>
+ <title>How things work</title>
+
+ <para>First, this is the sequence of events which occurs when
+ the user first types <command>make</command> in
+ your port's directory, and you may find that having
+ <filename>bsd.port.mk</filename> in another window while you
+ read this really helps to understand it.</para>
+
+ <para>But do not worry if you do not really understand what
+ <filename>bsd.port.mk</filename> is doing, not many people
+ do... <!-- smiley --><emphasis>:></emphasis></para>
+
+
+ <procedure>
+
+ <step>
+ <para>The <maketarget>fetch</maketarget> target is run. The <maketarget>fetch</maketarget> target is
+ responsible for making sure that the tarball exists
+ locally in <makevar>DISTDIR</makevar>.
+ If <maketarget>fetch</maketarget> cannot find the required files in <makevar>DISTDIR</makevar> it will look up the
+ URL <makevar>MASTER_SITES</makevar>,
+ which is set in the Makefile, as well as our main ftp
+ site at <ulink
+ URL="ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/">ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/,</ulink> where we put sanctioned distfiles as backup. It will then attempt to fetch the named distribution file with <makevar>FETCH</makevar>, assuming that the requesting site has direct access to the Internet. If that succeeds, it will save the file in <makevar>DISTDIR</makevar> for future use and proceed.</para>
+ </step>
+
+ <step>
+ <para>The <maketarget>extract</maketarget> target is run. It looks for your port's
+ distribution file (typically a gzip'd tarball) in <makevar>DISTDIR</makevar> and unpacks it into a temporary subdirectory
+ specified by <makevar>WRKDIR</makevar>
+ (defaults to <filename>work</filename>).</para>
+ </step>
+
+ <step>
+ <para>The <maketarget>patch</maketarget> target is run. First, any patches defined
+ in <makevar>PATCHFILES</makevar> are
+ applied. Second, if any patches are found in <makevar>PATCHDIR</makevar> (defaults to the
+ <filename>patches</filename> subdirectory), they are
+ applied at this time in alphabetical order.</para>
+ </step>
+
+ <step>
+ <para>The <maketarget>configure</maketarget> target is run. This can do any one of
+ many different things.</para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>If it exists,
+ <filename>scripts/configure</filename> is run.</para>
+ </listitem>
+
+ <listitem>
+ <para>If <makevar>HAS_CONFIGURE</makevar> or
+ <makevar>GNU_CONFIGURE</makevar>
+ is set,
+ <filename><makevar>WRKSRC</makevar>/configure</filename> is
+ run.</para>
+ </listitem>
+
+ <listitem>
+ <para>If <makevar>USE_IMAKE</makevar> is set,
+ <makevar>XMKMF</makevar>
+ (default: <command>xmkmf
+ -a</command>) is run.</para>
+ </listitem>
+
+ </orderedlist>
+
+ </step>
+
+ <step>
+ <para>The <maketarget>build</maketarget> target is run. This is responsible for
+ descending into the ports' private working directory
+ (<makevar>WRKSRC</makevar>) and
+ building it. If <makevar>USE_GMAKE</makevar> is set, GNU
+ <command>make</command> will be used,
+ otherwise the system <command>make</command>
+ will be used.</para>
+ </step>
+
+ </procedure>
+
+
+ <para>The above are the default actions. In addition, you can
+ define targets <maketarget>pre-<replaceable>something</replaceable></maketarget> or <maketarget>post-<replaceable>something</replaceable></maketarget>, or put scripts
+ with those names, in the <filename>scripts</filename>
+ subdirectory, and they will be run before or after the default
+ actions are done.</para>
+
+ <para>For example, if you have a <maketarget>post-extract</maketarget> target defined in your
+ Makefile, and a file <filename>pre-build</filename> in the
+ <filename>scripts</filename> subdirectory, the
+ <maketarget>post-extract</maketarget> target will be
+ called after the regular extraction actions, and the
+ <filename>pre-build</filename> script will be executed before
+ the default build rules are done. It is recommended that you
+ use <filename>Makefile</filename> targets if the actions are
+ simple enough, because it will be easier for someone to figure
+ out what kind of non-default action the port requires.</para>
+
+ <para>The default actions are done by the
+ <filename>bsd.port.mk</filename> targets <maketarget>do-<replaceable>something</replaceable></maketarget>. For example, the
+ commands to extract a port are in the target <maketarget>do-extract</maketarget>. If you are not happy with
+ the default target, you can fix it by redefining the
+ <maketarget>do-<replaceable>something</replaceable></maketarget> target in
+ your <filename>Makefile</filename>.</para>
+
+ <note>
+ <para>The “main” targets (e.g., <maketarget>extract</maketarget>, <maketarget>configure</maketarget>, etc.) do nothing more than
+ make sure all the stages up to that one is completed and
+ call the real targets or scripts, and they are not intended
+ to be changed. If you want to fix the extraction, fix
+ <maketarget>do-extract</maketarget>, but never ever
+ touch <maketarget>extract</maketarget>!</para>
+ </note>
+
+ <para>Now that you understand what goes on when the user types
+ <command>make</command>, let us go through the
+ recommended steps to create the perfect port.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Getting the original sources</title>
+
+ <para>Get the original sources (normally) as a compressed
+ tarball (<filename><replaceable>foo</replaceable>.tar.gz</filename> or
+ <filename><replaceable>foo</replaceable>.tar.Z</filename>) and copy it into
+ <makevar>DISTDIR</makevar>. Always use
+ <emphasis>mainstream</emphasis> sources when and where you
+ can.</para>
+
+ <para>If you cannot find a ftp/http site that is well-connected
+ to the net, or can only find sites that have irritatingly
+ non-standard formats, you might want to put a copy on a
+ reliable ftp or http server that you control (e.g., your home
+ page). Make sure you set <makevar>MASTER_SITES</makevar> to
+ reflect your choice.</para>
+
+ <para>If you
+ cannot find somewhere convenient and reliable to put the distfile
+ (if you are a FreeBSD committer, you can just put it in your
+ <filename>public_html/</filename> directory on
+ <hostid>freefall</hostid>),
+ we can “house” it ourselves by putting
+ it on <filename>ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/LOCAL_PORTS/</filename> as the last resort. Please refer to this
+ location as <makevar>MASTER_SITE_LOCAL</makevar>. Send mail to
+ the &a.ports;if you are not sure what to do.</para>
+
+ <para>If your port's distfile changes all the time for no good
+ reason, consider putting the distfile in your home page and
+ listing it as the first <makevar>MASTER_SITES</makevar>. This
+ will prevent users from getting <errorname>checksum
+ mismatch</errorname> errors, and also reduce the workload of
+ maintainers of our ftp site. Also, if there isonly one master
+ site for the port, it is recommended that you house a backup at
+ your site and list it as the second
+ <makevar>MASTER_SITES</makevar>.</para>
+
+ <para>If your port requires some additional `patches' that are
+ available on the Internet, fetch them too and put them in
+ <makevar>DISTDIR</makevar>. Do not worry if
+ they come from site other than where you got the main source
+ tarball, we have a way to handle these situations (see the
+ description of <link
+ linkend="porting-patchfiles">PATCHFILES</link> below).</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Modifying the port</title>
+
+ <para>Unpack a copy of the tarball in a private directory and
+ make whatever changes are necessary to get the port to compile
+ properly under the current version of FreeBSD. Keep
+ <emphasis>careful track</emphasis> of everything you do, as
+ you will be automating the process shortly. Everything,
+ including the deletion, addition or modification of files
+ should be doable using an automated script or patch file when
+ your port is finished.</para>
+
+ <para>If your port requires significant user
+ interaction/customization to compile or install, you should
+ take a look at one of Larry Wall's classic <application>Configure</application> scripts
+ and perhaps do something similar yourself. The goal of the
+ new ports collection is to make each port as “plug-and-play”
+ as possible for the end-user while using a minimum of disk
+ space.</para>
+
+ <note>
+ <para>Unless explicitly stated, patch files, scripts, and
+ other files you have created and contributed to the FreeBSD
+ ports collection are assumed to be covered by the standard
+ BSD copyright conditions.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>Patching</title>
+
+ <para>In the preparation of the port, files that have been added
+ or changed can be picked up with a recursive diff for later
+ feeding to patch. Each set of patches you wish to apply
+ should be collected into a file named
+ <filename>patch-<replaceable>xx</replaceable></filename> where
+ <replaceable>xx</replaceable> denotes the sequence in which
+ the patches will be applied — these are done in
+ <emphasis>alphabetical order</emphasis>, thus
+ <literal>aa</literal> first, <literal>ab</literal> second and so on. These files
+ should be stored in <makevar>PATCHDIR</makevar>, from where they will be
+ automatically applied. All patches should be relative to
+ <makevar>WRKSRC</makevar> (generally the
+ directory your port's tarball unpacks itself into, that being
+ where the build is done). To make fixes and upgrades easier,
+ you should avoid having more than one patch fix the same file
+ (e.g., <filename>patch-aa</filename> and <filename>patch-ab</filename> both changing <filename><makevar>WRKSRC</makevar>/foobar.c</filename>).</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Configuring</title>
+
+ <para>Include any additional customization commands to your
+ <filename>configure</filename> script and save it in the
+ <filename>scripts</filename> subdirectory. As mentioned
+ above, you can also do this as <filename>Makefile</filename>
+ targets and/or scripts with the name
+ <filename>pre-configure</filename> or
+ <filename>post-configure</filename>.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Handling user input</title>
+
+ <para>If your port requires user input to build, configure or
+ install, then set <makevar>IS_INTERACTIVE</makevar> in your
+ Makefile. This will allow “overnight builds” to skip your port
+ if the user sets the variable <envar>BATCH</envar> in his
+ environment (and if the user sets the variable
+ <envar>INTERACTIVE</envar>, then <emphasis>only</emphasis>
+ those ports requiring interaction are built).</para>
+
+ <para>It is also recommended that if there are reasonable default
+ answers to the questions, you check the
+ <makevar>PACKAGE_BUILDING</makevar> variable and turn off the
+ interactive script when it is set. This will allow us to build
+ the packages for CD-ROMs and ftp.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Configuring the Makefile</title>
+
+ <para>Configuring the Makefile is pretty simple, and again we
+ suggest that you look at existing examples before starting.
+ Also, there is a <link linkend="porting-samplem">sample
+ Makefile</link> in this handbook, so take a look and please follow
+ the ordering of variables and sections in that template to make
+ your port easier for others to read.</para>
+
+ <para>Now, consider the following problems in sequence as you
+ design your new Makefile:</para>
+
+
+ <sect3>
+ <title>The original source</title>
+
+ <para>Does it live in <makevar>DISTDIR</makevar> as a standard gzip'd
+ tarball? If so, you can go on to the next step. If not, you
+ should look at overriding any of the <makevar>EXTRACT_CMD</makevar>, <makevar>EXTRACT_BEFORE_ARGS</makevar>, <makevar>EXTRACT_AFTER_ARGS</makevar>, <makevar>EXTRACT_SUFX</makevar>, or <makevar>DISTFILES</makevar> variables, depending on
+ how alien a format your port's distribution file is. (The
+ most common case is <literal>EXTRACT_SUFX=.tar.Z</literal>,
+ when the tarball is condensed by regular compress, not
+ gzip.)</para>
+
+ <para>In the worst case, you can simply create your own
+ <maketarget>do-extract</maketarget> target to override
+ the default, though this should be rarely, if ever,
+ necessary.</para>
+
+ </sect3>
+
+ <sect3>
+ <title><makevar>DISTNAME</makevar></title>
+
+ <para>You should set <makevar>DISTNAME</makevar> to be the base name of
+ your port. The default rules expect the distribution file
+ list (<makevar>DISTFILES</makevar>) to be
+ named <makevar>DISTNAME</makevar><makevar>EXTRACT_SUFX</makevar> which, if it is a normal tarball, is going to be
+ something like <literal>foozolix-1.0.tar.gz</literal> for a setting of <literal>DISTNAME=foozolix-1.0</literal>.</para>
+
+ <para>The default rules also expect the tarball(s) to extract
+ into a subdirectory called
+ <filename>work/<makevar>DISTNAME</makevar></filename>, e.g. <filename>work/foozolix-1.0/</filename>.</para>
+
+ <para>All this behavior can be overridden, of course; it simply
+ represents the most common time-saving defaults. For a port
+ requiring multiple distribution files, simply set <makevar>DISTFILES</makevar> explicitly. If only a
+ subset of <makevar>DISTFILES</makevar> are
+ actual extractable archives, then set them up in <makevar>EXTRACT_ONLY</makevar>, which will override
+ the <makevar>DISTFILES</makevar> list when
+ it comes to extraction, and the rest will be just left in
+ <makevar>DISTDIR</makevar> for later
+ use.</para>
+
+ </sect3>
+
+ <sect3>
+ <title><makevar>PKGNAME</makevar></title>
+
+ <para>If <makevar>DISTNAME</makevar> does not conform to our <link
+ linkend="porting-pkgname">guidelines for a good package
+ name</link>, you should set the <makevar>PKGNAME</makevar>
+ variable to something better. See the abovementioned guidelines
+ for more details.</para>
+ </sect3>
+
+ <sect3>
+ <title><makevar>CATEGORIES</makevar></title>
+
+ <para>When a package is created, it is put under
+ <filename>/usr/ports/packages/All</filename> and links are
+ made from one or more subdirectories of
+ <filename>/usr/ports/packages</filename>. The names of these
+ subdirectories are specified by the variable <makevar>CATEGORIES</makevar>. It is intended to
+ make life easier for the user when he is wading through the
+ pile of packages on the ftp site or the CD-ROM. Please take a
+ look at the existing <link
+ linkend="porting-categories">categories</link> and pick the
+ ones that are suitable for your port.</para>
+
+ <para>This list also determines where in the ports tree the port
+ is imported. If you put more than one category here, it is
+ assumed that the port files will be put in the subdirectory with
+ the name in the first category. See the <link
+ linkend="porting-categories">categories</link> section for
+ more discussion about how to pick the right categories.</para>
+
+ <para>If you port truly belongs to something that is different
+ from all the existing ones, you can even create a new category
+ name. In that case, please send mail to the &a.ports; to propose
+ a new category.</para>
+
+ <note>
+ <para>There is no error checking for category
+ names. <command>make package</command> will happily create a
+ new directory if you mustype the category name, so be
+ careful!</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><makevar>MASTER_SITES</makevar></title>
+
+ <para>Record the directory part of the ftp/http-URL pointing at
+ the original tarball in <makevar>MASTER_SITES</makevar>. Do not forget the
+ trailing slash (<filename>/</filename>)!</para>
+
+ <para>The <command>make</command> macros will try to use this specification for
+ grabbing the distribution file with <makevar>FETCH</makevar> if they cannot find it
+ already on the system.</para>
+
+ <para>It is recommended that you put multiple sites on this
+ list, preferably from different continents. This will
+ safeguard against wide-area network problems, and we are even
+ planning to add support for automatically determining the
+ closest master site and fetching from there!</para>
+
+ <para>If the original tarball is part of one of the following
+ popular archives: X-contrib, GNU, Perl CPAN, TeX CTAN, or
+ Linux Sunsite, you refer to those sites in an easy compact
+ form using <makevar>MASTER_SITE_XCONTRIB</makevar>, <makevar>MASTER_SITE_GNU</makevar>,
+ <makevar>MASTER_SITE_PERL_CPAN</makevar>, <makevar>MASTER_SITE_TEX_CTAN</makevar>, and
+ <makevar>MASTER_SITE_SUNSITE</makevar>. Simply set <makevar>MASTER_SITE_SUBDIR</makevar> to the
+ path with in the archive. Here is an example:</para>
+
+ <programlisting>
+MASTER_SITES= ${MASTER_SITE_XCONTRIB}
+MASTER_SITE_SUBDIR= applications</programlisting>
+
+ <para>The user can also set the <makevar>MASTER_SITE_*</makevar> variables in
+ <filename>/etc/make.conf</filename> to override our choices,
+ and use their favorite mirrors of these popular archives
+ instead.</para>
+
+ </sect3>
+
+ <sect3 id="porting-patchfiles">
+ <title><makevar>PATCHFILES</makevar></title>
+
+ <para>If your port requires some additional patches that are
+ available by ftp or http, set <makevar>PATCHFILES</makevar> to the names of the
+ files and <makevar>PATCH_SITES</makevar> to
+ the URL of the directory that contains them (the format is the
+ same as <makevar>MASTER_SITES</makevar>).</para>
+
+ <para>If the patch is not relative to the top of the source tree
+ (i.e., <makevar>WKRSRC</makevar>) because it
+ contains some extra pathnames, set <makevar>PATCH_DIST_STRIP</makevar> accordingly.
+ For instance, if all the pathnames in the patch has an extra
+ <literal>foozolix-1.0/</literal> in front of the
+ filenames, then set
+ <literal>PATCH_DIST_STRIP=-p1</literal>.</para>
+
+ <para>Do not worry if the patches are compressed, they will be
+ decompressed automatically if the filenames end with
+ <filename>.gz</filename> or
+ <filename>.Z</filename>.</para>
+
+ <para>If the patch is distributed with some other files, such as
+ documentation, in a gzip'd tarball, you can't just use
+ <makevar>PATCHFILES</makevar>. If that is
+ the case, add the name and the location of the patch tarball
+ to <makevar>DISTFILES</makevar> and
+ <makevar>MASTER_SITES</makevar>. Then, from
+ the <maketarget>pre-patch</maketarget> target, apply the
+ patch either by running the patch command from there, or
+ copying the patch file into the <makevar>PATCHDIR</makevar> directory and calling it
+ <filename>patch-<replaceable>xx</replaceable></filename>.</para>
+
+ <note>
+ <para>Note the tarball will have been extracted alongside the
+ regular source by then, so there is no need to explicitly
+ extract it if it is a regular gzip'd or compress'd tarball.
+ If you do the latter, take extra care not to overwrite
+ something that already exists in that directory. Also do
+ not forget to add a command to remove the copied patch in
+ the <maketarget>pre-clean</maketarget> target.</para>
+ </note>
+
+ </sect3>
+
+ <sect3>
+ <title><makevar>MAINTAINER</makevar></title>
+
+ <para>Set your mail-address here. Please. <!-- smiley --><emphasis>:)</emphasis></para>
+
+ <para>For detailed description of the responsibility of
+ maintainers, refer to <link
+ linkend="policies-maintainer">MAINTAINER
+ on Makefiles</link> section.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Dependencies</title>
+
+ <para>Many ports depend on other ports. There are five
+ variables that you can use to ensure that all the required
+ bits will be on the user's machine. There are also some
+ pre-supported dependency variables for common cases, plus a few
+ more to control the behaviour of dependencies.</para>
+
+
+ <sect4>
+ <title><makevar>LIB_DEPENDS</makevar></title>
+
+ <para>This variable specifies the shared libraries this port
+ depends on. It is a list of <replaceable>lib</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples where
+ <replaceable>lib</replaceable> is the name of the shared library,
+ and <replaceable>dir</replaceable> is the directory in which to
+ find it in case it is not available, and
+ <replaceable>target</replaceable> is the target to call in
+ that directory. For example,
+
+ <programlisting>
+LIB_DEPENDS= jpeg\\.9\\.:${PORTSDIR}/graphics/jpeg:install</programlisting>
+
+ will check for a shared jpeg library with
+ major version 9, and descend into the
+ <filename>graphics/jpeg</filename> subdirectory of your
+ ports tree to build and install it if it is not
+ found. The <replaceable>target</replaceable> part can be
+ omitted if it is equal to <makevar>DEPENDS_TARGET</makevar>
+ (which defaults to <literal>install</literal>).</para>
+
+ <note>
+ <para>The <replaceable>lib</replaceable> part is an argument
+ given to <command>ldconfig -r | grep -wF</command>. There
+ shall be no reqular expressions in this variable.</para>
+ </note>
+
+ <para>The dependency is checked twice, once from within the
+ <maketarget>extract</maketarget> target and then from within
+ the <maketarget>install</maketarget> target. Also, the name of the
+ dependency is put in to the package so that
+ <command>pkg_add</command> will automatically install it if it
+ is not on the user's system.</para>
+
+ </sect4>
+
+ <sect4>
+ <title><makevar>RUN_DEPENDS</makevar></title>
+
+ <para>This variable specifies executables or files this port
+ depends on during run-time. It is a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples where
+ <replaceable>path</replaceable> is the name of the executable or
+ file, and <replaceable>dir</replaceable> is the directory in which
+ to find it in case it is not available, and
+ <replaceable>target</replaceable> is the target to call in
+ that directory. If
+ <replaceable>path</replaceable> starts with a slash
+ (<literal>/</literal>), it is treated as a file and its
+ existence is tested with <command>test -e</command>;
+ otherwise, it is assumed to be an executable, and
+ <command>which -s</command> is used to determine if the
+ program exists in the user's search path.</para>
+
+ <para>For example,
+
+ <programlisting>
+RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \
+ wish8.0:${PORTSDIR}/x11-toolkits/tk80</programlisting>
+
+ will check if the file or directory
+ <filename>/usr/local/etc/innd</filename> exists, and build
+ and install it from the <filename>news/inn</filename>
+ subdirectory of the ports tree if it is not found. It will
+ also see if an executable called <command>wish8.0</command> is in your search path, and
+ descend into the <filename>x11-toolkits/tk80</filename> subdirectory of
+ your ports tree to build and install it if it is not
+ found.</para>
+
+ <note>
+ <para>In this case, <command>innd</command> is actually an
+ executable; if an executable is in a place that is not
+ expected to be in a normal user's search path, you should
+ use the full pathname.</para>
+ </note>
+
+ <para>The dependency is checked from within the <maketarget>install</maketarget> target. Also, the name of the
+ dependency is put in to the package so that
+ <command>pkg_add</command> will automatically install it if it
+ is not on the user's system. The
+ <replaceable>target</replaceable> part can be omitted if it is
+ the same <makevar>DEPENDS_TARGET</makevar>.</para>
+
+ </sect4>
+
+ <sect4>
+ <title><makevar>BUILD_DEPENDS</makevar></title>
+
+ <para>This variable specifies executables or files this port
+ requires to build. Like <makevar>RUN_DEPENDS</makevar>, it is
+ a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples.
+ For example,
+
+ <programlisting>
+BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>
+
+ will check for an executable called
+ <command>unzip</command>, and descend into the
+ <filename>archivers/unzip</filename> subdirectory of your
+ ports tree to build and install it if it is not
+ found.</para>
+
+ <note>
+ <para>“build” here means everything from extracting to
+ compilation. The dependency is checked from within the
+ <maketarget>extract</maketarget> target. The
+ <replaceable>target</replaceable> part can be omitted if it
+ is the same as <makevar>DEPENDS_TARGET</makevar></para>
+ </note>
+ </sect4>
+
+ <sect4>
+ <title><makevar>FETCH_DEPENDS</makevar></title>
+
+ <para>This variable specifies executables or files this port
+ requires to fetch. Like the previous two, it is a list of
+ <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples. For
+ example,
+
+ <programlisting>
+FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting>
+
+ will check for an executable called
+ <command>ncftp2</command>, and descend into the
+ <filename>net/ncftp2</filename> subdirectory of your ports
+ tree to build and install it if it is not found.</para>
+
+ <para>The dependency is checked from within the
+ <maketarget>fetch</maketarget> target. The
+ <replaceable>target</replaceable> part can be omitted if it is
+ the same as <makevar>DEPENDS_TARGET</makevar>.</para>
+
+ </sect4>
+
+ <sect4>
+ <title><makevar>DEPENDS</makevar></title>
+
+ <para>If there is a dependency that does not fall into either
+ of the above four categories, or your port requires to have
+ the source of the other port extracted in addition to having
+ them installed, then use this variable. This is a list of
+ <replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional>, as there is nothing to check, unlike the previous four. The <replaceable>target</replaceable> part can be omitted if it is the same as <makevar>DEPENDS_TARGET</makevar>.</para>
+ </sect4>
+
+ <sect4>
+ <title>Common dependency variables</title>
+
+ <para>Define <literal>USE_XLIB=yes</literal> if your port
+ requires the X Window System to be installed (it is implied by
+ <makevar>USE_IMAKE</makevar>). Define
+ <literal>USE_GMAKE=yes</literal> if your port requires GNU
+ <command>make</command> instead of BSD
+ <command>make</command>. Define
+ <literal>USE_AUTOCONF=yes</literal> if your port requires GNU
+ autoconf to be run. Define <literal>USE_QT=yes</literal> if
+ your port uses the latest qt toolkit. Use
+ <literal>USE_PERL5=yes</literal> if your port requires version
+ 5 of the perl language. (The last is especially important since
+ some versions of FreeBSD has perl5 as part of the base system
+ while others don't.)</para>
+ </sect4>
+
+ <sect4>
+ <title>Notes on dependencies</title>
+
+ <para>As mentioned above, the default target to call when a
+ dependency is required is
+ <maketarget>DEPENDS_TARGET</maketarget>. It defaults to
+ <literal>install</literal>. This is a user variable; is is
+ never defined in a port's <filename>Makefile</filename>. If
+ your port needs a special way to handle a dependency, use the
+ <literal>:target</literal> part of the
+ <makevar>*_DEPENDS</makevar> variables instead of redefining
+ <makevar>DEPENDS_TARGET</makevar>.</para>
+
+ <para>When you type <command>make clean</command>, its
+ dependencies are automatically cleaned too. If you do not wish
+ this to happen, define the variable
+ <makevar>NOCLEANDEPENDS</makevar> in your environment.</para>
+
+ <para>To depend on another port unconditionally, it is customary
+ to use the string <literal>nonexistent</literal> as the first
+ field of <makevar>BUILD_DEPENDS</makevar> or
+ <makevar>RUN_DEPENDS</makevar>. Use this only when you need to
+ the to get to the source of the other port. You can often save
+ compilation time by specifying the target too. For
+ instance
+
+ <programlisting>
+BUILD_DEPENDS= /nonexistent:${PORTSDIR}/graphics/jpeg:extract</programlisting>
+
+ will always descend to the JPEG port and extract it.</para>
+
+ <para>Do not use <makevar>DEPENDS</makevar> unless there is no
+ other way the behaviour you want can be accomplished. It will
+ cause the other port to be always build (and installed, by
+ default), and the dependency will go into the packages as
+ well. If this is really what you need, I recommend you to
+ write it as <literal>BUILD_DEPENDS</literal> and
+ <literal>RUN_DEPENDS</literal> instead—at least the
+ intention will be clear.</para>
+ </sect4>
+ </sect3>
+
+ <sect3>
+ <title>Building mechanisms</title>
+
+ <para>If your package uses GNU <command>make</command>, set
+ <literal>USE_GMAKE=yes</literal>. If your package uses
+ <command>configure</command>, set
+ <literal>HAS_CONFIGURE=yes</literal>. If your package uses GNU
+ <command>configure</command>, set
+ <literal>GNU_CONFIGURE=yes</literal> (this implies
+ <literal>HAS_CONFIGURE</literal>). If you want to give some
+ extra arguments to <command>configure</command> (the default
+ argument list <literal>--prefix=${PREFIX}</literal> for
+ GNU <command>configure</command> and empty for non-GNU
+ <command>configure</command>), set those extra arguments in
+ <makevar>CONFIGURE_ARGS</makevar>. If your package uses GNU
+ <command>autoconf</command>, set
+ <literal>USE_AUTOCONF=yes</literal>. This implies
+ <makevar>GNU_CONFIGURE</makevar>, and will cause
+ <command>autoconf</command> to be run before
+ <command>configure</command>.</para>
+
+ <para>If your package is an X application that creates
+ <filename>Makefile</filename>s from
+ <filename>Imakefile</filename>s using <command>imake</command>, then set
+ <literal>USE_IMAKE=yes</literal>. This will cause the
+ configure stage to automatically do an <command>xmkmf
+ -a</command>. If the <option>-a</option> flag is a
+ problem for your port, set
+ <literal>XMKMF=xmkmf</literal>.
+ If the port uses <command>imake</command> but does not understand the
+ <maketarget>install.man</maketarget> target,
+ <literal>NO_INSTALL_MANPAGES=yes</literal> should be set.
+ In addition, the author of the original port should be shot.
+ <!-- smiley --><emphasis>:></emphasis></para>
+
+ <para>If your port's source <filename>Makefile</filename> has
+ something else than <maketarget>all</maketarget> as the main
+ build target, set <makevar>ALL_TARGET</makevar>
+ accordingly. Same goes for <maketarget>install</maketarget> and
+ <makevar>INSTALL_TARGET</makevar>.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Special considerations</title>
+
+ <para>There are some more things you have to take into account when
+ you create a port. This section explains the most common of
+ those.</para>
+
+ <sect3>
+ <title><command>ldconfig</command></title>
+
+ <para>If your port installs a shared library, add a
+ <maketarget>post-install</maketarget> target to your
+ <filename>Makefile</filename> that runs
+ <literal>${LDCONFIG} -m</literal> on the directory where
+ the new library is installed (usually
+ <filename><makevar>PREFIX</makevar>/lib</filename>) to register
+ it into the shared library cache.</para>
+
+ <para>Also, add a matching <literal>@exec /sbin/ldconfig
+ -m</literal> and <literal>@unexec /sbin/ldconfig -R</literal>
+ pair to your <filename>pkg/PLIST</filename> file so that a user
+ who installed the package can start using teh shared libraru
+ immediately and deinstallation will not cause the system to
+ still believe the library is there. These lines should
+ immediately follow the line for the shared library itself, as
+ in:</para>
+
+ <programlisting>
+lib/libtvl80.so.1
+@exec /sbin/ldconfig -m %D/lib
+@unexec /sbin/ldconfig -R</programlisting>
+
+ <para>Never, ever, <emphasis>ever</emphasis> add a line that says
+ <literal>ldconfig</literal> without any arguments to your
+ <filename>Makefile</filename> or
+ <filename>pkg/PLIST</filename>. This will reset the shared
+ libraru cache to the contents of <filename>/usr/lib</filename>
+ only, and will royally screw up the user's machine ("Help, xinit
+ does not run anymore after I install this port!"). Anybody who
+ does this will be shot and cut in 65,536 pieces by a rusty knife
+ and have is liver chopped out by a bunch of crows and will
+ eternally rot to death in the deepest bowels of hell (not
+ necessarily in that order…)</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>ELF support</title>
+
+ <para>Since FreeBSD is moving to ELF from 3.0-release onwards,
+ 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 that there will
+ be one more release (2.2.8) from the 2.2 branch. 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 awhile for reference
+ in case you have come across some old port you wish to
+ upgrade.</para>
+
+ <sect3>
+ <title>Moving a.out libraries out of the way</title>
+
+ <para>A.out libraries should be moved out of
+ <filename>/usr/local/lib</filename> and similar to an
+ <filename>aout</filename> subdirectory. (If you don't move them
+ out of the way, ELF ports will happily overwrite a.out libraries.)
+ The <maketarget>move-aout-libs</maketarget> target in the -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>
+ </sect3>
+
+ <sect3>
+ <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>
+ </sect3>
+
+ <sect3>
+ <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's always going to be
+ <literal>aout</literal> in -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>
+ </sect3>
+
+ <sect3>
+ <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 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>PLIST</filename> too, and it won't 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>
+ </sect3>
+
+ <sect3>
+ <title><makevar>LIB_DEPENDS</makevar></title>
+
+ <para>All port Makefiles 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>
+ </sect3>
+
+ <sect3>
+ <title><filename>PLIST</filename></title>
+
+ <para><filename>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>PLIST</filename> mentioned in the previous
+ paragraph.</para>
+ </sect3>
+
+ <sect3>
+ <title><literal>ldconfig</literal></title>
+
+ <para>The <literal>ldconfig</literal> line in Makefiles should read:</para>
+
+ <programlisting>
+${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....</programlisting>
+
+ <para>In <filename>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>
+ </sect3>
+ </sect2>
+
+ <sect2 id="porting-masterdir">
+ <title><makevar>MASTERDIR</makevar></title>
+
+ <para>If your port needs to build slightly different versions of
+ packages by having a variable (for instance, resolution, or paper
+ size) take different values, create one subdirectory per package
+ to make it easier forusers to see what to do, but try to share as
+ many files as possible between ports. Typically you only need a
+ very short <filename>Makefile</filename> in all but one of the
+ directories if you use variables cleverly. In the sole
+ <filename>Makefiles</filename>, you can use
+ <makevar>MASTERDIR</makevar> to specify the directory where the
+ rest of the files are. Also, use a variable as part of
+ <link linkend="porting-pkgname"><makevar>PKGNAME</makevar></link>
+ so the packages will have different names.</para>
+
+ <para>This will be best demonstrated by an example. This is part of
+ <filename>japanese/xdvi300/Makefile</filename>;</para>
+
+ <programlisting>
+PKGNAME= ja-xdvi${RESOLUTION}-17
+ :
+# 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>japanese/xdvi300</filename> also has all the regular
+ patches, package files, etc. If you type <command>make</command>
+ there, it will take the default value for the resolution (300) and
+ build the port normally.</para>
+
+ <para>As for other resolutions, this is the
+ <emphasis>entire</emphasis>
+ <filename>xdvi118/Makefile</filename>;</para>
+
+ <programlisting>
+RESOLUTION= 118
+MASTERDIR= ${.CURDIR}/../xdvi300
+
+.include ${MASTERDIR}/Makefile</programlisting>
+
+ <para>(<filename>xdvi240/Makefile</filename> and
+ <filename>xdvi400/Makefile</filename> are similar). The
+ <makevar>MASTERDIR</makevar> definition tells
+ <filename>bsd.port.mk</filename> that the refulat set of
+ subdirectories like <makevar>PATCHDIR</makevar> and
+ <makevar>PKGDIR</makevar> are to be found under
+ <filename>xdvi300</filename>. The
+ <literal>RESOLUTION=118</literal> line will override the
+ <literal>RESOLUTION=300</literal> line in
+ <filename>xdvi300/Makefile</filename> and the port will be built
+ with resolution set to 118.</para>
+ </sect2>
+
+ <sect2>
+ <title>Shared library versions</title>
+
+ <para>First, please read our <link linkend="policies-shlib">policy
+ on shared library versioning</link> to understand
+ what to do with shared library versions in general. Do
+ not blindly assume software authors know what they are
+ doing; many of them do not. It is very important that
+ these details are carefully considered, as we have quite a
+ unique situation where we are trying to have dozens of
+ potentially incompatible software pairs co-exist.
+ Careless port imports have caused great trouble regarding
+ shared libraries in the past (ever wondered why the port
+ <filename>jpeg-6b</filename> has a shared library version of 9.0?).
+ If in doubt, send a message to the &a.ports;. Most of the
+ time, your job ends by determining the right shared
+ library version and making appropriate patches to
+ implement it.</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>
+ </sect2>
+
+ <sect2 id="porting-manpages">
+ <title>Manpages</title>
+
+ <para>The <makevar>MAN[1-9LN]</makevar> variables will automatically
+ add any manpages to <filename>pkg/PLIST</filename> (this means you
+ must <emphasis>not</emphasis> list manpages in the
+ <filename>PLIST</filename>—see <link
+ linkend="porting-plist">generating PLIST</link> for more). It
+ also makes the install stage automatically compress or uncompress
+ manpages depending on the setting of
+ <makevar>NOMANCOMPRESS</makevar> in
+ <filename>/etc/make.conf</filename>.</para>
+
+ <para>To specify whether the manpages are compressed upon
+ installation, use the <makevar>MANCOMPRESSED</makevar> variable.
+ This variable can take three values, <literal>yes</literal>,
+ <literal>no</literal> and <literal>maybe</literal>.
+ <literal>yes</literal> means manpages are already installed
+ compressed, <literal>no</literal> means they are not, and
+ <literal>maybe</literal> means the software already respects the
+ value of <makevar>NOMANCOMPRESS</makevar> so
+ <filename>bsd.port.mk</filename> does not have to do anything
+ special.</para>
+
+ <para><makevar>MANCOMPRESSED</makevar> is automatically set to
+ <literal>yes</literal> if <makevar>USE_IMAKE</makevar> is set and
+ <makevar>NO_INSTALL_MANPAGES</makevar> is not set, and to
+ <literal>no</literal> otherwise. You don't have to explicitly
+ define it unless the default is not suitable for your port.</para>
+
+ <para>If your port anchors its man tree somewhere other than
+ <makevar>PREFIX</makevar>, you can use the
+ <makevar>MANPREFIX</makevar> to set it. Also, if only manpages in
+ certain sections go in a non-standard place, such as some Perl
+ modules ports, you can set individual man paths using
+ <makevar>MAN<replaceable>sect</replaceable>PREFIX</makevar> (where
+ <replaceable>sect</replaceable> is one of <literal>1-9</literal>,
+ <literal>L</literal> or <literal>N</literal>).</para>
+
+ <para>If your manpages go to language-specific subdirectories, set
+ the name of the languages to <makevar>MANLANG</makevar>. The
+ value of this variable defaults to <literal>""</literal> (i.e.,
+ English only).</para>
+
+ <para>Here is an example that puts it all together.</para>
+
+ <programlisting>
+MAN1= foo.1
+MAN3= bar.3
+MAN4= baz.4
+MANLANG= "" ja
+MAN3PREFIX= ${PREFIX}/share/foobar
+MANCOMPRESSED= yes</programlisting>
+
+ <para>This states that six files are installed by this 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>
+ </sect2>
+
+ <sect2>
+ <title>Ports that require Motif</title>
+
+ <para>There are many programs that require a Motif library
+ (available from several commercial vendors, while there is
+ a free clone reported to be able to run many applications in
+ <filename>x11-toolkits/lesstif</filename>) to compile. Since
+ it is a popular toolkit and their licenses usually permit
+ redistribution of statically linked binaries, we have made
+ special provisions for handling ports that require Motif in a
+ way that we can easily compile binaries linked either
+ dynamically (for people who are compiling from the port) or
+ statically (for people who distribute packages).</para>
+
+ <sect3>
+ <title><makevar>REQUIRES_MOTIF</makevar></title>
+
+ <para>If your port requires Motif, define this variable in the
+ Makefile. This will prevent people who don't own a copy of
+ Motif from even attempting to build it.</para>
+ </sect3>
+
+ <sect3>
+ <title><makevar>MOTIFLIB</makevar></title>
+
+ <para>This variable will be set by
+ <filename>bsd.port.mk</filename> to be the appropriate reference
+ to the Motif library. Please patch the source to use this
+ wherever the Motif library is referenced in the
+ <filename>Makefile</filename> or
+ <filename>Imakefile</filename>.</para>
+
+ <para>There are two common cases:</para>
+
+ <itemizedlist>
+ <listitem><para>If the port refers to the Motif library as
+ <literal>-lXm</literal> in its <filename>Makefile</filename>
+ or <filename>Imakefile</filename>, simply substitute
+ <literal>${MOTIFLIB}</literal> for
+ it.</para></listitem>
+
+ <listitem><para>If the port uses <literal>XmClientLibs</literal>
+ in its <filename>Imakefile</filename>, change it to
+ <literal>${MOTIFLIB} ${XTOOLLIB}
+ ${XLIB}</literal>.</para></listitem>
+ </itemizedlist>
+
+ <para>Note that <makevar>MOTIFLIB</makevar> (usually) expands to
+ <literal>-L/usr/X11R6/lib -lXm</literal> or
+ <literal>/usr/X11R6/lib/libXm.a</literal>, so there is no need
+ to add <literal>-L</literal> or <literal>-l</literal> in
+ front.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>X11 fonts</title>
+
+ <para>If your port installs fonts for the X Window system, put them
+ in
+ <filename><makevar>X11BASE</makevar>/lib/X11/fonts/local</filename>.
+ This directory is new to XFree86 release 3.3.3. If it does not
+ exist, please create it, and print out a message urging the user
+ to update their XFree86 to 3.3.3 or newer, or at least add this
+ directory to the font path in
+ <filename>/etc/XF86Config</filename>.</para>
+ </sect2>
+
+ <sect2>
+ <title>Info files</title>
+
+ <para>The new version of texinfo (included in 2.2.2-RELEASE and
+ onwards) contains a utility called <command>install-info</command>
+ to add and delete entries to the <filename>dir</filename> file. If
+ your port installs any info documents, please follow this
+ instructions so your port/package will correctly update the user's
+ <filename><makevar>PREFIX</makevar>/info/dir</filename>
+ file. (Sorry for the length of this section, but is it imperative
+ to weave all the info files together. If done correctly, it will
+ produce a <emphasis>beautiful</emphasis> listing, so please bear
+ with me!</para>
+
+ <para>First, this is what you (as a porter) need to know</para>
+
+ <informalexample>
+ <screen>&prompt.user; <userinput>install-info --help</userinput>
+install-info [OPTION]... [INFO-FILE [DIR-FILE]]
+ Install INFO-FILE in the Info directory file DIR-FILE.
+
+Options:
+--delete Delete existing entries in INFO-FILE;
+ don't insert any new entries.
+ :
+--entry=TEXT Insert TEXT as an Info directory entry.
+ :
+--section=SEC Put this file's entries in section SEC of the directory. :</screen>
+ </informalexample>
+
+ <note>
+ <para>This program will not actually
+ <emphasis>install</emphasis> info files; it merely inserts or
+ deletes entries in the <filename>dir</filename> file.</para>
+ </note>
+
+ <para>Here's a seven-step procedure to convert ports to use
+ <command>install-info</command>. I will use
+ <filename>editors/emacs</filename> as an example.</para>
+
+ <procedure>
+ <step>
+ <para>Look at the texinfo sources and make a patch to insert
+ <literal>@dircategory</literal> and <literal>@direntry</literal>
+ statements to files that don't have them. This is part of
+ my patch:</para>
+
+ <programlisting>
+--- ./man/vip.texi.org Fri Jun 16 15:31:11 1995
++++ ./man/vip.texi Tue May 20 01:28:33 1997
+@@ -2,6 +2,10 @@
+
+ @setfilename ../info/vip
+ @settitle VIP
++@dircategory The Emacs editor and associated tools
++@direntry
++* VIP: (vip). A VI-emulation for Emacs.
++@end direntry
+
+ @iftex
+ @finalout
+ :</programlisting>
+
+ <para>The format should be self-explanatory. Many authors
+ leave a <filename>dir</filename> file in the source tree
+ that contains all the entries you need, so look around
+ before you try to write your own. Also, make sure you
+ look into related ports and make the section names and
+ entry indentations consistent (we recommend that all entry
+ text start at the 4th tab stop).</para>
+
+ <note>
+ <para>Note that you can put only one info entry per file
+ because of a bug in <command>install-info
+ --delete</command> that deletes only the first entry
+ if you specify multiple entries in the
+ <email>@direntry</email> section.</para>
+ </note>
+
+ <para>You can give the <literal>dir</literal>
+ entries to <command>install-info</command> as
+ arguments (<option>--section</option> and
+ <option>--entry</option>) instead of patching the texinfo
+ sources. I do not think this is a good idea for ports
+ because you need to duplicate the same information in
+ <emphasis>three</emphasis> places
+ (<filename>Makefile</filename> and
+ <literal>@exec</literal>/<literal>@unexec</literal> of
+ <filename>PLIST</filename>; see below). However, if you
+ have a Japanese (or other multibyte encoding) info files,
+ you will have to use the extra arguments to <command>install-info</command> because <command>makeinfo</command> can't handle those texinfo
+ sources. (See <filename>Makefile</filename> and
+ <filename>PLIST</filename> of
+ <filename>japanese/skk</filename> for examples on how to
+ do this).</para>
+ </step>
+
+ <step>
+ <para>Go back to the port directory and do a <command>make clean; make</command> and verify that
+ the info files are regenerated from the texinfo sources.
+ Since the texinfo sources are newer than the info files,
+ they should be rebuilt when you type <command>make</command>; but many
+ <filename>Makefile</filename>s don't include correct
+ dependencies for info files. In <command>emacs</command>' case, I had to
+ patch the main <filename>Makefile.in</filename> so it will
+ descend into the <filename>man</filename>
+ subdirectory to rebuild the info pages.</para>
+
+ <programlisting>
+--- ./Makefile.in.org Mon Aug 19 21:12:19 1996
++++ ./Makefile.in Tue Apr 15 00:15:28 1997
+@@ -184,7 +184,7 @@
+ # Subdirectories to make recursively. `lisp' is not included
+ # because the compiled lisp files are part of the distribution
+ # and you cannot remake them without installing Emacs first.
+-SUBDIR = lib-src src
++SUBDIR = lib-src src man
+
+ # The makefiles of the directories in $SUBDIR.
+ SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile lwlib/Makefile
+--- ./man/Makefile.in.org Thu Jun 27 15:27:19 1996
++++ ./man/Makefile.in Tue Apr 15 00:29:52 1997
+@@ -66,6 +66,7 @@
+ ${srcdir}/gnu1.texi \
+ ${srcdir}/glossary.texi
+
++all: info
+ info: $(INFO_TARGETS)
+
+ dvi: $(DVI_TARGETS)</programlisting>
+
+ <para>The second hunk was necessary because the default
+ target in the <filename>man</filename> subdir is called
+ <maketarget>info</maketarget>, while the main
+ <filename>Makefile</filename> wants to call <maketarget>all</maketarget>. I also deleted the installation
+ of the <filename>info</filename> info file
+ because we already have one with the same name in
+ <filename>/usr/share/info</filename> (that patch is not
+ shown here).</para>
+ </step>
+
+ <step>
+ <para>If there is a place in the
+ <filename>Makefile</filename> that is installing the
+ <filename>dir</filename> file, delete it. Your
+ port may not be doing it. Also, remove any commands that
+ are otherwise mucking around with the
+ <filename>dir</filename> file.</para>
+
+ <programlisting>
+--- ./Makefile.in.org Mon Aug 19 21:12:19 1996
++++ ./Makefile.in Mon Apr 14 23:38:07 1997
+@@ -368,14 +368,8 @@
+ if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \
+ then \
+ (cd ${infodir}; \
+- if [ -f dir ]; then \
+- if [ ! -f dir.old ]; then mv -f dir dir.old; \
+- else mv -f dir dir.bak; fi; \
+- fi; \
+ cd ${srcdir}/info ; \
+- (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir); \
+- (cd $${thisdir}; chmod a+r ${infodir}/dir); \
+ for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \
+ (cd $${thisdir}; \
+ ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \
+ chmod a+r ${infodir}/$$f); \</programlisting>
+ </step>
+
+ <step>
+ <para>(This step is only necessary if you are modifying an
+ existing port.) Take a look at
+ <filename>pkg/PLIST</filename> and delete anything that is
+ trying to patch up <filename>info/dir</filename>. They
+ may be in <filename>pkg/INSTALL</filename> or some other
+ file, so search extensively.</para>
+
+ <programlisting>
+Index: pkg/PLIST
+===================================================================
+RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v
+retrieving revision 1.15
+diff -u -r1.15 PLIST
+--- PLIST 1997/03/04 08:04:00 1.15
++++ PLIST 1997/04/15 06:32:12
+@@ -15,9 +15,6 @@
+ man/man1/emacs.1.gz
+ man/man1/etags.1.gz
+ man/man1/ctags.1.gz
+-@unexec cp %D/info/dir %D/info/dir.bak
+-info/dir
+-@unexec cp %D/info/dir.bak %D/info/dir
+ info/cl
+ info/cl-1
+ info/cl-2</programlisting>
+ </step>
+
+ <step>
+ <para>Add a <maketarget>post-install</maketarget>
+ target to the <filename>Makefile</filename> to create a
+ <filename>dir</filename> file if it is not there. Also,
+ call <maketarget>install-info</maketarget> with the
+ installed info files.</para>
+
+ <programlisting>
+Index: Makefile
+===================================================================
+RCS file: /usr/cvs/ports/editors/emacs/Makefile,v
+retrieving revision 1.26
+diff -u -r1.26 Makefile
+--- Makefile 1996/11/19 13:14:40 1.26
++++ Makefile 1997/05/20 10:25:09 1.28
+@@ -20,5 +20,11 @@
+ post-install:
+ .for file in emacs-19.34 emacsclient etags ctags b2m
+ strip ${PREFIX}/bin/${file}
+ .endfor
++ if [ ! -f ${PREFIX}/info/dir ]; then \
++ ${SED} -ne '1,/Menu:/p' /usr/share/info/dir > ${PREFIX}/info/dir; \
++ fi
++.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode
++ install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir
++.endfor
+
+ .include <bsd.port.mk></programlisting>
+
+ <para>Do not use anything other than
+ <filename>/usr/share/info/dir</filename> and the above
+ command to create a new info file. In fact, I'd add the
+ first three lines of the above patch to
+ <filename>bsd.port.mk</filename> if you (the porter)
+ wouldn't have to do it in <filename>PLIST</filename> by
+ yourself anyway.</para>
+ </step>
+
+ <step>
+ <para>Edit <filename>PLIST</filename> and add equivalent
+ <literal>@exec</literal> statements and also
+ <literal>@unexec</literal> for <command>pkg_delete</command>.
+ You do not need to delete <filename>info/dir</filename>
+ with <literal>@unexec</literal>.</para>
+
+ <programlisting>
+Index: pkg/PLIST
+===================================================================
+RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v
+retrieving revision 1.15
+diff -u -r1.15 PLIST
+--- PLIST 1997/03/04 08:04:00 1.15
++++ PLIST 1997/05/20 10:25:12 1.17
+@@ -16,7 +14,15 @@
+ man/man1/etags.1.gz
+ man/man1/ctags.1.gz
++@unexec install-info --delete %D/info/emacs %D/info/dir
+ :
++@unexec install-info --delete %D/info/ccmode %D/info/dir
+ info/cl
+ info/cl-1
+@@ -87,6 +94,18 @@
+ info/viper-3
+ info/viper-4
++@exec [ -f %D/info/dir ] || sed -ne '1,/Menu:/p' /usr/share/info/dir > %D/info/dir
++@exec install-info %D/info/emacs %D/info/dir
+ :
++@exec install-info %D/info/ccmode %D/info/dir
+ libexec/emacs/19.34/i386--freebsd/cvtmail
+ libexec/emacs/19.34/i386--freebsd/digest-doc</programlisting>
+
+ <note>
+ <para>The <literal>@unexec install-info
+ --delete</literal> commands have to be listed before
+ the info files themselves so they can read the files.
+ Also, the <literal>@exec install-info</literal> commands
+ have to be after the info files and the
+ <literal>@exec</literal> command that creates the the
+ <filename>dir</filename> file.</para>
+ </note>
+ </step>
+
+ <step>
+ <para><link linkend="porting-testing">Test</link> and admire your work. <!-- smiley --><emphasis>:)</emphasis>. Check the <filename>dir</filename> file before and after each
+ step.</para>
+ </step>
+ </procedure>
+
+ </sect2>
+
+ <sect2>
+ <title>The <filename>pkg/</filename> subdirectory</title>
+
+ <para>There are some tricks we haven't mentioned yet about the
+ <filename>pkg/</filename> subdirectory that come in handy
+ sometimes.</para>
+
+ <sect3 id="porting-message">
+ <title><filename>MESSAGE</filename></title>
+
+ <para>If you need to display a message to the installer, you may
+ place the message in <filename>pkg/MESSAGE</filename>. This
+ capability is often useful to display additional installation
+ steps to be taken after a <command>pkg_add</command> or to display
+ licensing information.</para>
+
+ <note>
+ <para>The <filename>pkg/MESSAGE</filename> file does not need to
+ be added to <filename>pkg/PLIST</filename>. Also, it will not get
+ automatically printed if the user is using the port, not the
+ package, so you should probably display it from the
+ <maketarget>post-install</maketarget> target yourself.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><filename>INSTALL</filename></title>
+
+ <para>If your port needs execute commands when the binary package is
+ installed with <command>pkg_add</command> you can do with via the
+ <filename>pkg/INSTALL</filename> script. This script will
+ automatically be added to the package, and will be run twice by
+ <command>pkg_add</command>. The first time will as
+ <literal>INSTALL ${PKGNAME} PRE-INSTALL</literal> and the
+ second time as <literal>INSTALL ${PKGNAME}
+ POST-INSTALL</literal>. <literal>$2</literal> can be
+ tested to determine which mode the script is being run in. The
+ <envar>PKG_PREFIX</envar> environmental variable will be set to
+ the package installation directory. See <citerefentry>
+ <refentrytitle>pkg_add</refentrytitle>
+ <manvolnum>1</manvolnum></citerefentry> for additional
+ information.</para>
+
+ <note>
+ <para>This script is not run automatically if you install the port
+ with <command>make install</command>. If you are depending on
+ it being run, you will have to explicitly call it on your port's
+ <filename>Makefile</filename>.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><filename>REQ</filename></title>
+
+ <para>If your port needs to determine if it should install or not,
+ you can create a <filename>pkg/REQ</filename>
+ “requirements” script. It will be invoked
+ automatically at installation/deinstallation time to determine
+ whether or not installation/deinstallation should proceed.</para>
+ </sect3>
+
+ <sect3 id="porting-plist">
+ <title>Changing <filename>PLIST</filename> based on make variables</title>
+
+ <para>Some ports, particularly the p5- ports, need to change their
+ <filename>PLIST</filename> depending on what options they are
+ configured with (or version of perl, in the case of p5- ports). To
+ make this easy, any instances in the <filename>PLIST</filename> of
+ <literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal>, and
+ <literal>%%PERL_VERSION%%</literal> will be substituted for
+ appropriately. The value of <literal>%%OSREL%%</literal> is the
+ numeric revision of the operating system (e.g.,
+ <literal>2.2.7</literal>). <literal>%%PERL_VERSION%%</literal> is
+ the full version number of perl (e.g., <literal>5.00502</literal>)
+ and <literal>%%PERL_VER%%</literal> is the perl version number
+ minus the patchlevel (e.g., <literal>5.005</literal>).</para>
+
+ <para>If you need to make other substitutions, you can set the
+ <makevar>PLIST_SUB</makevar> variable with a list of
+ <literal><replaceable>VAR</replaceable>=<replaceable>VALUE</replaceable></literal>
+ pairs and instances of
+ <literal>%%<replaceable>VAR</replaceable>%%</literal>' will be
+ substituted with <replaceable>VALUE</replaceable> in the
+ <filename>PLIST</filename>.</para>
+
+ <para>For instance, if you have a port that installs many files in
+ a version-specific subdirectory, you can put something
+ like
+
+ <programlisting>
+OCTAVE_VERSION= 2.0.13
+PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
+
+ in the <filename>Makefile</filename> and use
+ <literal>%%OCTAVE_VERSION%%</literal> wherever the version shows
+ up in <filename>PLIST</filename>. That way, when you upgrade the
+ port, you will not have to change dozens (or in some cases,
+ hundreds) of lines in the <filename>PLIST</filename>.</para>
+
+ <para>This substitution (as well as addition of any <link
+ linkend="porting-manpages">man pages</link>) will be done
+ between the <maketarget>do-install</maketarget> and
+ <maketarget>post-install</maketarget> targets, by reading from
+ <makevar>PLIST</makevar> and writing to
+ <makevar>TMPPLIST</makevar> (default:
+ <filename><makevar>WRKDIR</makevar>/.PLIST.mktmp</filename>). So
+ if your port builds <makevar>PLIST</makevar> on the fly, do so in
+ or before <maketarget>do-install</maketarget>. Also, if your port
+ needs to edit the resulting file, do so in
+ <maketarget>post-install</maketarget> to a file named
+ <makevar>TMPPLIST</makevar>.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Licensing Problems</title>
+
+ <para>Some software packages have restrictive licenses or can be
+ in violation to the law (PKP's patent on public key crypto, ITAR
+ (export of crypto software) to name just two of them). What we
+ can do with them vary a lot, depending on the exact wordings of
+ the respective licenses.</para>
+
+ <note>
+ <para>It is your responsibility as a porter to read the
+ licensing terms of the software and make sure that the FreeBSD
+ project will not be held accountable of violating them by
+ redistributing the source or compiled binaries either via ftp
+ or CD-ROM. If in doubt, please contact the &a.ports;.</para>
+ </note>
+
+ <para>There are two variables you can set in the Makefile to
+ handle the situations that arise frequently:</para>
+
+
+ <orderedlist>
+
+ <listitem>
+ <para>If the port has a “do not sell for profit” type of
+ license, set the variable <makevar>NO_CDROM</makevar> to a
+ string describing the reason why. We
+ will make sure such ports won't go into the CD-ROM come
+ release time. The distfile and package will still be
+ available via ftp.</para>
+ </listitem>
+
+ <listitem>
+ <para>If the resulting package needs to be built uniquely
+ for each site, or the resulting binary package can't be
+ distributed due to licensing; set the variable
+ <makevar>NO_PACKAGE</makevar> to a string describing the
+ reason why. We will make sure such
+ packages won't go on the ftp site, nor into the CD-ROM
+ come release time. The distfile will still be included on
+ both however.</para>
+ </listitem>
+
+ <listitem>
+ <para>If the port has legal restrictions on who can use it
+ (e.g., crypto stuff) or has a “no commercial use” license,
+ set the variable <makevar>RESTRICTED</makevar> to be the
+ string describing the reason why. For such ports, the
+ distfiles/packages will not be available even from our ftp
+ sites.</para>
+ </listitem>
+
+ </orderedlist>
+
+
+ <note>
+ <para>The GNU General Public License (GPL), both version 1
+ and 2, should not be a problem for ports.</para>
+ </note>
+
+ <note>
+ <para>If you are a committer, make sure you update the
+ <filename>ports/LEGAL</filename> file too.</para>
+ </note>
+ </sect2>
+
+ <sect2>
+ <title>Upgrading</title>
+
+ <para>When you notice that a port is out of date compared to the
+ latest version from the original authors, first make sure you
+ have the latest port. You can find them in the
+ <filename>ports-current</filename> directory of the ftp mirror
+ sites.</para>
+
+ <para>The next step is to send a mail to the maintainer, if one is
+ listed in the port's <filename>Makefile</filename>. That person may already be
+ working on an upgrade, or have a reason to not upgrade the port
+ right now (because of, for example, stability problems of the
+ new version).</para>
+
+ <para>If the maintainer asks you to do the upgrade or there isn't
+ any such person to begin with, please make the upgrade and send
+ the recursive diff (either unified or context diff is fine, but
+ port committers appear to prefer unified diff more) of the new
+ and old ports directories to us (e.g., if your modified port
+ directory is called <filename>superedit</filename>
+ and the original as in our tree is
+ <filename>superedit.bak</filename>, then send us the result of
+ <command>diff -ruN superedit.bak
+ superedit</command>). Please examine the output to make
+ sure all the changes make sense. The best way to send us the
+ diff is by including it to <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ (category <literal>ports</literal>). Please mention any added or deleted files
+ in the message, as they have to be explicitly specified to CVS
+ when doing a commit. If the diff is more than about 20KB, please
+ compress and uuencode it; otherwise, just include it in as is in
+ the PR.</para>
+
+ </sect2>
+
+ <sect2>
+ <title><anchor id="porting-dads">Do's and Dont's</title>
+
+ <para>Here is a list of common do's and dont's that you encounter
+ during the porting process.You should check your own port
+ against this list, but you can also check ports in the PR
+ database that others have submitted. Submit any comments on
+ ports you check as described in <link linkend="contrib-general">Bug
+ Reports and General Commentary</link>. Checking ports in
+ the PR database will both make it faster for us to commit them,
+ and prove that you know what you are doing.</para>
+
+ <sect3>
+ <title>Strip Binaries</title>
+
+ <para>Do strip binaries. If the original source already strips the
+ binaries, fine; otherwise you should add a
+ <literal>post-install</literal> rule to to it yourself. Here is an
+ example;</para>
+
+ <programlisting>
+post-install:
+ strip ${PREFIX}/bin/xdl</programlisting>
+
+ <para>Use the <citerefentry>
+ <refentrytitle>file</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry> command on the installed executable to check
+ whether the binary is stripped or not. If it does not say
+ <literal>not stripped</literal>, it is stripped.</para>
+ </sect3>
+
+ <sect3>
+ <title>INSTALL_* macros</title>
+
+ <para>Do use the macros provided in <filename>bsd.port.mk</filename>
+ to ensure correct modes and ownership of files in your own
+ <maketarget>*-install</maketarget> targets. They are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><makevar>INSTALL_PROGRAM</makevar> is a command to install
+ binary executables.</para>
+ </listitem>
+
+ <listitem>
+ <para><makevar>INSTALL_SCRIPT</makevar> is a command to install
+ executable scripts.</para>
+ </listitem>
+
+ <listitem>
+ <para><makevar>INSTALL_DATA</makevar> is a command to install
+ sharable data.</para>
+ </listitem>
+
+ <listitem>
+ <para><makevar>INSTALL_MAN</makevar> is a command to install
+ manpages and other documentation (it doesn't compress
+ anything).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>These are basically the <command>install</command> command
+ with all the appropriate flags. See below for an example on how
+ to use them.</para>
+ </sect3>
+
+ <sect3 id="porting-versions">
+ <title>Differentiating operating systems and OS versions</title>
+
+ <para>You may come across code that needs modifications or
+ conditional compilation based upon what version of UNIX it is
+ running under. If you need to make such changes to the code for
+ conditional compilation, make sure you make the changes as general
+ as possible so that we can back-port code to FreeBSD 1.x systems
+ and cross-port to other BSD systems such as 4.4BSD from CSRG,
+ BSD/386, 386BSD, NetBSD, and OpenBSD.</para>
+
+ <para>The preferred way to tell 4.3BSD/Reno (1990) and newer
+ versions of the BSD code apart is by using the
+ <literal>BSD</literal> macro defined in
+ <filename><sys/param.h></filename>. Hopefully that file is
+ already included; if not, add the code:</para>
+
+ <programlisting>
+#if (defined(__unix__) || defined(unix)) && !defined(USG)
+#include <sys/param.h>
+#endif</programlisting>
+
+ <para>to the proper place in the <filename>.c</filename> file. We
+ believe that every system that defines these to symbols has
+ <filename>sys/param.h</filename>. If you find a system that
+ doesn't, we would like to know. Please send mail to the
+ &a.ports;.</para>
+
+ <para>Another way is to use the GNU Autoconf style of doing
+ this:</para>
+
+ <programlisting>
+#ifdef HAVE_SYS_PARAM_H
+#include <sys/param.h>
+#endif</programlisting>
+
+ <para>Don't forget to add <literal>-DHAVE_SYS_PARAM_H</literal> to
+ the <makevar>CFLAGS</makevar> in the <filename>Makefile</filename>
+ for this method.</para>
+
+ <para>Once you have <filename>sys/param.h</filename>
+ included, you may use:</para>
+
+ <programlisting>
+#if (defined(BSD) && (BSD >= 199103))</programlisting>
+
+ <para>to detect if the code is being compiled on a 4.3 Net2 code
+ base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD,
+ BSD/386 1.1 and below).</para>
+
+ <para>Use:</para>
+
+ <programlisting>
+#if (defined(BSD) && (BSD >= 199306))</programlisting>
+
+ <para>to detect if the code is being compiled on a 4.4 code base
+ or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or
+ above).</para>
+
+ <para>The value of the <literal>BSD</literal> macro is
+ <literal>199506</literal> for the 4.4BSD-Lite2 code base. This is
+ stated for informational purposes only. It should not be used to
+ distinguish between version of FreeBSD based only on 4.4-Lite vs.
+ versions that have merged in changes from 4.4-Lite2. The
+ <literal>__FreeBSD__</literal> macro should be used
+ instead.</para>
+
+ <para>Use sparingly:</para>
+
+
+ <itemizedlist>
+
+ <listitem>
+ <para><literal>__FreeBSD__</literal> is defined in all
+ versions of FreeBSD. Use it if the change you are making
+ <emphasis>only</emphasis> affects FreeBSD. Porting gotchas like the use of
+ <literal>sys_errlist[]</literal> vs
+ <function>strerror()</function> are Berkeleyisms, not
+ FreeBSD changes.</para>
+ </listitem>
+
+ <listitem>
+ <para>In FreeBSD 2.x, <literal>__FreeBSD__</literal> is
+ defined to be <literal>2</literal>. In earlier
+ versions, it is <literal>1</literal>. Later
+ versions will bump it to match their major version number.</para>
+ </listitem>
+
+ <listitem>
+ <para>If you need to tell the difference between a FreeBSD
+ 1.x system and a FreeBSD 2.x or 3.x system, usually the
+ right answer is to use the <literal>BSD</literal> macros
+ described above. If there actually is a FreeBSD specific
+ change (such as special shared library options when using
+ <command>ld</command>) then it is OK to use
+ <literal>__FreeBSD__</literal> and <literal>#if
+ __FreeBSD__ > 1</literal> to detect a FreeBSD 2.x
+ and later system. If you need more granularity in
+ detecting FreeBSD systems since 2.0-RELEASE you can use
+ the following:</para>
+
+ <programlisting>
+#if __FreeBSD__ >= 2
+#include <osreldate.h>
+# if __FreeBSD_version >= 199504
+ /* 2.0.5+ release specific code here */
+# endif
+#endif</programlisting>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Release</entry>
+ <entry><literal>_FreeBSD_version</literal></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>2.0-RELEASE</entry>
+ <entry>119411</entry>
+ </row>
+
+ <row>
+ <entry>2.1-currents</entry>
+ <entry>199501, 199503</entry>
+ </row>
+
+ <row>
+ <entry>2.0.5-RELEASE</entry>
+ <entry>199504</entry>
+ </row>
+
+ <row>
+ <entry>2.2-current before 2.1</entry>
+ <entry>199508</entry>
+ </row>
+
+ <row>
+ <entry>2.1.0-RELEASE</entry>
+ <entry>199511</entry>
+ </row>
+
+ <row>
+ <entry>2.2-current before 2.1.5</entry>
+ <entry>199512</entry>
+ </row>
+
+ <row>
+ <entry>2.1.5-RELEASE</entry>
+ <entry>199607</entry>
+ </row>
+
+ <row>
+ <entry>2.2-current before 2.1.6</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 (no change)</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.1-RELEASE</entry>
+ <entry>220000 (no change)</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after texinfo-3.9</entry>
+ <entry>221001</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after top</entry>
+ <entry>221002</entry>
+ </row>
+
+ <row>
+ <entry>2.2.2-RELEASE</entry>
+ <entry>222000</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.2-RELEASE</entry>
+ <entry>222001</entry>
+ </row>
+
+ <row>
+ <entry>2.2.5-RELEASE</entry>
+ <entry>225000</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.5-RELEASE</entry>
+ <entry>225001</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after ldconfig -R merge</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-STABLE after 2.2.7-RELEASE</entry>
+ <entry>227001</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after semctl(2) change</entry>
+ <entry>227002</entry>
+ </row>
+
+ <row>
+ <entry>2.2.8-RELEASE</entry>
+ <entry>228000</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.8-RELEASE</entry>
+ <entry>228001</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current before mount(2) change</entry>
+ <entry>300000</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after mount(2) change</entry>
+ <entry>300001</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after semctl(2) change</entry>
+ <entry>300002</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after ioctl arg changes</entry>
+ <entry>300003</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after ELF conversion</entry>
+ <entry>300004</entry>
+ </row>
+
+ <row>
+ <entry>3.0-RELEASE</entry>
+ <entry>300005</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after 3.0-RELEASE</entry>
+ <entry>300006</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </listitem>
+ </itemizedlist>
+
+ <note>
+ <para>Note that 2.2-STABLE sometimes identifies itself as
+ “2.2.5-STABLE” after the 2.2.5-RELEASE. The pattern used to
+ be year followed by the month, but we decided to change it
+ to a more straightforward major/minor system starting from
+ 2.2. This is because the parallel development on several
+ branches made it infeasible to classify the releases simply
+ by their real release dates. If you are making a port now,
+ you don't have to worry about old -current's; they are
+ listed here just for your reference.</para>
+ </note>
+
+
+ <para>In the hundreds of ports that have been done, there have
+ only been one or two cases where <literal>__FreeBSD__</literal>
+ should have been used. Just because an earlier port screwed up
+ and used it in the wrong place does not mean you should do so
+ too.</para>
+ </sect3>
+
+ <sect3>
+ <title>Writing something after
+ <filename>bsd.port.mk</filename></title>
+
+ <para>Do not write anything after the <literal>.include
+ <bsd.port.mk></literal> line. it usually can be avoided by
+ including <filename>bsd.port.pre.mk</filename> somewhere in the
+ middle of your <filename>Makefile</filename> and
+ <filename>bsd.port.post.mk</filename> at the end.</para>
+
+ <note>
+ <para>You need to include either the
+ <filename>pre.mk</filename>/<filename>post.mk</filename> pair or
+ <filename>bsd.port.mk</filename> only; don't mix these
+ two.</para>
+ </note>
+
+ <para><filename>bsd.port.pre.mk</filename> only defines a few
+ variables, which can be used in tests in the
+ <filename>Makefile</filename>,
+ <filename>bsd.port.post.mk</filename> defines the rest.</para>
+
+ <para>Here are some important variables defined in
+ <filename>bsd.port.pre.mk</filename> (this is not the complete
+ list, please read <filename>bsd.port.mk</filename> for the
+ complete list).</para>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Variable</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><makevar>ARCH</makevar></entry>
+ <entry>The architecture as returned by <command>uname
+ -m</command> (e.g., <literal>i386</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>OPSYS</makevar></entry>
+ <entry>The operating system type, as returned by
+ <command>uname -s</command> (e.g.,
+ <literal>FreeBSD</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>OSREL</makevar></entry>
+ <entry>The release version of the operating system (e.g.,
+ <literal>2.1.5</literal> or
+ <literal>2.2.7</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>OSVERSION</makevar></entry>
+ <entry>The numeric version of the operating system, same as
+ <link
+ linkend="porting-versions"><literal>__FreeBSD_version</literal></link>.</entry>
+ </row>
+
+ <row>
+ <entry><makevar>PORTOBJFORMAT</makevar></entry>
+ <entry>The object format of the system
+ (<literal>aout</literal> or <literal>elf</literal></entry>
+ </row>
+
+ <row>
+ <entry><makevar>LOCALBASE</makevar></entry>
+ <entry>The base of the “local” tree (e.g.,
+ <literal>/usr/local/</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>X11BASE</makevar></entry>
+ <entry>The base of the “X11” tree (e.g.,
+ <literal>/usr/X11R6</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>PREFIX</makevar></entry>
+ <entry>Where the port installs itself (see <link
+ linkend="porting-prefix">more on
+ <makevar>PREFIX</makevar></link>).</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <note>
+ <para>If you have to define the variables
+ <makevar>USE_IMAKE</makevar>, <makevar>USE_X_PREFIX</makevar>,
+ or <makevar>MASTERDIR</makevar>, do so before including
+ <filename>bsd.port.pre.mk</filename>.</para>
+ </note>
+
+ <para>Here are some examples of things you can write after
+ <filename>bsd.port.pre.mk</filename>;</para>
+
+ <programlisting>
+# no need to compile lang/perl5 if perl5 is already in system
+.if ${OSVERSION} > 300003
+BROKEN= perl is in system
+.endif
+
+# only one shlib version number for ELF
+.if ${PORTOBJFORMAT} == "elf"
+TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}
+.else
+TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}.${SHLIB_MINOR}
+.endif
+
+# software already makes link for ELF, but not for a.out
+post-install:
+.if ${PORTOBJFORMAT} == "aout"
+ ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so
+.endif</programlisting>
+ </sect3>
+
+ <sect3>
+ <title>Install additional documentation</title>
+
+ <para>If your software has some documentation other than the
+ standard man and info pages that you think is useful for the
+ user, install it under
+ <filename><makevar>PREFIX</makevar>/share/doc</filename>. This can be
+ done, like the previous item, in the <maketarget>post-install</maketarget> target.</para>
+
+ <para>Create a new directory for your port. The directory name
+ should reflect what the port is. This usually means <makevar>PKGNAME</makevar> minus the version part.
+ However, if you think the user might want different versions
+ of the port to be installed at the same time, you can use the
+ whole <makevar>PKGNAME</makevar>.</para>
+
+ <para>Make the installation dependent to the variable
+ <makevar>NOPORTDOCS</makevar> so that users can disable it in
+ <filename>/etc/make.conf</filename>, like this:</para>
+
+ <programlisting>
+post-install:
+.if !defined(NOPORTDOCS)
+ ${MKDIR}${PREFIX}/share/doc/xv
+ ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
+.endif</programlisting>
+
+ <para>Do not forget to add them to
+ <filename>pkg/PLIST</filename> too! (Do not worry about
+ <makevar>NOPORTDOCS</makevar> here; there is currently no way
+ for the packages to read variables from
+ <filename>/etc/make.conf</filename>.)</para>
+
+ <para>Also you can use the <filename>pkg/MESSAGE</filename> file to
+ display messages upon installation. See the <link
+ linkend="porting-message">using
+ <filename>pkg/MESSAGE</filename></link> section for
+ details.</para>
+
+ <note>
+ <para><filename>MESSAGE</filename> does not need to be added
+ to <filename>pkg/PLIST</filename>).</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><makevar>DIST_SUBDIR</makevar></title>
+
+ <para>Do not let your port clutter
+ <filename>/usr/ports/distfiles</filename>. If your port
+ requires a lot of files to be fetched, or contains a file that
+ has a name that might conflict with other ports (e.g.,
+ <filename>Makefile</filename>), set <makevar>DIST_SUBDIR</makevar> to the name of the
+ port (<makevar>PKGNAME</makevar> without the
+ version part should work fine). This will change <makevar>DISTDIR</makevar> from the default
+ <filename>/usr/ports/distfiles</filename> to
+ <filename>/usr/ports/distfiles/<makevar>DIST_SUBDIR</makevar></filename>,
+ and in effect puts everything that is required for your port
+ into that subdirectory.</para>
+
+ <para>It will also look at the subdirectory with the same name
+ on the backup master site at
+ <filename>ftp.freebsd.org</filename>. (Setting <makevar>DISTDIR</makevar> explicitly in your
+ <makevar>Makefile</makevar> will not accomplish this, so please use <makevar>DIST_SUBDIR</makevar>.)</para>
+
+ <note>
+ <para>This does not affect the <makevar>MASTER_SITES</makevar> you define in your
+ Makefile.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>Package information</title>
+
+ <para>Do include package information, i.e.
+ <filename>COMMENT</filename>, <filename>DESCR</filename>, and
+ <filename>PLIST</filename>, in <filename>pkg</filename>.</para>
+
+ <note>
+ <para>Note that these files are not used only for packaging
+ anymore, and are <emphasis>mandatory</emphasis> now, even if
+ <makevar>NO_PACKAGE</makevar> is
+ set.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>RCS strings</title>
+
+ <para>Do not put RCS strings in patches. CVS will mangle them
+ when we put the files into the ports tree, and when we check
+ them out again, they will come out different and the patch
+ will fail. RCS strings are surrounded by dollar (<literal>$</literal>) signs, and typically start with
+ <literal>$Id</literal> or <literal>$RCS</literal>.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Recursive diff</title>
+
+ <para>Using the recurse (<option>-r</option>) option to
+ <command>diff</command> to generate patches is
+ fine, but please take a look at the resulting patches to make
+ sure you don't have any unnecessary junk in there. In
+ particular, diffs between two backup files, <filename>Makefiles</filename> when the
+ port uses <command>Imake</command> or GNU <command>configure</command>, etc., are unnecessary and
+ should be deleted. If you had to edit
+ <filename>configure.in</filename> and run
+ <command>autoconf</command> to regenerate
+ <command>configure</command>, do not take the diffs of
+ <command>configure</command> (it often grows to a few thousand
+ lines!); define <literal>USE_AUTOCONF=yes</literal> and take the
+ diffsof <filename>configure.in</filename>.</para>
+
+ <para>Also, if you had to delete a file, then you
+ can do it in the <maketarget>post-extract</maketarget>
+ target rather than as part of the patch. Once you are happy
+ with the resulting diff, please split it up into one source
+ file per patch file.</para>
+
+ </sect3>
+
+ <sect3 id="porting-prefix">
+ <title><makevar>PREFIX</makevar></title>
+
+ <para>Do try to make your port install relative to <makevar>PREFIX</makevar>. (The value of this
+ variable will be set to <makevar>LOCALBASE</makevar> (default
+ <filename>/usr/local</filename>), unless <makevar>USE_X_PREFIX</makevar> or <makevar>USE_IMAKE</makevar> is set, in which case it
+ will be <makevar>X11BASE</makevar> (default
+ <filename>/usr/X11R6</filename>).)</para>
+
+ <para>Not hard-coding <filename>/usr/local</filename> or
+ <filename>/usr/X11R6</filename> anywhere in the source will
+ make the port much more flexible and able to cater to the
+ needs of other sites. For X ports that use <command>imake</command>, this is
+ automatic; otherwise, this can often be done by simply
+ replacing the occurrences of <filename>/usr/local</filename>
+ (or <filename>/usr/X11R6</filename> for X ports that do not
+ use imake) in the various scripts/Makefiles in the port to
+ read <makevar>PREFIX</makevar>, as this
+ variable is automatically passed down to every stage of the
+ build and install processes.</para>
+
+ <para>Do not set <makevar>USE_X_PREFIX</makevar> unless your port
+ truly require it (i.e., it links against X libs or it needs to
+ reference files in <makevar>X11BASE</makevar>).</para>
+
+ <para>The variable <makevar>PREFIX</makevar>
+ can be reassigned in your <filename>Makefile</filename> or in the user's
+ environment. However, it is strongly discouraged for
+ individual ports to set this variable explicitly in the
+ <filename>Makefiles</filename>.</para>
+
+ <para>Also, refer to programs/files from other ports with the
+ variables mentioned above, not explicit pathnames. For
+ instance, if your port requires a macro
+ <literal>PAGER</literal> to be the full pathname of <command>less</command>, use the compiler flag:
+
+ <programlisting>
+-DPAGER=\"${PREFIX}/bin/less\"</programlisting>
+
+ or
+
+ <programlisting>
+-DPAGER=\"${LOCALBASE}/bin/less\"</programlisting>
+
+ if this is an X port, instead of <literal>-DPAGER=\"/usr/local/bin/less\".</literal> This way it will have a better chance of working if the system administrator has moved the whole `/usr/local' tree somewhere else.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Subdirectories</title>
+
+ <para>Try to let the port put things in the right subdirectories
+ of <makevar>PREFIX</makevar>. Some ports
+ lump everything and put it in the subdirectory with the port's
+ name, which is incorrect. Also, many ports put everything
+ except binaries, header files and manual pages in the a
+ subdirectory of <filename>lib</filename>, which does not
+ bode well with the BSD paradigm. Many of the files should be
+ moved to one of the following: <filename>etc</filename>
+ (setup/configuration files), <filename>libexec</filename>
+ (executables started internally), <filename>sbin</filename>
+ (executables for superusers/managers),
+ <filename>info</filename> (documentation for info browser)
+ or <filename>share</filename> (architecture independent
+ files). See man <citerefentry><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+ details, the rule governing <filename>/usr</filename> pretty
+ much applies to <filename>/usr/local</filename> too. The
+ exception are ports dealing with USENET “news”. They may use
+ <filename><makevar>PREFIX</makevar>/news</filename> as a destination for
+ their files.</para>
+
+ </sect3>
+
+ <sect3 id="porting-cleaning">
+ <title>Cleaning up empty directories</title>
+
+ <para>Do make your ports clean up after themselves when they are
+ deinstalled. This is usually accomplished by adding
+ <literal>@dirrm</literal> lines for all directories that are
+ specifically created by the port. You need to delete
+ subdirectories before you can delete parent directories.</para>
+
+ <programlisting>
+ :
+lib/X11/oneko/pixmaps/cat.xpm
+lib/X11/oneko/sounds/cat.au
+ :
+@dirrm lib/X11/oneko/pixmals
+@dirrm lib/X11/oneko/sounds
+@dirrm lib/X11/oneko</programlisting>
+
+ <para>However, sometimes <literal>@dirrm</literal> will give you
+ errors because other ports also share the same subdirectory. You
+ can call <command>rmdir</command> from <literal>@unexec</literal>
+ to remove only empty directories without warning.</para>
+
+ <programlisting>
+@unexec rmdir %D/share/doc/gimp 2>/dev/null || true</programlisting>
+
+ <para>This will neither print any error messages nor cause
+ <command>pkg_delete</command> to exit abnormally even if
+ <filename><makevar>PREFIX</makevar>/share/doc/gimp</filename> is
+ not empty due to other ports installing some files in there.</para>
+ </sect3>
+
+
+ <sect3>
+ <title>UIDs</title>
+
+ <para>If your port requires a certain user to be on the
+ installed system, let the <filename>pkg/INSTALL</filename>
+ script call <command>pw</command> to create it
+ automatically. Look at <filename>net/cvsup-mirror</filename>
+ for an example.</para>
+
+ <para>If your port must use the same user/group ID number when it is
+ installed a binarypackage as when it was compiled, then you mus
+ choose a free UID from 50 to 99 and register it below. Look at
+ <filename>japanese/Wnn</filename> for an example.</para>
+
+ <para>Make sure you don't use a UID already used by the system
+ or other ports. This is the current list of UIDs between 50
+ and 99.</para>
+
+ <programlisting>
+majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent
+cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent
+gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh
+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:/nonexistent
+wnn:*:69:7:Wnn:/nonexistent:/nonexistent
+ifmail:*:70:66:Ifmail user:/nonexistent:/nonexistent
+pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh
+ircd:*:72:72:IRCd hybrid:/nonexistent:/nonexistent
+alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent
+qmaill:*:83:81:QMail user:/var/qmail:/nonexistent
+qmaild:*:82:81:QMail user:/var/qmail:/nonexistent
+qmailq:*:85:82:QMail user:/var/qmail:/nonexistent
+qmails:*:87:82:QMail user:/var/qmail:/nonexistent
+qmailp:*:84:81:QMail user:/var/qmail:/nonexistent
+qmailr:*:86:82:QMail user:/var/qmail:/nonexistent
+msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh</programlisting>
+
+ <para>Please include a notice when you submit a port (or an
+ upgrade) that reserves a new UID or GID in this range. This allows
+ us to keep the list of reserved IDs up to date.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Do things rationally</title>
+
+ <para>The <filename>Makefile</filename> should do things simply and
+ reasonably. If you can make it a couple of lines shorter or more
+ readable, then do so. Examples include using a make
+ <literal>.if</literal> construct instead of a shell
+ <literal>if</literal> construct, not redefining
+ <maketarget>do-extract</maketarget> if you can redefine
+ <makevar>EXTRACT*</makevar> instead, and using
+ <makevar>GNU_CONFIGURE</makevar> instead of
+ <literal>CONFIGURE_ARGS +=
+ --prefix=${PREFIX}</literal>.</para>
+ </sect3>
+
+ <sect3>
+ <title>Respect <makevar>CFLAGS</makevar></title>
+
+ <para>The port should respect the <makevar>CFLAGS</makevar>
+ variable. If it doesn't, please add <literal>NO_PACKAGE=ignores
+ cflags</literal> to the <filename>Makefile</filename>.</para>
+ </sect3>
+
+ <sect3>
+ <title>Configuration files</title>
+
+ <para>If your port requires some configuration files in
+ <filename><makevar>PREFIX</makevar>/etc</filename>, do
+ <emphasis>not</emphasis> just install them and list them in
+ <filename>pkg/PLIST</filename>. That will cause
+ <command>pkg_delete</command> to delete files carefully edited by
+ the user and a new installation to wipe them out.</para>
+
+ <para>Instead, install sample files with a suffix
+ (<filename><replaceable>filename</replaceable>.sample</filename>
+ will work well) and print out a <link
+ linkend="porting-message">message</link> pointing out that the
+ user has to copy and edit the file before the software can be made
+ to work.</para>
+ </sect3>
+
+ <sect3>
+ <title>Portlint</title>
+
+ <para>Do check your work with <link
+ linkend="porting-portlint"><command>portlint</command></link>
+ before you submit or commit it.</para>
+ </sect3>
+
+ <sect3>
+ <title>Feedback</title>
+
+ <para>Do send applicable changes/patches to the original
+ author/maintainer for inclusion in next release of the code. This
+ will only make your job that much easier for the next
+ release.</para>
+ </sect3>
+
+ <sect3>
+ <title>Miscellanea</title>
+
+ <para>The files <filename>pkg/DESCR</filename>,
+ <filename>pkg/COMMENT</filename>, and
+ <filename>pkg/PLIST</filename> should each be double-checked. If
+ you are reviewing a port and feel they can be worded better, do
+ so.</para>
+
+ <para>Don't copy more copies of the GNU General Public License into
+ our system, please.</para>
+
+ <para>Please be careful to note any legal issues! Don't let us
+ illegally distribute software!</para>
+ </sect3>
+
+ <sect3>
+ <title>If you are stuck…</title>
+
+ <para>Do look at existing examples and the
+ <filename>bsd.port.mk</filename> file before asking us
+ questions! <!-- smiley --><emphasis>;)</emphasis></para>
+
+ <para>Do ask us questions if you have any trouble! Do not just
+ beat your head against a wall! <!-- smiley --><emphasis>:)</emphasis></para>
+
+ </sect3>
+ </sect2>
+
+ <sect2 id="porting-samplem">
+ <title>A Sample <filename>Makefile</filename></title>
+
+ <para>Here is a sample <filename>Makefile</filename> that you can
+ use to create a new port. Make sure you remove all the extra
+ comments (ones between brackets)!</para>
+
+ <para>It is recommended that you follow this format (ordering of
+ variables, empty lines between sections, etc.). This format is
+ designed so that the most important information is easy to
+ locate. We recommend that you use <link
+ linkend="porting-portlint">portlint</link> to check the <filename>Makefile</filename>.</para>
+
+ <programlisting>
+[the header...just to make it easier for us to identify the ports.]
+# New ports collection makefile for: xdvi
+[the version required header should updated when upgrading a port.]
+# Version required: pl18 [things like "1.5alpha" are fine here too]
+[this is the date when the first version of this Makefile was created.
+Never change this when doing an update of the port.]
+# Date created: 26 May 1995
+[this is the person who did the original port to FreeBSD, in particular, the
+person who wrote the first version of this Makefile. Remember, this should
+not be changed when upgrading the port later.]
+# Whom: Satoshi Asami <asami@FreeBSD.ORG>
+#
+# $Id$
+[ ^^^^ This will be automatically replaced with RCS ID string by CVS
+when it is committed to our repository.]
+#
+
+[section to describe the port itself and the master site - DISTNAME
+ is always first, followed by PKGNAME (if necessary), CATEGORIES,
+ and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR.
+ After those, one of EXTRACT_SUFX or DISTFILES can be specified too.]
+DISTNAME= xdvi
+PKGNAME= xdvi-pl18
+CATEGORIES= print
+[do not forget the trailing slash ("/")!
+ if you aren't using MASTER_SITE_* macros]
+MASTER_SITES= ${MASTER_SITE_XCONTRIB}
+MASTER_SITE_SUBDIR= applications
+[set this if the source is not in the standard ".tar.gz" form]
+EXTRACT_SUFX= .tar.Z
+
+[section for distributed patches -- can be empty]
+PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/
+PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz
+
+[maintainer; *mandatory*! This is the person (preferably with commit
+ privileges) who a user can contact for questions and bug reports - this
+ person should be the porter or someone who can forward questions to the
+ original porter reasonably promptly. If you really do not want to have
+ your address here, set it to "ports@FreeBSD.ORG".]
+MAINTAINER= asami@FreeBSD.ORG
+
+[dependencies -- can be empty]
+RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript
+LIB_DEPENDS= Xpm.5:${PORTSDIR}/graphics/xpm
+
+[this section is for other standard bsd.port.mk variables that do not
+ belong to any of the above]
+[If it asks questions during configure, build, install...]
+IS_INTERACTIVE= yes
+[If it extracts to a directory other than ${DISTNAME}...]
+WRKSRC= ${WRKDIR}/xdvi-new
+[If the distributed patches were not made relative to ${WRKSRC}, you
+ may need to tweak this]
+PATCH_DIST_STRIP= -p1
+[If it requires a "configure" script generated by GNU autoconf to be run]
+GNU_CONFIGURE= yes
+[If it requires GNU make, not /usr/bin/make, to build...]
+USE_GMAKE= yes
+[If it is an X application and requires "xmkmf -a" to be run...]
+USE_IMAKE= yes
+[et cetera.]
+
+[non-standard variables to be used in the rules below]
+MY_FAVORITE_RESPONSE= "yeah, right"
+
+[then the special rules, in the order they are called]
+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
+
+[and then the epilogue]
+.include <bsd.port.mk></programlisting>
+
+ </sect2>
+
+ <sect2 id="porting-pkgname">
+ <title>Package Names</title>
+
+ <para>The following are the conventions you should follow in
+ naming your packages. This is to have our package directory
+ easy to scan, as there are already lots and lots of packages and
+ users are going to turn away if they hurt their eyes!</para>
+
+ <para>The package name should look like <filename><replaceable>language-</replaceable>name<replaceable>-compiled.specifics</replaceable><replaceable>-version.numbers</replaceable></filename>.</para>
+
+ <para>If your <makevar>DISTNAME</makevar>
+ doesn't look like that, set <makevar>PKGNAME</makevar> to something in that
+ format.</para>
+
+
+ <orderedlist>
+
+ <listitem>
+ <para>FreeBSD strives to support the native language of its
+ users. The <replaceable>language-</replaceable> part should be a two letter
+ abbreviation of the natural language defined by ISO-639 if
+ the port is specific to a certain language. Examples are
+ <literal>ja</literal> for Japanese, <literal>ru</literal> for Russian, <literal>vi</literal> for Vietnamese,
+ <literal>zh</literal> for Chinese, <literal>ko</literal> for Korean and <literal>de</literal> for German.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <filename>name</filename> part
+ should be all lowercases, except for a really large
+ package (with lots of programs in it). Things like
+ XFree86 (yes there really is a port of it, check it
+ out) and ImageMagick fall into this category. Otherwise,
+ convert the name (or at least the first letter) to
+ lowercase. If the capital letters are
+ important to the name (for example, with one-letter names
+ like <literal>R</literal> or <literal>V</literal>) you may use capital letters at your discretion.
+ There is a tradition of naming Perl 5 modules by prepending
+ <literal>p5-</literal> and converting the double-colon separator to a hyphen;
+ for example, the <literal>Data::Dumper</literal> module becomes
+ <literal>p5-Data-Dumper</literal>. If the software in question has numbers,
+ hyphens, or underscores in its name, you may include them as
+ well (like <literal>kinput2</literal>).</para>
+ </listitem>
+
+ <listitem>
+ <para>If the port can be built with different <link linkend="porting-masterdir">hardcoded
+ defaults</link> (usually part of the directory name in a
+ family of ports), the
+ <replaceable>-compiled.specifics</replaceable> part should state the
+ compiled-in defaults (the hyphen is optional). Examples
+ are papersize and font units.</para>
+ </listitem>
+
+ <listitem>
+ <para>The version string should be a period-separated list
+ of integers and single lowercase alphabetics. The only
+ exception is the string <literal>pl</literal> (meaning `patchlevel'), which
+ can be used <emphasis>only</emphasis> when there are no
+ major and minor version numbers in the software.</para>
+ </listitem>
+
+ </orderedlist>
+
+
+ <para>Here are some (real) examples on how to convert a <makevar>DISTNAME</makevar> into a suitable <makevar>PKGNAME</makevar>:</para>
+
+ <informaltable frame="none">
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Distribution Name</entry>
+ <entry>Package Name</entry>
+ <entry>Reason</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>mule-2.2.2.</entry>
+ <entry>mule-2.2.2</entry>
+ <entry>No changes required</entry>
+ </row>
+
+ <row>
+ <entry>XFree86-3.1.2</entry>
+ <entry>XFree86-3.1.2</entry>
+ <entry>No changes required</entry>
+ </row>
+
+ <row>
+ <entry>EmiClock-1.0.2</entry>
+ <entry>emiclock-1.0.2</entry>
+ <entry>No uppercase names for single programs</entry>
+ </row>
+
+ <row>
+ <entry>gmod1.4</entry>
+ <entry>gmod-1.4</entry>
+ <entry>Need a hyphen before version numbers</entry>
+ </row>
+
+ <row>
+ <entry>xmris.4.0.2</entry>
+ <entry>xmris-4.0.2</entry>
+ <entry>Need a hyphen before version numbers</entry>
+ </row>
+
+ <row>
+ <entry>rdist-1.3alpha</entry>
+ <entry>rdist-1.3a</entry>
+ <entry>No strings like <literal>alpha</literal>
+ allowed</entry>
+ </row>
+
+ <row>
+ <entry>es-0.9-beta1</entry>
+ <entry>es-0.9b1</entry>
+ <entry>No strings like <literal>beta</literal>
+ allowed</entry>
+ </row>
+
+ <row>
+ <entry>v3.3beta021.src</entry>
+ <entry>tiff-3.3</entry>
+ <entry>What the heck was that anyway?</entry>
+ </row>
+
+ <row>
+ <entry>tvtwm</entry>
+ <entry>tvtwm-pl11</entry>
+ <entry>Version string always required</entry>
+ </row>
+
+ <row>
+ <entry>piewm</entry>
+ <entry>piewm-1.0</entry>
+ <entry>Version string always required</entry>
+ </row>
+
+ <row>
+ <entry>xvgr-2.10pl1</entry>
+ <entry>xvgr-2.10.1</entry>
+ <entry><literal>pl</literal> allowed only when no
+ major/minor version numbers</entry>
+ </row>
+
+ <row>
+ <entry>gawk-2.15.6</entry>
+ <entry>ja-gawk-2.15.6</entry>
+ <entry>Japanese language version</entry>
+ </row>
+
+ <row>
+ <entry>psutils-1.13</entry>
+ <entry>psutils-letter-1.13</entry>
+ <entry>Papersize hardcoded at package build time</entry>
+ </row>
+
+ <row>
+ <entry>pkfonts</entry>
+ <entry>pkfonts300-1.0</entry>
+ <entry>Package for 300dpi fonts</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>If there is absolutely no trace of version information in
+ the original source and it is unlikely that the original author
+ will ever release another version, just set the version string
+ to <literal>1.0</literal> (like the piewm example above). Otherwise, ask the
+ original author or use the date string (<literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>) as the
+ version.</para>
+
+ </sect2>
+
+ <sect2 id="porting-categories">
+ <title>Categories</title>
+
+ <para>As you already know, ports are classified in several
+ categories. But for this to wor, it is important that porters and
+ users understand what each category and how we deicde what to put in
+ each category.</para>
+
+ <sect3>
+ <title>Current list of categories</title>
+
+ <para>First, this is the current list of port categories. Those
+ marked with an asterisk (<literal>*</literal>) are
+ <emphasis>virtual</emphasis> categories—those that do not
+ have a corresponding subdirectory in the ports tree.</para>
+
+ <note>
+ <para>For non-virtual categories, you will find a one-line
+ description in the <filename>pkg/COMMENT</filename> file in that
+ subdirectory (e.g.,
+ <filename>archivers/pkg/COMMENT</filename>).</para>
+ </note>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Category</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><filename>archivers</filename></entry>
+ <entry>Archiving tools.</entry>
+ </row>
+
+ <row>
+ <entry><filename>astro</filename></entry>
+ <entry>Astronomical ports.</entry>
+ </row>
+
+ <row>
+ <entry><filename>audio</filename></entry>
+ <entry>Sound support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>benchmarks</filename></entry>
+ <entry>Benchmarking utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>biology</filename></entry>
+ <entry>Biology-related software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>cad</filename></entry>
+ <entry>Computer aided design tools.</entry>
+ </row>
+
+ <row>
+ <entry><filename>chinese</filename></entry>
+ <entry>Chinese language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>comms</filename></entry>
+ <entry>Communication software. Mostly software to talk to
+ your serial port.</entry>
+ </row>
+
+ <row>
+ <entry><filename>converters</filename></entry>
+ <entry>Character code converters.</entry>
+ </row>
+
+ <row>
+ <entry><filename>databases</filename></entry>
+ <entry>Databases.</entry>
+ </row>
+
+ <row>
+ <entry><filename>deskutils</filename></entry>
+ <entry>Things that used to be on the desktop before
+ computers were invented.</entry>
+ </row>
+
+ <row>
+ <entry><filename>devel</filename></entry>
+ <entry>Development utilities. Do not put libraries here just
+ because they are libraries—unless they truly don't
+ belong to anywhere else, they shouldn't be in this
+ category.</entry>
+ </row>
+
+ <row>
+ <entry><filename>editors</filename></entry>
+ <entry>General editors. Specialized editors go in the
+ section for those tools (e.g., a mathematical-formula
+ editor will go in <filename>math</filename>).</entry>
+ </row>
+
+ <row>
+ <entry><filename>elisp</filename></entry>
+ <entry>Emacs-lisp ports.</entry>
+ </row>
+
+ <row>
+ <entry><filename>emulators</filename></entry>
+ <entry>Emulators for other operating systems. Terminal
+ emulators do <emphasis>not</emphasis> belong
+ here—X-based ones should go to
+ <filename>x11</filename> and text-based ones to either
+ <filename>comms</filename> or <filename>misc</filename>,
+ depending on the exact functionality.</entry>
+ </row>
+
+ <row>
+ <entry><filename>games</filename></entry>
+ <entry>Games.</entry>
+ </row>
+
+ <row>
+ <entry><filename>german</filename></entry>
+ <entry>German language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>graphics</filename></entry>
+ <entry>Graphics utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>japanese</filename></entry>
+ <entry>Japanese language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>kde*</filename></entry>
+ <entry>Ports that form the K Desktop Environment
+ (kde).</entry>
+ </row>
+
+ <row>
+ <entry><filename>korean</filename></entry>
+ <entry>Korean language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>lang</filename></entry>
+ <entry>Programming languages.</entry>
+ </row>
+
+ <row>
+ <entry><filename>mail</filename></entry>
+ <entry>Mail software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>math</filename></entry>
+ <entry>Numerical computation software and other utilities
+ for mathematics.</entry>
+ </row>
+
+ <row>
+ <entry><filename>mbone</filename></entry>
+ <entry>MBone applications.</entry>
+ </row>
+
+ <row>
+ <entry><filename>misc</filename></entry>
+ <entry>Miscellaneous utilities—basically things that
+ doesn't belong to anywhere else. This is the only category
+ that should not appear with any other non-virtual
+ category. If you have <literal>misc</literal> with
+ something else in your <makevar>CATEGORIES</makevar> line,
+ that means you can safely delete <literal>misc</literal>
+ and just put the port in that other subdirectory!</entry>
+ </row>
+
+ <row>
+ <entry><filename>net</filename></entry>
+ <entry>Miscellaneous networking software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>news</filename></entry>
+ <entry>USENET news software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>offix*</filename></entry>
+ <entry>Ports from the OffiX suite.</entry>
+ </row>
+
+ <row>
+ <entry><filename>perl5*</filename></entry>
+ <entry>Ports that require perl version 5 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>pilot*</filename></entry>
+ <entry>Software to use with the 3Com PalmPilot.</entry>
+ </row>
+
+ <row>
+ <entry><filename>plan9</filename></entry>
+ <entry>Various programs from Plan9.</entry>
+ </row>
+
+ <row>
+ <entry><filename>print</filename></entry>
+ <entry>Printing software. Desktop publishing tools
+ (previewers, etc.) belong here too.</entry>
+ </row>
+
+ <row>
+ <entry><filename>python*</filename></entry>
+ <entry>Software written in python.</entry>
+ </row>
+
+ <row>
+ <entry><filename>russian</filename></entry>
+ <entry>Russian language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>security</filename></entry>
+ <entry>Security utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>shells</filename></entry>
+ <entry>Command line shells.</entry>
+ </row>
+
+ <row>
+ <entry><filename>sysutils</filename></entry>
+ <entry>System utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl75*</filename></entry>
+ <entry>Ports that use tcl version 7.5 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl76*</filename></entry>
+ <entry>Ports that use tcl version 7.6 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl80*</filename></entry>
+ <entry>Ports that use tcl version 8.0 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl81*</filename></entry>
+ <entry>Ports that use tcl version 8.1 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>textproc</filename></entry>
+ <entry>Text processing utilities. It does not include
+ desktop publishing tools, which go to print/.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk41*</filename></entry>
+ <entry>Ports that use tk version 4.1 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk42*</filename></entry>
+ <entry>Ports that use tk version 4.2 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk80*</filename></entry>
+ <entry>Ports that use tk version 8.0 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk81*</filename></entry>
+ <entry>Ports that use tk version 8.1 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>vietnamese</filename></entry>
+ <entry>Vietnamese language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>www</filename></entry>
+ <entry>Software related to the World Wide Web. HTML language
+ support belong here too.</entry>
+ </row>
+
+ <row>
+ <entry>x11</entry>
+ <entry>The X window system and friends. This category is
+ only for software that directly support the window system.
+ Do not put regular X applications here. If your port is
+ an X application, define <makevar>USE_XLIB</makevar>
+ (implied by <makevar>USE_IMAKE</makevar>) and put it in
+ appropriate categories. Also, many of them go into other
+ <filename>x11-*</filename> categories (see below).</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-clocks</filename></entry>
+ <entry>X11 clocks.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-fm</filename></entry>
+ <entry>X11 file managers.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-fonts</filename></entry>
+ <entry>X11 fonts and font utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-toolkits</filename></entry>
+ <entry>X11 toolkits.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-wm</filename></entry>
+ <entry>X11 window managers.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect3>
+
+ <sect3>
+ <title>Choosing the right category</title>
+
+ <para>As many of the categories overlap, you often have to choose
+ which of the categories should be the primary category of your
+ port. There are several rules that govern this usse. Here is the
+ list of priorities, in decreasing order of precedence.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Language specific categories alwasys come first. For
+ example, if your port installs Japanese X11 fonts, then your
+ <makevar>CATEGORIES</makevar> line would read
+ <literal>japanese x11</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Specific categories win over less-specific ones. For
+ instance, an HTML editor should be listed as <literal>www
+ editors</literal>, not the other way around. Also, you don't
+ need to list <literal>net</literal> when the port belongs to
+ either of <literal>mail</literal>, <literal>mbone</literal>,
+ <literal>news</literal>, <literal>security</literal>, or
+ <literal>www</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>x11</literal> is used as a secondary category
+ only when the primary category is a natural language. In
+ particular, you should not put <literal>x11</literal> in the
+ category line for X applications.</para>
+ </listitem>
+
+ <listitem>
+ <para>If your port truly does not belong anywhere else, put it
+ in <literal>misc</literal>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>If you are not sure about the category, please put a comment
+ to that effect in your <command>send-pr</command> submission so we
+ can discuss it before import it. (If you are a committer, send a
+ note &a.ports; so we can discuss it first—too often new
+ ports are imported to a wrong category only to be moved right
+ away.)</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Changes to this document and the ports system</title>
+
+ <para>If you maintain a lot of ports, you should consider following
+ the &a.ports;. Important changes to
+ the way ports work will be announced there. You can always
+ find more detailed information on the latest changes by
+ looking at <ulink
+ url="http://www.FreeBSD.ORG/cgi/cvsweb.cgi/src/share/mk/bsd.port.mk">
+ the bsd.port.mk CVS log</ulink>.</para>
+ </sect2>
+
+ <sect2>
+ <title>That is It, Folks!</title>
+
+ <para>Boy, this sure was a long tutorial, wasn't it? Thanks for
+ following us to here, really.</para>
+
+ <para>Well, now that you know how to do a port, let us go at it
+ and convert everything in the world into ports! That is the
+ easiest way to start contributing to the FreeBSD Project!
+ <!-- smiley --><emphasis>:)</emphasis></para>
+
+ </sect2>
+ </sect1>
+
</chapter>
@@ -1053,9 +4516,7 @@ grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arc
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml b/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml
index b0d244ca37..a83def5913 100644
--- a/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml
@@ -2561,9 +2561,7 @@ import proto rip interface ed {
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/printing/chapter.sgml b/en_US.ISO8859-1/books/handbook/printing/chapter.sgml
index f1937d3edf..6bbaf37a71 100644
--- a/en_US.ISO8859-1/books/handbook/printing/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/printing/chapter.sgml
@@ -2839,13 +2839,13 @@ if [ "$first_two_chars" = "%!" ]; then
#
# PostScript job, print it.
#
- echo $first_line && cat && printf "\004" && exit 0
+ echo "$first_line" && cat && printf "\004" && exit 0
exit 2
else
#
# Plain text, convert it, then print it.
#
- ( echo $first_line; cat ) | /usr/local/bin/textps && printf "\004" && exit 0
+ ( echo "$first_line"; cat ) | /usr/local/bin/textps && printf "\004" && exit 0
exit 2
fi</programlisting>
@@ -2919,7 +2919,7 @@ else
# Plain text or HP/PCL, so just print it directly; print a form
# at the end to eject the last page.
#
- echo $first_line && cat && printf "\f" && exit 0
+ echo "$first_line" && cat && printf "\f" && exit 0
fi
exit 2</programlisting>
@@ -4912,9 +4912,7 @@ total 337.00 154 $ 6.74</screen>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/security/chapter.sgml b/en_US.ISO8859-1/books/handbook/security/chapter.sgml
index b620aeb316..00fcb1dc43 100644
--- a/en_US.ISO8859-1/books/handbook/security/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/security/chapter.sgml
@@ -1703,9 +1703,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml
index 59b6b828f9..c6112d3bcf 100644
--- a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml
@@ -2090,9 +2090,7 @@ raisechar=^^</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/staff/chapter.sgml b/en_US.ISO8859-1/books/handbook/staff/chapter.sgml
index 350c823cb5..b34fa0411c 100644
--- a/en_US.ISO8859-1/books/handbook/staff/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/staff/chapter.sgml
@@ -128,14 +128,6 @@
<para>&a.dburr;</para>
</listitem>
- <listitem>
- <para>&a.danny;</para>
- </listitem>
-
- <listitem>
- <para>&a.thepish;</para>
- </listitem>
-
<listitem>
<para>&a.charnier;</para>
</listitem>
@@ -155,7 +147,11 @@
<listitem>
<para>&a.gclarkii;</para>
</listitem>
-
+
+ <listitem>
+ <para>&a.archie</para>
+ </listitem>
+
<listitem>
<para>&a.cracauer;</para>
</listitem>
@@ -212,14 +208,18 @@
<para>&a.jfitz;</para>
</listitem>
- <listitem>
- <para>&a.lars;</para>
- </listitem>
-
<listitem>
<para>&a.scrappy;</para>
</listitem>
+ <listitem>
+ <para>&a.lars;</para>
+ </listitem>
+
+ <listitem>
+ <para>&a.billf;</para>
+ </listitem>
+
<listitem>
<para>&a.tg;</para>
</listitem>
@@ -247,23 +247,35 @@
<listitem>
<para>&a.hanai;</para>
</listitem>
-
+
+ <listitem>
+ <para>&a.thepish;</para>
+ </listitem>
+
<listitem>
<para>&a.jhay;</para>
</listitem>
+ <listitem>
+ <para>&a.helbig;</para>
+ </listitem>
+
<listitem>
<para>&a.ghelmer;</para>
</listitem>
- <listitem>
- <para>&a.helbig;</para>
- </listitem>
-
<listitem>
<para>&a.erich;</para>
</listitem>
+ <listitem>
+ <para>&a.nhibma;</para>
+ </listitem>
+
+ <listitem>
+ <para>&a.flathill;</para>
+ </listitem>
+
<listitem>
<para>&a.hosokawa;</para>
</listitem>
@@ -279,7 +291,11 @@
<listitem>
<para>&a.itojun;</para>
</listitem>
-
+
+ <listitem>
+ <para>&a.mjacob;</para>
+ </listitem>
+
<listitem>
<para>&a.gj;</para>
</listitem>
@@ -319,7 +335,11 @@
<listitem>
<para>&a.jlemon;</para>
</listitem>
-
+
+ <listitem>
+ <para>&a.truckman;</para>
+ </listitem>
+
<listitem>
<para>&a.imp;</para>
</listitem>
@@ -372,6 +392,10 @@
<para>&a.obrien;</para>
</listitem>
+ <listitem>
+ <para>&a.danny;</para>
+ </listitem>
+
<listitem>
<para>&a.ljo;</para>
</listitem>
@@ -391,7 +415,11 @@
<listitem>
<para>&a.jmacd;</para>
</listitem>
-
+
+ <listitem>
+ <para>&a.wes;</para>
+ </listitem>
+
<listitem>
<para>&a.steve;</para>
</listitem>
@@ -435,7 +463,11 @@
<listitem>
<para>&a.dima;</para>
</listitem>
-
+
+ <listitem>
+ <para>&a.sada;</para>
+ </listitem>
+
<listitem>
<para>&a.wosch;</para>
</listitem>
@@ -512,10 +544,6 @@
<para>&a.jmz;</para>
</listitem>
- <listitem>
- <para>&a.hosokawa;</para>
- </listitem>
-
<listitem>
<para>&a.archie;</para>
</listitem>
@@ -536,8 +564,9 @@
<variablelist>
<varlistentry><term>Documentation Project Manager</term>
- <listitem>
- <para><emphasis>currently vacant</emphasis></para>
+
+ <listitem>
+ <para>&a.nik;</para>
</listitem>
</varlistentry>
@@ -545,7 +574,7 @@
<varlistentry><term>Webmaster</term>
<listitem>
- <para>&a.wosch;;</para>
+ <para>&a.wosch;</para>
</listitem>
</varlistentry>
@@ -641,7 +670,7 @@
url="http://www.freebsd.org/docproj/docproj.html">Documentation Project Manager</ulink></term>
<listitem>
- <para><emphasis>currently vacant</emphasis></para>
+ <para>&a.nik;</para>
</listitem>
</varlistentry>
@@ -758,9 +787,7 @@
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml
index 3d6c6c5c05..e8fb397095 100644
--- a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml
@@ -13,9 +13,7 @@
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml
index aa5d962c4a..092d021ad9 100644
--- a/en_US.ISO8859-1/books/porters-handbook/book.sgml
+++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml
@@ -88,7 +88,7 @@
<title>How Does the Ports Collection Work?</title>
<para>Programs are typically distributed on the Internet as a
- <xref linkend="ports-tarball" remap="tarball"> consisting of a
+ <link linkend="ports-tarball">tarball</link> consisting of a
Makefile and the source code for the program and usually some
instructions (which are unfortunately not always as instructive as
they could be), with perhaps a configuration script.</para>
@@ -100,18 +100,18 @@
from the source.</para>
<para>FreeBSD ports still use the tarball mechanism, but use a
- <xref linkend="ports-skeleton" remap="skeleton"> to hold the
+ <link linkend="ports-skeleton">skeleton</link> to hold the
"knowledge" of how to get the program working on FreeBSD,
rather than expecting the user to be able to work it out. They also
supply their own customised
- <xref linkend="ports-makefile" remap="Makefile">, so that almost
+ <link linkend="ports-makefile">Makefile</link>, so that almost
every port can be built in the same way.</para>
<para>If you look at a port skeleton (either on <ulink
URL="file://localhost/usr/ports/devel/ElectricFence">your FreeBSD
system</ulink> or <ulink
- URL="ftp://ftp.freebsd.org/pub/FreeBSD/ports/devel/ElectricFence">the FTP site</ulink>) and expect to find all sorts of pointy-headed rocket science lurking there, you may be disappointed by the one or two rather unexciting-looking files and directories you find there. (We will discuss in a minute how to go about <xref
- linkend="ports-getting" remap="Getting a port">).</para>
+ URL="ftp://ftp.freebsd.org/pub/FreeBSD/ports/devel/ElectricFence">the FTP site</ulink>) and expect to find all sorts of pointy-headed rocket science lurking there, you may be disappointed by the one or two rather unexciting-looking files and directories you find there. (We will discuss in a minute how to go about <link
+ linkend="ports-getting">Getting a port</link>).</para>
<para>“How on earth can this do anything?” I hear you cry. “There
is no source code there!”</para>
@@ -171,13 +171,12 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<procedure>
<step>
- <para>Locate the source code <xref linkend="ports-tarball"
- remap="tarball."> If it is not available locally, try to
+ <para>Locate the source code <link linkend="ports-tarball">tarball.</link> If it is not available locally, try to
grab it from an FTP site.</para>
</step>
<step>
- <para>Run a <xref linkend="ports-checksum" remap="checksum">
+ <para>Run a <link linkend="ports-checksum">checksum</link>
test on the tarball to make sure it has not been tampered
with, accidentally truncated, downloaded in ASCII mode, struck
by neutrinos while in transit, etc.</para>
@@ -188,7 +187,7 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
</step>
<step>
- <para>Apply any <xref linkend="ports-patch" remap="patches">
+ <para>Apply any <link linkend="ports-patch">patches</link>
needed to get the source to compile and run under FreeBSD.</para>
</step>
@@ -212,8 +211,8 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<step>
<para>Register the installation in a database. This means that,
- if you do not like the program, you can cleanly <xref
- linkend="ports-remove" remap="remove"> all traces of it from
+ if you do not like the program, you can cleanly <link
+ linkend="ports-remove">remove</link> all traces of it from
your system.</para>
</step>
@@ -230,85 +229,28 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<title>Getting a FreeBSD Port</title>
<para>There are two ways of getting hold of the FreeBSD port for a
- program. One requires a <xref linkend="ports-cd" remap="FreeBSD
- CDROM">, the other involves using an <xref linkend="ports-inet"
- remap="Internet Connection."></para>
+ program. One requires a <link linkend="ports-cd">FreeBSD
+ CDROM</link>, the other involves using an <link linkend="ports-inet">Internet Connection.</link></para>
<sect2 id="ports-cd">
<title>Compiling ports from CDROM</title>
-
- <para>If you answered yes to the question “Do you want to link the
- ports collection to your CDROM” during the FreeBSD installation,
- the initial setting up will already have been done for you.</para>
-
- <para>If not, make sure the <emphasis>FreeBSD</emphasis> CDROM is in
- the drive and mounted on, say, <filename>/cdrom</filename>. Then
- do</para>
-
- <informalexample>
- <screen>&prompt.root; <userinput>mkdir /usr/ports</userinput>
-&prompt.root; <userinput>cd /usr/ports</userinput>
-&prompt.root; <userinput>ln -s /cdrom/ports/distfiles distfiles</userinput></screen>
- </informalexample>
-
- <para>to enable the ports make mechanism to find the tarballs (it
- expects to find them in <filename>/usr/ports/distfiles</filename>,
- which is why we sym-linked the CDROM's tarball directory to that
- directory).</para>
-
- <para>Now, suppose you want to install the gnats program from the
- databases directory. Here is how to do it:-</para>
-
- <informalexample>
- <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
-&prompt.root; <userinput>mkdir databases</userinput>
-&prompt.root; <userinput>cp -R /cdrom/ports/databases/gnats databases</userinput>
-&prompt.root; <userinput>cd databases/gnats</userinput>
-&prompt.root; <userinput>make install</userinput></screen>
- </informalexample>
-
- <para>Or if you are a serious database user and you want to compare
- all the ones available in the Ports collection, do</para>
-
- <informalexample>
- <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
-&prompt.root; <userinput>cp -R /cdrom/ports/databases .</userinput>
-&prompt.root; <userinput>cd databases</userinput>
-&prompt.root; <userinput>make install</userinput></screen>
- </informalexample>
-
- <para>(yes, that really is a dot on its own after the <command>cp</command> command and
- not a mistake. It is Unix-ese for “the current
- directory”) and the ports make mechanism will automatically compile and
- install all the ports in the databases directory for you!</para>
-
- <para>If you do not like this method, here is a completely different
- way of doing it:-</para>
-
- <para>Create a “link tree” to it using the
- <citerefentry><refentrytitle>lndir</refentrytitle><manvolnum>1</manvolnum></citerefentry> command that comes with the
- <emphasis>XFree86</emphasis> distribution. Find a location with
- some free space, create a directory there and then cd to it. Then
- invoke the <citerefentry><refentrytitle>lndir</refentrytitle><manvolnum>1</manvolnum></citerefentry> command with the full
- pathname of the <filename>ports</filename> directory on the CDROM as the first
- argument and . (the current directory) as the second. This might
- be, for example, something like:</para>
- <informalexample>
- <screen>&prompt.root; <userinput>lndir /cdrom/ports .</userinput></screen>
- </informalexample>
-
- <para>Then you can build ports directly off the CDROM by building
- them in the link tree you have created.</para>
-
- <para>Note that there are some ports for which we cannot provide the
+ <para>Assuming that your FreeBSD CDROM is in the drive and mounted on
+ <filename>/cdrom</filename> (and the mount point
+ <emphasis>must</emphasis> be <filename>/cdrom</filename>), you should
+ then be able to build ports just as you normally do and the port
+ collection's built in search path should find the tarballs in
+ <filename>/cdrom/ports/distfiles/</filename> (if they exist there)
+ rather than downloading them over the net.</para>
+
+ <note>
+ <para>There are some ports for which we cannot provide the
original source in the CDROM due to licensing limitations. In
- that case, you will need to look at the section on <xref
- linkend="ports-inet"
- remap="Compiling ports using an Internet connection."></para>
-
- </sect2>
+ that case, you will need to look at the section on <link
+ linkend="ports-inet">Compiling ports using an Internet connection.</link></para>
+ </note>
+ </sect2>
<sect2 id="ports-inet">
<title>Compiling ports from the Internet</title>
@@ -316,13 +258,20 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<para>If you do not have a CDROM, or you want to make sure you get
the very latest version of the port you want, you will need to
download the
- <xref linkend="ports-skeleton" remap="skeleton"> for the port. Now
+ <link linkend="ports-skeleton">skeleton</link> for the port. Now
this might sound like rather a fiddly job full of pitfalls, but
it is actually very easy.</para>
-
- <para>The key to it is that the FreeBSD FTP server can create
+
+ <para>First, if you are running a release version of FreeBSD, make
+ sure you get the appropriate “upgradekiet” for your
+ replease from the <ulink url="http://www.freebsd.org/ports/">ports
+ web page</ulink>. These packages include files that have been
+ updated since the release that you may need to compile new
+ ports.</para>
+
+ <para>The key to the skeletons is that the FreeBSD FTP server can create
on-the-fly
- <xref linkend="ports-tarball" remap="tarballs"> for you. Here is
+ <link linkend="ports-tarball">tarballs</link> for you. Here is
how it works, with the gnats program in the databases directory as
an example (the bits in square brackets are comments. Do not type
them in if you are trying this yourself!):-</para>
@@ -347,14 +296,12 @@ password. Remember to use binary (also known as image) mode!]
<para>What happened here? We connected to the FTP server in the
usual way and went to its <filename>databases</filename> sub-directory. When we gave it
- the command <command>get gnats.tar</command>, the FTP server <xref
- linkend="ports-tarball"
- remap="tarred"> up the gnats directory for us.</para>
+ the command <command>get gnats.tar</command>, the FTP server <link
+ linkend="ports-tarball">tarred</link> up the gnats directory for us.</para>
<para>We then extracted the gnats skeleton and went into the gnats
- directory to build the port. As we explained <xref
- linkend="ports-fetch"
- remap="earlier">, the make process noticed we did not have a
+ directory to build the port. As we explained <link
+ linkend="ports-fetch">earlier</link>, the make process noticed we did not have a
copy of the source locally, so it fetched one before extracting,
patching and building it.</para>
@@ -436,16 +383,17 @@ do-install:
the benefit of human readers (as in most Unix script
files).</para>
- <para><literal>DISTNAME</literal> specifies the name of the <xref
- linkend="ports-tarball" remap="tarball">, but without the
+ <para><literal>DISTNAME</literal> specifies the name of the <link
+ linkend="ports-tarball">tarball</link>, but without the
extension.</para>
<para><literal>CATEGORIES</literal> states what kind of program this is. In
- this case, a utility for developers.</para>
+ this case, a utility for developers. See the <link
+ linkend="porting-categories">categories</link> section of this
+ handbook for a complete list.</para>
<para><literal>MASTER_SITES</literal> is the URL(s) of the master FTP site,
- which is used to retrieve the <xref linkend="ports-tarball"
- remap="tarball"> if it is not available on the local system.
+ which is used to retrieve the <link linkend="ports-tarball">tarball</link> if it is not available on the local system.
This is a site which is regarded as reputable, and is normally the
one from which the program is officially distributed (in so far
as any software is "officially" distributed on the
@@ -477,8 +425,7 @@ do-install:
<sect2>
<title>The <filename>files</filename> directory</title>
- <para>The file containing the <xref linkend="ports-checksum"
- remap="checksum"> for the port is called
+ <para>The file containing the <link linkend="ports-checksum">checksum</link> for the port is called
<filename>md5</filename>, after the MD5 algorithm used for ports
checksums. It lives in a directory with the slightly confusing
name of <filename>files</filename>.</para>
@@ -491,8 +438,7 @@ do-install:
<sect2>
<title>The <filename>patches</filename> directory</title>
- <para>This directory contains the <xref linkend="ports-patch"
- remap="patches"> needed to make everything work properly under
+ <para>This directory contains the <link linkend="ports-patch">patches</link> needed to make everything work properly under
FreeBSD.</para>
</sect2>
@@ -536,7 +482,7 @@ do-install:
<listitem>
<para>Fix it yourself. Technical details on how ports work can
be found in
- <xref linkend="porting" remap="Porting applications."></para>
+ <link linkend="porting">Porting applications.</link></para>
</listitem>
<listitem>
@@ -568,15 +514,6 @@ do-install:
</sect1>
- <sect1>
- <title>I Want to Make a Port!</title>
-
- <para>Great! Please see the <xref linkend="porting"
- remap="guidelines"> for detailed instructions on how to do
- this.</para>
-
- </sect1>
-
<sect1>
<title>Some Questions and Answers</title>
@@ -707,8 +644,7 @@ do-install:
</listitem>
<listitem>
- <para>Q. I did what you said for <xref linkend="ports-cd"
- remap="compiling ports from a CDROM"> and it worked great
+ <para>Q. I did what you said for <link linkend="ports-cd">compiling ports from a CDROM</link> and it worked great
until I tried to install the kermit port:-</para>
<informalexample>
@@ -884,7 +820,16 @@ do-install:
<para>Q. There are so many ports it is hard to find the one I
want. Is there a list anywhere of what ports are available?</para>
- <para>A. Look in the <filename>INDEX</filename> file in <filename>/usr/ports</filename>.</para>
+ <para>A. Look in the <filename>INDEX</filename> file in
+ <filename>/usr/ports</filename>. If you would like to search the
+ ports collection for a keyword, you can do that too. For example,
+ you can find ports relevant to the LISP programming language
+ using:</para>
+
+ <informalexample>
+ <screen>&prompt.user; <userinput>cd /usr/ports</userinput>
+&prompt.user; <userinput>make search key=lisp</userinput></screen>
+ </informalexample>
</listitem>
<listitem>
@@ -1044,6 +989,3524 @@ grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arc
</sect1>
+
+ <sect1 id="porting">
+ <title>Making a port yourself</title>
+
+ <para><emphasis>Contributed by &a.jkh;, &a.gpalmer;, &a.asami;
+ &a.obrien; and &a.hoek;. 28 August 1996.</emphasis></para>
+
+ <para>So, now you are interested in making your own port?
+ Great!</para>
+
+ <para>What follows are some guidelines for creating a new port for
+ FreeBSD. The bulk of the work is done by
+ <filename>/usr/share/mk/bsd.port.mk</filename>, which all port
+ Makefiles include. Please refer to that file for more details on
+ the inner workings of the ports collection. Even if you don't
+ hack Makefiles daily, it is well commented, and you will still
+ gain much knowledge from it.</para>
+
+ <note>
+ <para>Only a fraction of the overridable variables
+ (<makevar><replaceable>VAR</replaceable></makevar>) are mentioned
+ in this document. Most (if not all) are documented at the start of
+ <filename>bsd.port.mk</filename>. This file users a non-standard
+ tab setting. <application>Emacs</application> and
+ <application>Vim</application> should recognise the setting on
+ loading the file. <command>vi</command> or <command>ex</command>
+ can be set to use the correct value by typing <command>:set
+ tabstop=4</command> once the file has been loaded.</para>
+ </note>
+
+ <sect2>
+ <title>Quick Porting</title>
+
+ <para>This section tells you how to do a quick port. In many
+ cases, it is not enough, but we will see.</para>
+
+ <para>First, get the original tarball and put it into <makevar>DISTDIR</makevar>, which defaults to
+ <filename>/usr/ports/distfiles</filename>.</para>
+
+ <note>
+ <para>The following assumes that the software compiled
+ out-of-the-box, i.e., there was absolutely no change required
+ for the port to work on your FreeBSD box. If you needed to
+ change something, you will have to refer to the next section
+ too.</para>
+ </note>
+
+ <sect3>
+ <title>Writing the <filename>Makefile</filename></title>
+
+ <para>The minimal <filename>Makefile</filename> would
+ look something like this:</para>
+
+ <programlisting>
+# New ports collection makefile for: oneko
+# Version required: 1.1b
+# Date created: 5 December 1994
+# Whom: asami
+#
+# $Id$
+#
+
+DISTNAME= oneko-1.1b
+CATEGORIES= games
+MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
+
+MAINTAINER= asami@FreeBSD.ORG
+
+MAN1= oneko.1
+MANCOMPRESSED= yes
+USE_IMAKE= yes
+
+.include <bsd.port.mk></programlisting>
+
+ <para>See if you can figure it out. Do not worry about the
+ contents of the <literal>$Id$</literal>
+ line, it will be filled in automatically by CVS when the port
+ is imported to our main ports tree. You can find a more
+ detailed example in the <link
+ linkend="porting-samplem">sample Makefile</link>
+ section.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Writing the description files</title>
+
+ <para>There are three description files that are
+ required for any port, whether they actually package or not.
+ They are <filename>COMMENT</filename>,
+ <filename>DESCR</filename>, and <filename>PLIST</filename>,
+ and reside in the <filename>pkg</filename>
+ subdirectory.</para>
+
+
+ <sect4>
+ <title><filename>COMMENT</filename></title>
+
+ <para>This is the one-line description of the port.
+ <emphasis>Please</emphasis> do not include the package name (or version
+ number of the software) in the comment. Here is
+ an example:</para>
+
+ <programlisting>
+A cat chasing a mouse all over the screen.</programlisting>
+
+ </sect4>
+
+ <sect4>
+ <title><filename>DESCR</filename></title>
+
+ <para>This is a longer description of the port. One to a few
+ paragraphs concisely explaining what the port does is
+ sufficient.</para>
+
+ <note>
+ <para>This is <emphasis>not</emphasis> a manual or an
+ in-depth description on how to use or compile the port!
+ <emphasis>Please be careful if you are copying from the
+ <filename>README</filename> or manpage</emphasis>; too often
+ they are not a concise description of the port or are in an
+ awkward format (e.g., manpages have justified spacing). If the
+ ported software has an official WWW homepage, you should list
+ it here.</para>
+ </note>
+
+ <para>It is recommended that you sign the name at the end of
+ this file, as in:</para>
+
+ <programlisting>
+This is a port of oneko, in which a cat chases a poor mouse all over
+the screen.
+ :
+(etc.)
+
+http://www.oneko.org/
+
+- Satoshi
+asami@cs.berkeley.edu</programlisting>
+
+ </sect4>
+
+ <sect4>
+ <title><filename>PLIST</filename></title>
+
+ <para>This file lists all the files installed by the port. It
+ is also called the “packing list” because the package is
+ generated by packing the files listed here. The pathnames
+ are relative to the installation prefix (usually
+ <filename>/usr/local</filename> or
+ <filename>/usr/X11R6</filename>). If you are using the
+ <makevar>MAN<replaceable>n</replaceable></makevar> variables (as
+ you should be), do not list any manpages here.</para>
+
+ <para>Here is a small example:</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>Refer to the <citerefentry><refentrytitle>pkg_create</refentrytitle><manvolnum>1</manvolnum></citerefentry> man page
+ for details on the packing list.</para>
+
+ <note>
+ <para>You should list all the files, but not the name
+ directories, in the list. Also, if the port creates
+ directories for itself during installtion, make sure to add
+ <literal>@dirrm</literal> lines as necessary to remove them
+ when the port is deleted.</para>
+
+ <para>It is recommended that you keep all the filenames in
+ this file sorted alphabetically. It will make verifying the
+ changes when you upgrade the port much easier.</para>
+ </note>
+ </sect4>
+ </sect3>
+
+ <sect3>
+ <title>Creating the checksum file</title>
+
+ <para>Just type <command>make makesum</command>.
+ The ports make rules will automatically generate the file
+ <filename>files/md5</filename>.</para>
+
+ </sect3>
+
+ <sect3 id="porting-testing">
+ <title>Testing the port</title>
+
+ <para>You should make sure that the port rules do exactly what
+ you want it to do, including packaging up the port. These are
+ the important points you need to verify.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename>PLIST</filename> does not contain anything not
+ installed by your port</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>PLIST</filename> contains everything that is
+ installed by your port</para>
+ </listitem>
+
+ <listitem>
+ <para>Your port can be installed multiple times using the
+ <maketarget>reinstall</maketarget> target</para>
+ </listitem>
+
+ <listitem>
+ <para>Your port <link linkend="porting-cleaning">cleans
+ up</link> after itself upon deinstall</para>
+ </listitem>
+ </itemizedlist>
+
+ <procedure>
+ <title>Recommended test ordering</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 `make package-name`</command></para>
+ </step>
+
+ <step>
+ <para><command>make deinstall</command></para>
+ </step>
+
+ <step>
+ <para><command>make reinstall</command></para>
+ </step>
+
+ <step>
+ <para><command>make package</command></para>
+ </step>
+ </procedure>
+
+ <para>Make sure that there aren't any warnings issued in any of
+ the <maketarget>package</maketarget> and
+ <maketarget>deinstall</maketarget> stages, After step 3, check
+ to see if all the new directories are correctly deleted. Also,
+ try using the software after step 4, to ensure that is works
+ correctly when installed from a package.</para>
+ </sect3>
+
+ <sect3 id="porting-portlint">
+ <title>Checking your port with <command>portlint</command></title>
+
+ <para>Please use <command>portlint</command> to see if your port
+ conforms to our guidelines. The <command>portlint</command>
+ program is part of the ports collection. In particular, your may
+ want to check if the <link
+ linkend="porting-samplem">Makefile</link> is in the right
+ shape and the <link linkend="porting-pkgname">package</link> is
+ named appropriately.</para>
+ </sect3>
+
+ <sect3 id="porting-submitting">
+ <title>Submitting the port</title>
+
+ <para>First, make sure you have read the <link
+ linkend="porting-dads">Do's and Dont's</link> section.</para>
+
+ <para>Now that you are happy with your port, the only thing
+ remaining is to put it in the main FreeBSD ports tree and make
+ everybody else happy about it too. We do not need your
+ <filename>work</filename> directory or the
+ <filename>pkgname.tgz</filename> package, so delete them
+ now. Next, simply include the output of <command>shar `find
+ port_dir`</command> in a bug report and send it with the
+ <citerefentry>
+ <refentrytitle>send-pr</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry> program (see <link linkend="contrib-general">Bug
+ Reports and General Commentary</link> for more information
+ about <citerefentry>
+ <refentrytitle>send-pr</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>. If the uncompressed port is larger than
+ 20KB, you should compress it into a tarfile and use <citerefentry>
+ <refentrytitle>uuencode</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry> before including it in the bug report (uuencoded
+ tarfiles are acceptable even if the bug report is smaller than
+ 20KB but are not preferred). Be sure to classify the bug report as
+ category <literal>ports</literal> and class
+ <literal>change-request</literal>. (Do not mark the report
+ <literal>confidential</literal>!)</para>
+
+ <para>One more time, <emphasis>do not include the original source
+ distfile, the <filename>work</filename> directory, or the
+ package you built with <command>make
+ package</command></emphasis>.</para>
+
+ <note>
+ <para>In the past, we asked you to upload new port submissions
+ in our ftp site (<hostid
+ role="fqdn">ftp.freebsd.org</hostid>). This is no longer
+ recommended as read access is turned off on that
+ <filename>incoming/</filename> directory of that site due to
+ the large amount of pirated software showing up there.</para>
+ </note>
+
+ <para>We will look at your port,
+ get back to you if necessary, and put it in the
+ tree. Your name will also appear in the list of “Additional
+ FreeBSD contributors” on the FreeBSD Handbook and other files.
+ Isn't that great?!? <!-- smiley -->:)</para>
+
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Slow Porting</title>
+
+ <para>Ok, so it was not that simple, and the port required some
+ modifications to get it to work. In this section, we will
+ explain, step by step, how to modify it to get it to work with
+ the ports paradigm.</para>
+
+
+ <sect3>
+ <title>How things work</title>
+
+ <para>First, this is the sequence of events which occurs when
+ the user first types <command>make</command> in
+ your port's directory, and you may find that having
+ <filename>bsd.port.mk</filename> in another window while you
+ read this really helps to understand it.</para>
+
+ <para>But do not worry if you do not really understand what
+ <filename>bsd.port.mk</filename> is doing, not many people
+ do... <!-- smiley --><emphasis>:></emphasis></para>
+
+
+ <procedure>
+
+ <step>
+ <para>The <maketarget>fetch</maketarget> target is run. The <maketarget>fetch</maketarget> target is
+ responsible for making sure that the tarball exists
+ locally in <makevar>DISTDIR</makevar>.
+ If <maketarget>fetch</maketarget> cannot find the required files in <makevar>DISTDIR</makevar> it will look up the
+ URL <makevar>MASTER_SITES</makevar>,
+ which is set in the Makefile, as well as our main ftp
+ site at <ulink
+ URL="ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/">ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/,</ulink> where we put sanctioned distfiles as backup. It will then attempt to fetch the named distribution file with <makevar>FETCH</makevar>, assuming that the requesting site has direct access to the Internet. If that succeeds, it will save the file in <makevar>DISTDIR</makevar> for future use and proceed.</para>
+ </step>
+
+ <step>
+ <para>The <maketarget>extract</maketarget> target is run. It looks for your port's
+ distribution file (typically a gzip'd tarball) in <makevar>DISTDIR</makevar> and unpacks it into a temporary subdirectory
+ specified by <makevar>WRKDIR</makevar>
+ (defaults to <filename>work</filename>).</para>
+ </step>
+
+ <step>
+ <para>The <maketarget>patch</maketarget> target is run. First, any patches defined
+ in <makevar>PATCHFILES</makevar> are
+ applied. Second, if any patches are found in <makevar>PATCHDIR</makevar> (defaults to the
+ <filename>patches</filename> subdirectory), they are
+ applied at this time in alphabetical order.</para>
+ </step>
+
+ <step>
+ <para>The <maketarget>configure</maketarget> target is run. This can do any one of
+ many different things.</para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>If it exists,
+ <filename>scripts/configure</filename> is run.</para>
+ </listitem>
+
+ <listitem>
+ <para>If <makevar>HAS_CONFIGURE</makevar> or
+ <makevar>GNU_CONFIGURE</makevar>
+ is set,
+ <filename><makevar>WRKSRC</makevar>/configure</filename> is
+ run.</para>
+ </listitem>
+
+ <listitem>
+ <para>If <makevar>USE_IMAKE</makevar> is set,
+ <makevar>XMKMF</makevar>
+ (default: <command>xmkmf
+ -a</command>) is run.</para>
+ </listitem>
+
+ </orderedlist>
+
+ </step>
+
+ <step>
+ <para>The <maketarget>build</maketarget> target is run. This is responsible for
+ descending into the ports' private working directory
+ (<makevar>WRKSRC</makevar>) and
+ building it. If <makevar>USE_GMAKE</makevar> is set, GNU
+ <command>make</command> will be used,
+ otherwise the system <command>make</command>
+ will be used.</para>
+ </step>
+
+ </procedure>
+
+
+ <para>The above are the default actions. In addition, you can
+ define targets <maketarget>pre-<replaceable>something</replaceable></maketarget> or <maketarget>post-<replaceable>something</replaceable></maketarget>, or put scripts
+ with those names, in the <filename>scripts</filename>
+ subdirectory, and they will be run before or after the default
+ actions are done.</para>
+
+ <para>For example, if you have a <maketarget>post-extract</maketarget> target defined in your
+ Makefile, and a file <filename>pre-build</filename> in the
+ <filename>scripts</filename> subdirectory, the
+ <maketarget>post-extract</maketarget> target will be
+ called after the regular extraction actions, and the
+ <filename>pre-build</filename> script will be executed before
+ the default build rules are done. It is recommended that you
+ use <filename>Makefile</filename> targets if the actions are
+ simple enough, because it will be easier for someone to figure
+ out what kind of non-default action the port requires.</para>
+
+ <para>The default actions are done by the
+ <filename>bsd.port.mk</filename> targets <maketarget>do-<replaceable>something</replaceable></maketarget>. For example, the
+ commands to extract a port are in the target <maketarget>do-extract</maketarget>. If you are not happy with
+ the default target, you can fix it by redefining the
+ <maketarget>do-<replaceable>something</replaceable></maketarget> target in
+ your <filename>Makefile</filename>.</para>
+
+ <note>
+ <para>The “main” targets (e.g., <maketarget>extract</maketarget>, <maketarget>configure</maketarget>, etc.) do nothing more than
+ make sure all the stages up to that one is completed and
+ call the real targets or scripts, and they are not intended
+ to be changed. If you want to fix the extraction, fix
+ <maketarget>do-extract</maketarget>, but never ever
+ touch <maketarget>extract</maketarget>!</para>
+ </note>
+
+ <para>Now that you understand what goes on when the user types
+ <command>make</command>, let us go through the
+ recommended steps to create the perfect port.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Getting the original sources</title>
+
+ <para>Get the original sources (normally) as a compressed
+ tarball (<filename><replaceable>foo</replaceable>.tar.gz</filename> or
+ <filename><replaceable>foo</replaceable>.tar.Z</filename>) and copy it into
+ <makevar>DISTDIR</makevar>. Always use
+ <emphasis>mainstream</emphasis> sources when and where you
+ can.</para>
+
+ <para>If you cannot find a ftp/http site that is well-connected
+ to the net, or can only find sites that have irritatingly
+ non-standard formats, you might want to put a copy on a
+ reliable ftp or http server that you control (e.g., your home
+ page). Make sure you set <makevar>MASTER_SITES</makevar> to
+ reflect your choice.</para>
+
+ <para>If you
+ cannot find somewhere convenient and reliable to put the distfile
+ (if you are a FreeBSD committer, you can just put it in your
+ <filename>public_html/</filename> directory on
+ <hostid>freefall</hostid>),
+ we can “house” it ourselves by putting
+ it on <filename>ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/LOCAL_PORTS/</filename> as the last resort. Please refer to this
+ location as <makevar>MASTER_SITE_LOCAL</makevar>. Send mail to
+ the &a.ports;if you are not sure what to do.</para>
+
+ <para>If your port's distfile changes all the time for no good
+ reason, consider putting the distfile in your home page and
+ listing it as the first <makevar>MASTER_SITES</makevar>. This
+ will prevent users from getting <errorname>checksum
+ mismatch</errorname> errors, and also reduce the workload of
+ maintainers of our ftp site. Also, if there isonly one master
+ site for the port, it is recommended that you house a backup at
+ your site and list it as the second
+ <makevar>MASTER_SITES</makevar>.</para>
+
+ <para>If your port requires some additional `patches' that are
+ available on the Internet, fetch them too and put them in
+ <makevar>DISTDIR</makevar>. Do not worry if
+ they come from site other than where you got the main source
+ tarball, we have a way to handle these situations (see the
+ description of <link
+ linkend="porting-patchfiles">PATCHFILES</link> below).</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Modifying the port</title>
+
+ <para>Unpack a copy of the tarball in a private directory and
+ make whatever changes are necessary to get the port to compile
+ properly under the current version of FreeBSD. Keep
+ <emphasis>careful track</emphasis> of everything you do, as
+ you will be automating the process shortly. Everything,
+ including the deletion, addition or modification of files
+ should be doable using an automated script or patch file when
+ your port is finished.</para>
+
+ <para>If your port requires significant user
+ interaction/customization to compile or install, you should
+ take a look at one of Larry Wall's classic <application>Configure</application> scripts
+ and perhaps do something similar yourself. The goal of the
+ new ports collection is to make each port as “plug-and-play”
+ as possible for the end-user while using a minimum of disk
+ space.</para>
+
+ <note>
+ <para>Unless explicitly stated, patch files, scripts, and
+ other files you have created and contributed to the FreeBSD
+ ports collection are assumed to be covered by the standard
+ BSD copyright conditions.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>Patching</title>
+
+ <para>In the preparation of the port, files that have been added
+ or changed can be picked up with a recursive diff for later
+ feeding to patch. Each set of patches you wish to apply
+ should be collected into a file named
+ <filename>patch-<replaceable>xx</replaceable></filename> where
+ <replaceable>xx</replaceable> denotes the sequence in which
+ the patches will be applied — these are done in
+ <emphasis>alphabetical order</emphasis>, thus
+ <literal>aa</literal> first, <literal>ab</literal> second and so on. These files
+ should be stored in <makevar>PATCHDIR</makevar>, from where they will be
+ automatically applied. All patches should be relative to
+ <makevar>WRKSRC</makevar> (generally the
+ directory your port's tarball unpacks itself into, that being
+ where the build is done). To make fixes and upgrades easier,
+ you should avoid having more than one patch fix the same file
+ (e.g., <filename>patch-aa</filename> and <filename>patch-ab</filename> both changing <filename><makevar>WRKSRC</makevar>/foobar.c</filename>).</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Configuring</title>
+
+ <para>Include any additional customization commands to your
+ <filename>configure</filename> script and save it in the
+ <filename>scripts</filename> subdirectory. As mentioned
+ above, you can also do this as <filename>Makefile</filename>
+ targets and/or scripts with the name
+ <filename>pre-configure</filename> or
+ <filename>post-configure</filename>.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Handling user input</title>
+
+ <para>If your port requires user input to build, configure or
+ install, then set <makevar>IS_INTERACTIVE</makevar> in your
+ Makefile. This will allow “overnight builds” to skip your port
+ if the user sets the variable <envar>BATCH</envar> in his
+ environment (and if the user sets the variable
+ <envar>INTERACTIVE</envar>, then <emphasis>only</emphasis>
+ those ports requiring interaction are built).</para>
+
+ <para>It is also recommended that if there are reasonable default
+ answers to the questions, you check the
+ <makevar>PACKAGE_BUILDING</makevar> variable and turn off the
+ interactive script when it is set. This will allow us to build
+ the packages for CD-ROMs and ftp.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Configuring the Makefile</title>
+
+ <para>Configuring the Makefile is pretty simple, and again we
+ suggest that you look at existing examples before starting.
+ Also, there is a <link linkend="porting-samplem">sample
+ Makefile</link> in this handbook, so take a look and please follow
+ the ordering of variables and sections in that template to make
+ your port easier for others to read.</para>
+
+ <para>Now, consider the following problems in sequence as you
+ design your new Makefile:</para>
+
+
+ <sect3>
+ <title>The original source</title>
+
+ <para>Does it live in <makevar>DISTDIR</makevar> as a standard gzip'd
+ tarball? If so, you can go on to the next step. If not, you
+ should look at overriding any of the <makevar>EXTRACT_CMD</makevar>, <makevar>EXTRACT_BEFORE_ARGS</makevar>, <makevar>EXTRACT_AFTER_ARGS</makevar>, <makevar>EXTRACT_SUFX</makevar>, or <makevar>DISTFILES</makevar> variables, depending on
+ how alien a format your port's distribution file is. (The
+ most common case is <literal>EXTRACT_SUFX=.tar.Z</literal>,
+ when the tarball is condensed by regular compress, not
+ gzip.)</para>
+
+ <para>In the worst case, you can simply create your own
+ <maketarget>do-extract</maketarget> target to override
+ the default, though this should be rarely, if ever,
+ necessary.</para>
+
+ </sect3>
+
+ <sect3>
+ <title><makevar>DISTNAME</makevar></title>
+
+ <para>You should set <makevar>DISTNAME</makevar> to be the base name of
+ your port. The default rules expect the distribution file
+ list (<makevar>DISTFILES</makevar>) to be
+ named <makevar>DISTNAME</makevar><makevar>EXTRACT_SUFX</makevar> which, if it is a normal tarball, is going to be
+ something like <literal>foozolix-1.0.tar.gz</literal> for a setting of <literal>DISTNAME=foozolix-1.0</literal>.</para>
+
+ <para>The default rules also expect the tarball(s) to extract
+ into a subdirectory called
+ <filename>work/<makevar>DISTNAME</makevar></filename>, e.g. <filename>work/foozolix-1.0/</filename>.</para>
+
+ <para>All this behavior can be overridden, of course; it simply
+ represents the most common time-saving defaults. For a port
+ requiring multiple distribution files, simply set <makevar>DISTFILES</makevar> explicitly. If only a
+ subset of <makevar>DISTFILES</makevar> are
+ actual extractable archives, then set them up in <makevar>EXTRACT_ONLY</makevar>, which will override
+ the <makevar>DISTFILES</makevar> list when
+ it comes to extraction, and the rest will be just left in
+ <makevar>DISTDIR</makevar> for later
+ use.</para>
+
+ </sect3>
+
+ <sect3>
+ <title><makevar>PKGNAME</makevar></title>
+
+ <para>If <makevar>DISTNAME</makevar> does not conform to our <link
+ linkend="porting-pkgname">guidelines for a good package
+ name</link>, you should set the <makevar>PKGNAME</makevar>
+ variable to something better. See the abovementioned guidelines
+ for more details.</para>
+ </sect3>
+
+ <sect3>
+ <title><makevar>CATEGORIES</makevar></title>
+
+ <para>When a package is created, it is put under
+ <filename>/usr/ports/packages/All</filename> and links are
+ made from one or more subdirectories of
+ <filename>/usr/ports/packages</filename>. The names of these
+ subdirectories are specified by the variable <makevar>CATEGORIES</makevar>. It is intended to
+ make life easier for the user when he is wading through the
+ pile of packages on the ftp site or the CD-ROM. Please take a
+ look at the existing <link
+ linkend="porting-categories">categories</link> and pick the
+ ones that are suitable for your port.</para>
+
+ <para>This list also determines where in the ports tree the port
+ is imported. If you put more than one category here, it is
+ assumed that the port files will be put in the subdirectory with
+ the name in the first category. See the <link
+ linkend="porting-categories">categories</link> section for
+ more discussion about how to pick the right categories.</para>
+
+ <para>If you port truly belongs to something that is different
+ from all the existing ones, you can even create a new category
+ name. In that case, please send mail to the &a.ports; to propose
+ a new category.</para>
+
+ <note>
+ <para>There is no error checking for category
+ names. <command>make package</command> will happily create a
+ new directory if you mustype the category name, so be
+ careful!</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><makevar>MASTER_SITES</makevar></title>
+
+ <para>Record the directory part of the ftp/http-URL pointing at
+ the original tarball in <makevar>MASTER_SITES</makevar>. Do not forget the
+ trailing slash (<filename>/</filename>)!</para>
+
+ <para>The <command>make</command> macros will try to use this specification for
+ grabbing the distribution file with <makevar>FETCH</makevar> if they cannot find it
+ already on the system.</para>
+
+ <para>It is recommended that you put multiple sites on this
+ list, preferably from different continents. This will
+ safeguard against wide-area network problems, and we are even
+ planning to add support for automatically determining the
+ closest master site and fetching from there!</para>
+
+ <para>If the original tarball is part of one of the following
+ popular archives: X-contrib, GNU, Perl CPAN, TeX CTAN, or
+ Linux Sunsite, you refer to those sites in an easy compact
+ form using <makevar>MASTER_SITE_XCONTRIB</makevar>, <makevar>MASTER_SITE_GNU</makevar>,
+ <makevar>MASTER_SITE_PERL_CPAN</makevar>, <makevar>MASTER_SITE_TEX_CTAN</makevar>, and
+ <makevar>MASTER_SITE_SUNSITE</makevar>. Simply set <makevar>MASTER_SITE_SUBDIR</makevar> to the
+ path with in the archive. Here is an example:</para>
+
+ <programlisting>
+MASTER_SITES= ${MASTER_SITE_XCONTRIB}
+MASTER_SITE_SUBDIR= applications</programlisting>
+
+ <para>The user can also set the <makevar>MASTER_SITE_*</makevar> variables in
+ <filename>/etc/make.conf</filename> to override our choices,
+ and use their favorite mirrors of these popular archives
+ instead.</para>
+
+ </sect3>
+
+ <sect3 id="porting-patchfiles">
+ <title><makevar>PATCHFILES</makevar></title>
+
+ <para>If your port requires some additional patches that are
+ available by ftp or http, set <makevar>PATCHFILES</makevar> to the names of the
+ files and <makevar>PATCH_SITES</makevar> to
+ the URL of the directory that contains them (the format is the
+ same as <makevar>MASTER_SITES</makevar>).</para>
+
+ <para>If the patch is not relative to the top of the source tree
+ (i.e., <makevar>WKRSRC</makevar>) because it
+ contains some extra pathnames, set <makevar>PATCH_DIST_STRIP</makevar> accordingly.
+ For instance, if all the pathnames in the patch has an extra
+ <literal>foozolix-1.0/</literal> in front of the
+ filenames, then set
+ <literal>PATCH_DIST_STRIP=-p1</literal>.</para>
+
+ <para>Do not worry if the patches are compressed, they will be
+ decompressed automatically if the filenames end with
+ <filename>.gz</filename> or
+ <filename>.Z</filename>.</para>
+
+ <para>If the patch is distributed with some other files, such as
+ documentation, in a gzip'd tarball, you can't just use
+ <makevar>PATCHFILES</makevar>. If that is
+ the case, add the name and the location of the patch tarball
+ to <makevar>DISTFILES</makevar> and
+ <makevar>MASTER_SITES</makevar>. Then, from
+ the <maketarget>pre-patch</maketarget> target, apply the
+ patch either by running the patch command from there, or
+ copying the patch file into the <makevar>PATCHDIR</makevar> directory and calling it
+ <filename>patch-<replaceable>xx</replaceable></filename>.</para>
+
+ <note>
+ <para>Note the tarball will have been extracted alongside the
+ regular source by then, so there is no need to explicitly
+ extract it if it is a regular gzip'd or compress'd tarball.
+ If you do the latter, take extra care not to overwrite
+ something that already exists in that directory. Also do
+ not forget to add a command to remove the copied patch in
+ the <maketarget>pre-clean</maketarget> target.</para>
+ </note>
+
+ </sect3>
+
+ <sect3>
+ <title><makevar>MAINTAINER</makevar></title>
+
+ <para>Set your mail-address here. Please. <!-- smiley --><emphasis>:)</emphasis></para>
+
+ <para>For detailed description of the responsibility of
+ maintainers, refer to <link
+ linkend="policies-maintainer">MAINTAINER
+ on Makefiles</link> section.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Dependencies</title>
+
+ <para>Many ports depend on other ports. There are five
+ variables that you can use to ensure that all the required
+ bits will be on the user's machine. There are also some
+ pre-supported dependency variables for common cases, plus a few
+ more to control the behaviour of dependencies.</para>
+
+
+ <sect4>
+ <title><makevar>LIB_DEPENDS</makevar></title>
+
+ <para>This variable specifies the shared libraries this port
+ depends on. It is a list of <replaceable>lib</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples where
+ <replaceable>lib</replaceable> is the name of the shared library,
+ and <replaceable>dir</replaceable> is the directory in which to
+ find it in case it is not available, and
+ <replaceable>target</replaceable> is the target to call in
+ that directory. For example,
+
+ <programlisting>
+LIB_DEPENDS= jpeg\\.9\\.:${PORTSDIR}/graphics/jpeg:install</programlisting>
+
+ will check for a shared jpeg library with
+ major version 9, and descend into the
+ <filename>graphics/jpeg</filename> subdirectory of your
+ ports tree to build and install it if it is not
+ found. The <replaceable>target</replaceable> part can be
+ omitted if it is equal to <makevar>DEPENDS_TARGET</makevar>
+ (which defaults to <literal>install</literal>).</para>
+
+ <note>
+ <para>The <replaceable>lib</replaceable> part is an argument
+ given to <command>ldconfig -r | grep -wF</command>. There
+ shall be no reqular expressions in this variable.</para>
+ </note>
+
+ <para>The dependency is checked twice, once from within the
+ <maketarget>extract</maketarget> target and then from within
+ the <maketarget>install</maketarget> target. Also, the name of the
+ dependency is put in to the package so that
+ <command>pkg_add</command> will automatically install it if it
+ is not on the user's system.</para>
+
+ </sect4>
+
+ <sect4>
+ <title><makevar>RUN_DEPENDS</makevar></title>
+
+ <para>This variable specifies executables or files this port
+ depends on during run-time. It is a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples where
+ <replaceable>path</replaceable> is the name of the executable or
+ file, and <replaceable>dir</replaceable> is the directory in which
+ to find it in case it is not available, and
+ <replaceable>target</replaceable> is the target to call in
+ that directory. If
+ <replaceable>path</replaceable> starts with a slash
+ (<literal>/</literal>), it is treated as a file and its
+ existence is tested with <command>test -e</command>;
+ otherwise, it is assumed to be an executable, and
+ <command>which -s</command> is used to determine if the
+ program exists in the user's search path.</para>
+
+ <para>For example,
+
+ <programlisting>
+RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \
+ wish8.0:${PORTSDIR}/x11-toolkits/tk80</programlisting>
+
+ will check if the file or directory
+ <filename>/usr/local/etc/innd</filename> exists, and build
+ and install it from the <filename>news/inn</filename>
+ subdirectory of the ports tree if it is not found. It will
+ also see if an executable called <command>wish8.0</command> is in your search path, and
+ descend into the <filename>x11-toolkits/tk80</filename> subdirectory of
+ your ports tree to build and install it if it is not
+ found.</para>
+
+ <note>
+ <para>In this case, <command>innd</command> is actually an
+ executable; if an executable is in a place that is not
+ expected to be in a normal user's search path, you should
+ use the full pathname.</para>
+ </note>
+
+ <para>The dependency is checked from within the <maketarget>install</maketarget> target. Also, the name of the
+ dependency is put in to the package so that
+ <command>pkg_add</command> will automatically install it if it
+ is not on the user's system. The
+ <replaceable>target</replaceable> part can be omitted if it is
+ the same <makevar>DEPENDS_TARGET</makevar>.</para>
+
+ </sect4>
+
+ <sect4>
+ <title><makevar>BUILD_DEPENDS</makevar></title>
+
+ <para>This variable specifies executables or files this port
+ requires to build. Like <makevar>RUN_DEPENDS</makevar>, it is
+ a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples.
+ For example,
+
+ <programlisting>
+BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>
+
+ will check for an executable called
+ <command>unzip</command>, and descend into the
+ <filename>archivers/unzip</filename> subdirectory of your
+ ports tree to build and install it if it is not
+ found.</para>
+
+ <note>
+ <para>“build” here means everything from extracting to
+ compilation. The dependency is checked from within the
+ <maketarget>extract</maketarget> target. The
+ <replaceable>target</replaceable> part can be omitted if it
+ is the same as <makevar>DEPENDS_TARGET</makevar></para>
+ </note>
+ </sect4>
+
+ <sect4>
+ <title><makevar>FETCH_DEPENDS</makevar></title>
+
+ <para>This variable specifies executables or files this port
+ requires to fetch. Like the previous two, it is a list of
+ <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples. For
+ example,
+
+ <programlisting>
+FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting>
+
+ will check for an executable called
+ <command>ncftp2</command>, and descend into the
+ <filename>net/ncftp2</filename> subdirectory of your ports
+ tree to build and install it if it is not found.</para>
+
+ <para>The dependency is checked from within the
+ <maketarget>fetch</maketarget> target. The
+ <replaceable>target</replaceable> part can be omitted if it is
+ the same as <makevar>DEPENDS_TARGET</makevar>.</para>
+
+ </sect4>
+
+ <sect4>
+ <title><makevar>DEPENDS</makevar></title>
+
+ <para>If there is a dependency that does not fall into either
+ of the above four categories, or your port requires to have
+ the source of the other port extracted in addition to having
+ them installed, then use this variable. This is a list of
+ <replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional>, as there is nothing to check, unlike the previous four. The <replaceable>target</replaceable> part can be omitted if it is the same as <makevar>DEPENDS_TARGET</makevar>.</para>
+ </sect4>
+
+ <sect4>
+ <title>Common dependency variables</title>
+
+ <para>Define <literal>USE_XLIB=yes</literal> if your port
+ requires the X Window System to be installed (it is implied by
+ <makevar>USE_IMAKE</makevar>). Define
+ <literal>USE_GMAKE=yes</literal> if your port requires GNU
+ <command>make</command> instead of BSD
+ <command>make</command>. Define
+ <literal>USE_AUTOCONF=yes</literal> if your port requires GNU
+ autoconf to be run. Define <literal>USE_QT=yes</literal> if
+ your port uses the latest qt toolkit. Use
+ <literal>USE_PERL5=yes</literal> if your port requires version
+ 5 of the perl language. (The last is especially important since
+ some versions of FreeBSD has perl5 as part of the base system
+ while others don't.)</para>
+ </sect4>
+
+ <sect4>
+ <title>Notes on dependencies</title>
+
+ <para>As mentioned above, the default target to call when a
+ dependency is required is
+ <maketarget>DEPENDS_TARGET</maketarget>. It defaults to
+ <literal>install</literal>. This is a user variable; is is
+ never defined in a port's <filename>Makefile</filename>. If
+ your port needs a special way to handle a dependency, use the
+ <literal>:target</literal> part of the
+ <makevar>*_DEPENDS</makevar> variables instead of redefining
+ <makevar>DEPENDS_TARGET</makevar>.</para>
+
+ <para>When you type <command>make clean</command>, its
+ dependencies are automatically cleaned too. If you do not wish
+ this to happen, define the variable
+ <makevar>NOCLEANDEPENDS</makevar> in your environment.</para>
+
+ <para>To depend on another port unconditionally, it is customary
+ to use the string <literal>nonexistent</literal> as the first
+ field of <makevar>BUILD_DEPENDS</makevar> or
+ <makevar>RUN_DEPENDS</makevar>. Use this only when you need to
+ the to get to the source of the other port. You can often save
+ compilation time by specifying the target too. For
+ instance
+
+ <programlisting>
+BUILD_DEPENDS= /nonexistent:${PORTSDIR}/graphics/jpeg:extract</programlisting>
+
+ will always descend to the JPEG port and extract it.</para>
+
+ <para>Do not use <makevar>DEPENDS</makevar> unless there is no
+ other way the behaviour you want can be accomplished. It will
+ cause the other port to be always build (and installed, by
+ default), and the dependency will go into the packages as
+ well. If this is really what you need, I recommend you to
+ write it as <literal>BUILD_DEPENDS</literal> and
+ <literal>RUN_DEPENDS</literal> instead—at least the
+ intention will be clear.</para>
+ </sect4>
+ </sect3>
+
+ <sect3>
+ <title>Building mechanisms</title>
+
+ <para>If your package uses GNU <command>make</command>, set
+ <literal>USE_GMAKE=yes</literal>. If your package uses
+ <command>configure</command>, set
+ <literal>HAS_CONFIGURE=yes</literal>. If your package uses GNU
+ <command>configure</command>, set
+ <literal>GNU_CONFIGURE=yes</literal> (this implies
+ <literal>HAS_CONFIGURE</literal>). If you want to give some
+ extra arguments to <command>configure</command> (the default
+ argument list <literal>--prefix=${PREFIX}</literal> for
+ GNU <command>configure</command> and empty for non-GNU
+ <command>configure</command>), set those extra arguments in
+ <makevar>CONFIGURE_ARGS</makevar>. If your package uses GNU
+ <command>autoconf</command>, set
+ <literal>USE_AUTOCONF=yes</literal>. This implies
+ <makevar>GNU_CONFIGURE</makevar>, and will cause
+ <command>autoconf</command> to be run before
+ <command>configure</command>.</para>
+
+ <para>If your package is an X application that creates
+ <filename>Makefile</filename>s from
+ <filename>Imakefile</filename>s using <command>imake</command>, then set
+ <literal>USE_IMAKE=yes</literal>. This will cause the
+ configure stage to automatically do an <command>xmkmf
+ -a</command>. If the <option>-a</option> flag is a
+ problem for your port, set
+ <literal>XMKMF=xmkmf</literal>.
+ If the port uses <command>imake</command> but does not understand the
+ <maketarget>install.man</maketarget> target,
+ <literal>NO_INSTALL_MANPAGES=yes</literal> should be set.
+ In addition, the author of the original port should be shot.
+ <!-- smiley --><emphasis>:></emphasis></para>
+
+ <para>If your port's source <filename>Makefile</filename> has
+ something else than <maketarget>all</maketarget> as the main
+ build target, set <makevar>ALL_TARGET</makevar>
+ accordingly. Same goes for <maketarget>install</maketarget> and
+ <makevar>INSTALL_TARGET</makevar>.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Special considerations</title>
+
+ <para>There are some more things you have to take into account when
+ you create a port. This section explains the most common of
+ those.</para>
+
+ <sect3>
+ <title><command>ldconfig</command></title>
+
+ <para>If your port installs a shared library, add a
+ <maketarget>post-install</maketarget> target to your
+ <filename>Makefile</filename> that runs
+ <literal>${LDCONFIG} -m</literal> on the directory where
+ the new library is installed (usually
+ <filename><makevar>PREFIX</makevar>/lib</filename>) to register
+ it into the shared library cache.</para>
+
+ <para>Also, add a matching <literal>@exec /sbin/ldconfig
+ -m</literal> and <literal>@unexec /sbin/ldconfig -R</literal>
+ pair to your <filename>pkg/PLIST</filename> file so that a user
+ who installed the package can start using teh shared libraru
+ immediately and deinstallation will not cause the system to
+ still believe the library is there. These lines should
+ immediately follow the line for the shared library itself, as
+ in:</para>
+
+ <programlisting>
+lib/libtvl80.so.1
+@exec /sbin/ldconfig -m %D/lib
+@unexec /sbin/ldconfig -R</programlisting>
+
+ <para>Never, ever, <emphasis>ever</emphasis> add a line that says
+ <literal>ldconfig</literal> without any arguments to your
+ <filename>Makefile</filename> or
+ <filename>pkg/PLIST</filename>. This will reset the shared
+ libraru cache to the contents of <filename>/usr/lib</filename>
+ only, and will royally screw up the user's machine ("Help, xinit
+ does not run anymore after I install this port!"). Anybody who
+ does this will be shot and cut in 65,536 pieces by a rusty knife
+ and have is liver chopped out by a bunch of crows and will
+ eternally rot to death in the deepest bowels of hell (not
+ necessarily in that order…)</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>ELF support</title>
+
+ <para>Since FreeBSD is moving to ELF from 3.0-release onwards,
+ 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 that there will
+ be one more release (2.2.8) from the 2.2 branch. 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 awhile for reference
+ in case you have come across some old port you wish to
+ upgrade.</para>
+
+ <sect3>
+ <title>Moving a.out libraries out of the way</title>
+
+ <para>A.out libraries should be moved out of
+ <filename>/usr/local/lib</filename> and similar to an
+ <filename>aout</filename> subdirectory. (If you don't move them
+ out of the way, ELF ports will happily overwrite a.out libraries.)
+ The <maketarget>move-aout-libs</maketarget> target in the -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>
+ </sect3>
+
+ <sect3>
+ <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>
+ </sect3>
+
+ <sect3>
+ <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's always going to be
+ <literal>aout</literal> in -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>
+ </sect3>
+
+ <sect3>
+ <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 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>PLIST</filename> too, and it won't 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>
+ </sect3>
+
+ <sect3>
+ <title><makevar>LIB_DEPENDS</makevar></title>
+
+ <para>All port Makefiles 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>
+ </sect3>
+
+ <sect3>
+ <title><filename>PLIST</filename></title>
+
+ <para><filename>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>PLIST</filename> mentioned in the previous
+ paragraph.</para>
+ </sect3>
+
+ <sect3>
+ <title><literal>ldconfig</literal></title>
+
+ <para>The <literal>ldconfig</literal> line in Makefiles should read:</para>
+
+ <programlisting>
+${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....</programlisting>
+
+ <para>In <filename>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>
+ </sect3>
+ </sect2>
+
+ <sect2 id="porting-masterdir">
+ <title><makevar>MASTERDIR</makevar></title>
+
+ <para>If your port needs to build slightly different versions of
+ packages by having a variable (for instance, resolution, or paper
+ size) take different values, create one subdirectory per package
+ to make it easier forusers to see what to do, but try to share as
+ many files as possible between ports. Typically you only need a
+ very short <filename>Makefile</filename> in all but one of the
+ directories if you use variables cleverly. In the sole
+ <filename>Makefiles</filename>, you can use
+ <makevar>MASTERDIR</makevar> to specify the directory where the
+ rest of the files are. Also, use a variable as part of
+ <link linkend="porting-pkgname"><makevar>PKGNAME</makevar></link>
+ so the packages will have different names.</para>
+
+ <para>This will be best demonstrated by an example. This is part of
+ <filename>japanese/xdvi300/Makefile</filename>;</para>
+
+ <programlisting>
+PKGNAME= ja-xdvi${RESOLUTION}-17
+ :
+# 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>japanese/xdvi300</filename> also has all the regular
+ patches, package files, etc. If you type <command>make</command>
+ there, it will take the default value for the resolution (300) and
+ build the port normally.</para>
+
+ <para>As for other resolutions, this is the
+ <emphasis>entire</emphasis>
+ <filename>xdvi118/Makefile</filename>;</para>
+
+ <programlisting>
+RESOLUTION= 118
+MASTERDIR= ${.CURDIR}/../xdvi300
+
+.include ${MASTERDIR}/Makefile</programlisting>
+
+ <para>(<filename>xdvi240/Makefile</filename> and
+ <filename>xdvi400/Makefile</filename> are similar). The
+ <makevar>MASTERDIR</makevar> definition tells
+ <filename>bsd.port.mk</filename> that the refulat set of
+ subdirectories like <makevar>PATCHDIR</makevar> and
+ <makevar>PKGDIR</makevar> are to be found under
+ <filename>xdvi300</filename>. The
+ <literal>RESOLUTION=118</literal> line will override the
+ <literal>RESOLUTION=300</literal> line in
+ <filename>xdvi300/Makefile</filename> and the port will be built
+ with resolution set to 118.</para>
+ </sect2>
+
+ <sect2>
+ <title>Shared library versions</title>
+
+ <para>First, please read our <link linkend="policies-shlib">policy
+ on shared library versioning</link> to understand
+ what to do with shared library versions in general. Do
+ not blindly assume software authors know what they are
+ doing; many of them do not. It is very important that
+ these details are carefully considered, as we have quite a
+ unique situation where we are trying to have dozens of
+ potentially incompatible software pairs co-exist.
+ Careless port imports have caused great trouble regarding
+ shared libraries in the past (ever wondered why the port
+ <filename>jpeg-6b</filename> has a shared library version of 9.0?).
+ If in doubt, send a message to the &a.ports;. Most of the
+ time, your job ends by determining the right shared
+ library version and making appropriate patches to
+ implement it.</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>
+ </sect2>
+
+ <sect2 id="porting-manpages">
+ <title>Manpages</title>
+
+ <para>The <makevar>MAN[1-9LN]</makevar> variables will automatically
+ add any manpages to <filename>pkg/PLIST</filename> (this means you
+ must <emphasis>not</emphasis> list manpages in the
+ <filename>PLIST</filename>—see <link
+ linkend="porting-plist">generating PLIST</link> for more). It
+ also makes the install stage automatically compress or uncompress
+ manpages depending on the setting of
+ <makevar>NOMANCOMPRESS</makevar> in
+ <filename>/etc/make.conf</filename>.</para>
+
+ <para>To specify whether the manpages are compressed upon
+ installation, use the <makevar>MANCOMPRESSED</makevar> variable.
+ This variable can take three values, <literal>yes</literal>,
+ <literal>no</literal> and <literal>maybe</literal>.
+ <literal>yes</literal> means manpages are already installed
+ compressed, <literal>no</literal> means they are not, and
+ <literal>maybe</literal> means the software already respects the
+ value of <makevar>NOMANCOMPRESS</makevar> so
+ <filename>bsd.port.mk</filename> does not have to do anything
+ special.</para>
+
+ <para><makevar>MANCOMPRESSED</makevar> is automatically set to
+ <literal>yes</literal> if <makevar>USE_IMAKE</makevar> is set and
+ <makevar>NO_INSTALL_MANPAGES</makevar> is not set, and to
+ <literal>no</literal> otherwise. You don't have to explicitly
+ define it unless the default is not suitable for your port.</para>
+
+ <para>If your port anchors its man tree somewhere other than
+ <makevar>PREFIX</makevar>, you can use the
+ <makevar>MANPREFIX</makevar> to set it. Also, if only manpages in
+ certain sections go in a non-standard place, such as some Perl
+ modules ports, you can set individual man paths using
+ <makevar>MAN<replaceable>sect</replaceable>PREFIX</makevar> (where
+ <replaceable>sect</replaceable> is one of <literal>1-9</literal>,
+ <literal>L</literal> or <literal>N</literal>).</para>
+
+ <para>If your manpages go to language-specific subdirectories, set
+ the name of the languages to <makevar>MANLANG</makevar>. The
+ value of this variable defaults to <literal>""</literal> (i.e.,
+ English only).</para>
+
+ <para>Here is an example that puts it all together.</para>
+
+ <programlisting>
+MAN1= foo.1
+MAN3= bar.3
+MAN4= baz.4
+MANLANG= "" ja
+MAN3PREFIX= ${PREFIX}/share/foobar
+MANCOMPRESSED= yes</programlisting>
+
+ <para>This states that six files are installed by this 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>
+ </sect2>
+
+ <sect2>
+ <title>Ports that require Motif</title>
+
+ <para>There are many programs that require a Motif library
+ (available from several commercial vendors, while there is
+ a free clone reported to be able to run many applications in
+ <filename>x11-toolkits/lesstif</filename>) to compile. Since
+ it is a popular toolkit and their licenses usually permit
+ redistribution of statically linked binaries, we have made
+ special provisions for handling ports that require Motif in a
+ way that we can easily compile binaries linked either
+ dynamically (for people who are compiling from the port) or
+ statically (for people who distribute packages).</para>
+
+ <sect3>
+ <title><makevar>REQUIRES_MOTIF</makevar></title>
+
+ <para>If your port requires Motif, define this variable in the
+ Makefile. This will prevent people who don't own a copy of
+ Motif from even attempting to build it.</para>
+ </sect3>
+
+ <sect3>
+ <title><makevar>MOTIFLIB</makevar></title>
+
+ <para>This variable will be set by
+ <filename>bsd.port.mk</filename> to be the appropriate reference
+ to the Motif library. Please patch the source to use this
+ wherever the Motif library is referenced in the
+ <filename>Makefile</filename> or
+ <filename>Imakefile</filename>.</para>
+
+ <para>There are two common cases:</para>
+
+ <itemizedlist>
+ <listitem><para>If the port refers to the Motif library as
+ <literal>-lXm</literal> in its <filename>Makefile</filename>
+ or <filename>Imakefile</filename>, simply substitute
+ <literal>${MOTIFLIB}</literal> for
+ it.</para></listitem>
+
+ <listitem><para>If the port uses <literal>XmClientLibs</literal>
+ in its <filename>Imakefile</filename>, change it to
+ <literal>${MOTIFLIB} ${XTOOLLIB}
+ ${XLIB}</literal>.</para></listitem>
+ </itemizedlist>
+
+ <para>Note that <makevar>MOTIFLIB</makevar> (usually) expands to
+ <literal>-L/usr/X11R6/lib -lXm</literal> or
+ <literal>/usr/X11R6/lib/libXm.a</literal>, so there is no need
+ to add <literal>-L</literal> or <literal>-l</literal> in
+ front.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>X11 fonts</title>
+
+ <para>If your port installs fonts for the X Window system, put them
+ in
+ <filename><makevar>X11BASE</makevar>/lib/X11/fonts/local</filename>.
+ This directory is new to XFree86 release 3.3.3. If it does not
+ exist, please create it, and print out a message urging the user
+ to update their XFree86 to 3.3.3 or newer, or at least add this
+ directory to the font path in
+ <filename>/etc/XF86Config</filename>.</para>
+ </sect2>
+
+ <sect2>
+ <title>Info files</title>
+
+ <para>The new version of texinfo (included in 2.2.2-RELEASE and
+ onwards) contains a utility called <command>install-info</command>
+ to add and delete entries to the <filename>dir</filename> file. If
+ your port installs any info documents, please follow this
+ instructions so your port/package will correctly update the user's
+ <filename><makevar>PREFIX</makevar>/info/dir</filename>
+ file. (Sorry for the length of this section, but is it imperative
+ to weave all the info files together. If done correctly, it will
+ produce a <emphasis>beautiful</emphasis> listing, so please bear
+ with me!</para>
+
+ <para>First, this is what you (as a porter) need to know</para>
+
+ <informalexample>
+ <screen>&prompt.user; <userinput>install-info --help</userinput>
+install-info [OPTION]... [INFO-FILE [DIR-FILE]]
+ Install INFO-FILE in the Info directory file DIR-FILE.
+
+Options:
+--delete Delete existing entries in INFO-FILE;
+ don't insert any new entries.
+ :
+--entry=TEXT Insert TEXT as an Info directory entry.
+ :
+--section=SEC Put this file's entries in section SEC of the directory. :</screen>
+ </informalexample>
+
+ <note>
+ <para>This program will not actually
+ <emphasis>install</emphasis> info files; it merely inserts or
+ deletes entries in the <filename>dir</filename> file.</para>
+ </note>
+
+ <para>Here's a seven-step procedure to convert ports to use
+ <command>install-info</command>. I will use
+ <filename>editors/emacs</filename> as an example.</para>
+
+ <procedure>
+ <step>
+ <para>Look at the texinfo sources and make a patch to insert
+ <literal>@dircategory</literal> and <literal>@direntry</literal>
+ statements to files that don't have them. This is part of
+ my patch:</para>
+
+ <programlisting>
+--- ./man/vip.texi.org Fri Jun 16 15:31:11 1995
++++ ./man/vip.texi Tue May 20 01:28:33 1997
+@@ -2,6 +2,10 @@
+
+ @setfilename ../info/vip
+ @settitle VIP
++@dircategory The Emacs editor and associated tools
++@direntry
++* VIP: (vip). A VI-emulation for Emacs.
++@end direntry
+
+ @iftex
+ @finalout
+ :</programlisting>
+
+ <para>The format should be self-explanatory. Many authors
+ leave a <filename>dir</filename> file in the source tree
+ that contains all the entries you need, so look around
+ before you try to write your own. Also, make sure you
+ look into related ports and make the section names and
+ entry indentations consistent (we recommend that all entry
+ text start at the 4th tab stop).</para>
+
+ <note>
+ <para>Note that you can put only one info entry per file
+ because of a bug in <command>install-info
+ --delete</command> that deletes only the first entry
+ if you specify multiple entries in the
+ <email>@direntry</email> section.</para>
+ </note>
+
+ <para>You can give the <literal>dir</literal>
+ entries to <command>install-info</command> as
+ arguments (<option>--section</option> and
+ <option>--entry</option>) instead of patching the texinfo
+ sources. I do not think this is a good idea for ports
+ because you need to duplicate the same information in
+ <emphasis>three</emphasis> places
+ (<filename>Makefile</filename> and
+ <literal>@exec</literal>/<literal>@unexec</literal> of
+ <filename>PLIST</filename>; see below). However, if you
+ have a Japanese (or other multibyte encoding) info files,
+ you will have to use the extra arguments to <command>install-info</command> because <command>makeinfo</command> can't handle those texinfo
+ sources. (See <filename>Makefile</filename> and
+ <filename>PLIST</filename> of
+ <filename>japanese/skk</filename> for examples on how to
+ do this).</para>
+ </step>
+
+ <step>
+ <para>Go back to the port directory and do a <command>make clean; make</command> and verify that
+ the info files are regenerated from the texinfo sources.
+ Since the texinfo sources are newer than the info files,
+ they should be rebuilt when you type <command>make</command>; but many
+ <filename>Makefile</filename>s don't include correct
+ dependencies for info files. In <command>emacs</command>' case, I had to
+ patch the main <filename>Makefile.in</filename> so it will
+ descend into the <filename>man</filename>
+ subdirectory to rebuild the info pages.</para>
+
+ <programlisting>
+--- ./Makefile.in.org Mon Aug 19 21:12:19 1996
++++ ./Makefile.in Tue Apr 15 00:15:28 1997
+@@ -184,7 +184,7 @@
+ # Subdirectories to make recursively. `lisp' is not included
+ # because the compiled lisp files are part of the distribution
+ # and you cannot remake them without installing Emacs first.
+-SUBDIR = lib-src src
++SUBDIR = lib-src src man
+
+ # The makefiles of the directories in $SUBDIR.
+ SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile lwlib/Makefile
+--- ./man/Makefile.in.org Thu Jun 27 15:27:19 1996
++++ ./man/Makefile.in Tue Apr 15 00:29:52 1997
+@@ -66,6 +66,7 @@
+ ${srcdir}/gnu1.texi \
+ ${srcdir}/glossary.texi
+
++all: info
+ info: $(INFO_TARGETS)
+
+ dvi: $(DVI_TARGETS)</programlisting>
+
+ <para>The second hunk was necessary because the default
+ target in the <filename>man</filename> subdir is called
+ <maketarget>info</maketarget>, while the main
+ <filename>Makefile</filename> wants to call <maketarget>all</maketarget>. I also deleted the installation
+ of the <filename>info</filename> info file
+ because we already have one with the same name in
+ <filename>/usr/share/info</filename> (that patch is not
+ shown here).</para>
+ </step>
+
+ <step>
+ <para>If there is a place in the
+ <filename>Makefile</filename> that is installing the
+ <filename>dir</filename> file, delete it. Your
+ port may not be doing it. Also, remove any commands that
+ are otherwise mucking around with the
+ <filename>dir</filename> file.</para>
+
+ <programlisting>
+--- ./Makefile.in.org Mon Aug 19 21:12:19 1996
++++ ./Makefile.in Mon Apr 14 23:38:07 1997
+@@ -368,14 +368,8 @@
+ if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \
+ then \
+ (cd ${infodir}; \
+- if [ -f dir ]; then \
+- if [ ! -f dir.old ]; then mv -f dir dir.old; \
+- else mv -f dir dir.bak; fi; \
+- fi; \
+ cd ${srcdir}/info ; \
+- (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir); \
+- (cd $${thisdir}; chmod a+r ${infodir}/dir); \
+ for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \
+ (cd $${thisdir}; \
+ ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \
+ chmod a+r ${infodir}/$$f); \</programlisting>
+ </step>
+
+ <step>
+ <para>(This step is only necessary if you are modifying an
+ existing port.) Take a look at
+ <filename>pkg/PLIST</filename> and delete anything that is
+ trying to patch up <filename>info/dir</filename>. They
+ may be in <filename>pkg/INSTALL</filename> or some other
+ file, so search extensively.</para>
+
+ <programlisting>
+Index: pkg/PLIST
+===================================================================
+RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v
+retrieving revision 1.15
+diff -u -r1.15 PLIST
+--- PLIST 1997/03/04 08:04:00 1.15
++++ PLIST 1997/04/15 06:32:12
+@@ -15,9 +15,6 @@
+ man/man1/emacs.1.gz
+ man/man1/etags.1.gz
+ man/man1/ctags.1.gz
+-@unexec cp %D/info/dir %D/info/dir.bak
+-info/dir
+-@unexec cp %D/info/dir.bak %D/info/dir
+ info/cl
+ info/cl-1
+ info/cl-2</programlisting>
+ </step>
+
+ <step>
+ <para>Add a <maketarget>post-install</maketarget>
+ target to the <filename>Makefile</filename> to create a
+ <filename>dir</filename> file if it is not there. Also,
+ call <maketarget>install-info</maketarget> with the
+ installed info files.</para>
+
+ <programlisting>
+Index: Makefile
+===================================================================
+RCS file: /usr/cvs/ports/editors/emacs/Makefile,v
+retrieving revision 1.26
+diff -u -r1.26 Makefile
+--- Makefile 1996/11/19 13:14:40 1.26
++++ Makefile 1997/05/20 10:25:09 1.28
+@@ -20,5 +20,11 @@
+ post-install:
+ .for file in emacs-19.34 emacsclient etags ctags b2m
+ strip ${PREFIX}/bin/${file}
+ .endfor
++ if [ ! -f ${PREFIX}/info/dir ]; then \
++ ${SED} -ne '1,/Menu:/p' /usr/share/info/dir > ${PREFIX}/info/dir; \
++ fi
++.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode
++ install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir
++.endfor
+
+ .include <bsd.port.mk></programlisting>
+
+ <para>Do not use anything other than
+ <filename>/usr/share/info/dir</filename> and the above
+ command to create a new info file. In fact, I'd add the
+ first three lines of the above patch to
+ <filename>bsd.port.mk</filename> if you (the porter)
+ wouldn't have to do it in <filename>PLIST</filename> by
+ yourself anyway.</para>
+ </step>
+
+ <step>
+ <para>Edit <filename>PLIST</filename> and add equivalent
+ <literal>@exec</literal> statements and also
+ <literal>@unexec</literal> for <command>pkg_delete</command>.
+ You do not need to delete <filename>info/dir</filename>
+ with <literal>@unexec</literal>.</para>
+
+ <programlisting>
+Index: pkg/PLIST
+===================================================================
+RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v
+retrieving revision 1.15
+diff -u -r1.15 PLIST
+--- PLIST 1997/03/04 08:04:00 1.15
++++ PLIST 1997/05/20 10:25:12 1.17
+@@ -16,7 +14,15 @@
+ man/man1/etags.1.gz
+ man/man1/ctags.1.gz
++@unexec install-info --delete %D/info/emacs %D/info/dir
+ :
++@unexec install-info --delete %D/info/ccmode %D/info/dir
+ info/cl
+ info/cl-1
+@@ -87,6 +94,18 @@
+ info/viper-3
+ info/viper-4
++@exec [ -f %D/info/dir ] || sed -ne '1,/Menu:/p' /usr/share/info/dir > %D/info/dir
++@exec install-info %D/info/emacs %D/info/dir
+ :
++@exec install-info %D/info/ccmode %D/info/dir
+ libexec/emacs/19.34/i386--freebsd/cvtmail
+ libexec/emacs/19.34/i386--freebsd/digest-doc</programlisting>
+
+ <note>
+ <para>The <literal>@unexec install-info
+ --delete</literal> commands have to be listed before
+ the info files themselves so they can read the files.
+ Also, the <literal>@exec install-info</literal> commands
+ have to be after the info files and the
+ <literal>@exec</literal> command that creates the the
+ <filename>dir</filename> file.</para>
+ </note>
+ </step>
+
+ <step>
+ <para><link linkend="porting-testing">Test</link> and admire your work. <!-- smiley --><emphasis>:)</emphasis>. Check the <filename>dir</filename> file before and after each
+ step.</para>
+ </step>
+ </procedure>
+
+ </sect2>
+
+ <sect2>
+ <title>The <filename>pkg/</filename> subdirectory</title>
+
+ <para>There are some tricks we haven't mentioned yet about the
+ <filename>pkg/</filename> subdirectory that come in handy
+ sometimes.</para>
+
+ <sect3 id="porting-message">
+ <title><filename>MESSAGE</filename></title>
+
+ <para>If you need to display a message to the installer, you may
+ place the message in <filename>pkg/MESSAGE</filename>. This
+ capability is often useful to display additional installation
+ steps to be taken after a <command>pkg_add</command> or to display
+ licensing information.</para>
+
+ <note>
+ <para>The <filename>pkg/MESSAGE</filename> file does not need to
+ be added to <filename>pkg/PLIST</filename>. Also, it will not get
+ automatically printed if the user is using the port, not the
+ package, so you should probably display it from the
+ <maketarget>post-install</maketarget> target yourself.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><filename>INSTALL</filename></title>
+
+ <para>If your port needs execute commands when the binary package is
+ installed with <command>pkg_add</command> you can do with via the
+ <filename>pkg/INSTALL</filename> script. This script will
+ automatically be added to the package, and will be run twice by
+ <command>pkg_add</command>. The first time will as
+ <literal>INSTALL ${PKGNAME} PRE-INSTALL</literal> and the
+ second time as <literal>INSTALL ${PKGNAME}
+ POST-INSTALL</literal>. <literal>$2</literal> can be
+ tested to determine which mode the script is being run in. The
+ <envar>PKG_PREFIX</envar> environmental variable will be set to
+ the package installation directory. See <citerefentry>
+ <refentrytitle>pkg_add</refentrytitle>
+ <manvolnum>1</manvolnum></citerefentry> for additional
+ information.</para>
+
+ <note>
+ <para>This script is not run automatically if you install the port
+ with <command>make install</command>. If you are depending on
+ it being run, you will have to explicitly call it on your port's
+ <filename>Makefile</filename>.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><filename>REQ</filename></title>
+
+ <para>If your port needs to determine if it should install or not,
+ you can create a <filename>pkg/REQ</filename>
+ “requirements” script. It will be invoked
+ automatically at installation/deinstallation time to determine
+ whether or not installation/deinstallation should proceed.</para>
+ </sect3>
+
+ <sect3 id="porting-plist">
+ <title>Changing <filename>PLIST</filename> based on make variables</title>
+
+ <para>Some ports, particularly the p5- ports, need to change their
+ <filename>PLIST</filename> depending on what options they are
+ configured with (or version of perl, in the case of p5- ports). To
+ make this easy, any instances in the <filename>PLIST</filename> of
+ <literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal>, and
+ <literal>%%PERL_VERSION%%</literal> will be substituted for
+ appropriately. The value of <literal>%%OSREL%%</literal> is the
+ numeric revision of the operating system (e.g.,
+ <literal>2.2.7</literal>). <literal>%%PERL_VERSION%%</literal> is
+ the full version number of perl (e.g., <literal>5.00502</literal>)
+ and <literal>%%PERL_VER%%</literal> is the perl version number
+ minus the patchlevel (e.g., <literal>5.005</literal>).</para>
+
+ <para>If you need to make other substitutions, you can set the
+ <makevar>PLIST_SUB</makevar> variable with a list of
+ <literal><replaceable>VAR</replaceable>=<replaceable>VALUE</replaceable></literal>
+ pairs and instances of
+ <literal>%%<replaceable>VAR</replaceable>%%</literal>' will be
+ substituted with <replaceable>VALUE</replaceable> in the
+ <filename>PLIST</filename>.</para>
+
+ <para>For instance, if you have a port that installs many files in
+ a version-specific subdirectory, you can put something
+ like
+
+ <programlisting>
+OCTAVE_VERSION= 2.0.13
+PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
+
+ in the <filename>Makefile</filename> and use
+ <literal>%%OCTAVE_VERSION%%</literal> wherever the version shows
+ up in <filename>PLIST</filename>. That way, when you upgrade the
+ port, you will not have to change dozens (or in some cases,
+ hundreds) of lines in the <filename>PLIST</filename>.</para>
+
+ <para>This substitution (as well as addition of any <link
+ linkend="porting-manpages">man pages</link>) will be done
+ between the <maketarget>do-install</maketarget> and
+ <maketarget>post-install</maketarget> targets, by reading from
+ <makevar>PLIST</makevar> and writing to
+ <makevar>TMPPLIST</makevar> (default:
+ <filename><makevar>WRKDIR</makevar>/.PLIST.mktmp</filename>). So
+ if your port builds <makevar>PLIST</makevar> on the fly, do so in
+ or before <maketarget>do-install</maketarget>. Also, if your port
+ needs to edit the resulting file, do so in
+ <maketarget>post-install</maketarget> to a file named
+ <makevar>TMPPLIST</makevar>.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Licensing Problems</title>
+
+ <para>Some software packages have restrictive licenses or can be
+ in violation to the law (PKP's patent on public key crypto, ITAR
+ (export of crypto software) to name just two of them). What we
+ can do with them vary a lot, depending on the exact wordings of
+ the respective licenses.</para>
+
+ <note>
+ <para>It is your responsibility as a porter to read the
+ licensing terms of the software and make sure that the FreeBSD
+ project will not be held accountable of violating them by
+ redistributing the source or compiled binaries either via ftp
+ or CD-ROM. If in doubt, please contact the &a.ports;.</para>
+ </note>
+
+ <para>There are two variables you can set in the Makefile to
+ handle the situations that arise frequently:</para>
+
+
+ <orderedlist>
+
+ <listitem>
+ <para>If the port has a “do not sell for profit” type of
+ license, set the variable <makevar>NO_CDROM</makevar> to a
+ string describing the reason why. We
+ will make sure such ports won't go into the CD-ROM come
+ release time. The distfile and package will still be
+ available via ftp.</para>
+ </listitem>
+
+ <listitem>
+ <para>If the resulting package needs to be built uniquely
+ for each site, or the resulting binary package can't be
+ distributed due to licensing; set the variable
+ <makevar>NO_PACKAGE</makevar> to a string describing the
+ reason why. We will make sure such
+ packages won't go on the ftp site, nor into the CD-ROM
+ come release time. The distfile will still be included on
+ both however.</para>
+ </listitem>
+
+ <listitem>
+ <para>If the port has legal restrictions on who can use it
+ (e.g., crypto stuff) or has a “no commercial use” license,
+ set the variable <makevar>RESTRICTED</makevar> to be the
+ string describing the reason why. For such ports, the
+ distfiles/packages will not be available even from our ftp
+ sites.</para>
+ </listitem>
+
+ </orderedlist>
+
+
+ <note>
+ <para>The GNU General Public License (GPL), both version 1
+ and 2, should not be a problem for ports.</para>
+ </note>
+
+ <note>
+ <para>If you are a committer, make sure you update the
+ <filename>ports/LEGAL</filename> file too.</para>
+ </note>
+ </sect2>
+
+ <sect2>
+ <title>Upgrading</title>
+
+ <para>When you notice that a port is out of date compared to the
+ latest version from the original authors, first make sure you
+ have the latest port. You can find them in the
+ <filename>ports-current</filename> directory of the ftp mirror
+ sites.</para>
+
+ <para>The next step is to send a mail to the maintainer, if one is
+ listed in the port's <filename>Makefile</filename>. That person may already be
+ working on an upgrade, or have a reason to not upgrade the port
+ right now (because of, for example, stability problems of the
+ new version).</para>
+
+ <para>If the maintainer asks you to do the upgrade or there isn't
+ any such person to begin with, please make the upgrade and send
+ the recursive diff (either unified or context diff is fine, but
+ port committers appear to prefer unified diff more) of the new
+ and old ports directories to us (e.g., if your modified port
+ directory is called <filename>superedit</filename>
+ and the original as in our tree is
+ <filename>superedit.bak</filename>, then send us the result of
+ <command>diff -ruN superedit.bak
+ superedit</command>). Please examine the output to make
+ sure all the changes make sense. The best way to send us the
+ diff is by including it to <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ (category <literal>ports</literal>). Please mention any added or deleted files
+ in the message, as they have to be explicitly specified to CVS
+ when doing a commit. If the diff is more than about 20KB, please
+ compress and uuencode it; otherwise, just include it in as is in
+ the PR.</para>
+
+ </sect2>
+
+ <sect2>
+ <title><anchor id="porting-dads">Do's and Dont's</title>
+
+ <para>Here is a list of common do's and dont's that you encounter
+ during the porting process.You should check your own port
+ against this list, but you can also check ports in the PR
+ database that others have submitted. Submit any comments on
+ ports you check as described in <link linkend="contrib-general">Bug
+ Reports and General Commentary</link>. Checking ports in
+ the PR database will both make it faster for us to commit them,
+ and prove that you know what you are doing.</para>
+
+ <sect3>
+ <title>Strip Binaries</title>
+
+ <para>Do strip binaries. If the original source already strips the
+ binaries, fine; otherwise you should add a
+ <literal>post-install</literal> rule to to it yourself. Here is an
+ example;</para>
+
+ <programlisting>
+post-install:
+ strip ${PREFIX}/bin/xdl</programlisting>
+
+ <para>Use the <citerefentry>
+ <refentrytitle>file</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry> command on the installed executable to check
+ whether the binary is stripped or not. If it does not say
+ <literal>not stripped</literal>, it is stripped.</para>
+ </sect3>
+
+ <sect3>
+ <title>INSTALL_* macros</title>
+
+ <para>Do use the macros provided in <filename>bsd.port.mk</filename>
+ to ensure correct modes and ownership of files in your own
+ <maketarget>*-install</maketarget> targets. They are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><makevar>INSTALL_PROGRAM</makevar> is a command to install
+ binary executables.</para>
+ </listitem>
+
+ <listitem>
+ <para><makevar>INSTALL_SCRIPT</makevar> is a command to install
+ executable scripts.</para>
+ </listitem>
+
+ <listitem>
+ <para><makevar>INSTALL_DATA</makevar> is a command to install
+ sharable data.</para>
+ </listitem>
+
+ <listitem>
+ <para><makevar>INSTALL_MAN</makevar> is a command to install
+ manpages and other documentation (it doesn't compress
+ anything).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>These are basically the <command>install</command> command
+ with all the appropriate flags. See below for an example on how
+ to use them.</para>
+ </sect3>
+
+ <sect3 id="porting-versions">
+ <title>Differentiating operating systems and OS versions</title>
+
+ <para>You may come across code that needs modifications or
+ conditional compilation based upon what version of UNIX it is
+ running under. If you need to make such changes to the code for
+ conditional compilation, make sure you make the changes as general
+ as possible so that we can back-port code to FreeBSD 1.x systems
+ and cross-port to other BSD systems such as 4.4BSD from CSRG,
+ BSD/386, 386BSD, NetBSD, and OpenBSD.</para>
+
+ <para>The preferred way to tell 4.3BSD/Reno (1990) and newer
+ versions of the BSD code apart is by using the
+ <literal>BSD</literal> macro defined in
+ <filename><sys/param.h></filename>. Hopefully that file is
+ already included; if not, add the code:</para>
+
+ <programlisting>
+#if (defined(__unix__) || defined(unix)) && !defined(USG)
+#include <sys/param.h>
+#endif</programlisting>
+
+ <para>to the proper place in the <filename>.c</filename> file. We
+ believe that every system that defines these to symbols has
+ <filename>sys/param.h</filename>. If you find a system that
+ doesn't, we would like to know. Please send mail to the
+ &a.ports;.</para>
+
+ <para>Another way is to use the GNU Autoconf style of doing
+ this:</para>
+
+ <programlisting>
+#ifdef HAVE_SYS_PARAM_H
+#include <sys/param.h>
+#endif</programlisting>
+
+ <para>Don't forget to add <literal>-DHAVE_SYS_PARAM_H</literal> to
+ the <makevar>CFLAGS</makevar> in the <filename>Makefile</filename>
+ for this method.</para>
+
+ <para>Once you have <filename>sys/param.h</filename>
+ included, you may use:</para>
+
+ <programlisting>
+#if (defined(BSD) && (BSD >= 199103))</programlisting>
+
+ <para>to detect if the code is being compiled on a 4.3 Net2 code
+ base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD,
+ BSD/386 1.1 and below).</para>
+
+ <para>Use:</para>
+
+ <programlisting>
+#if (defined(BSD) && (BSD >= 199306))</programlisting>
+
+ <para>to detect if the code is being compiled on a 4.4 code base
+ or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or
+ above).</para>
+
+ <para>The value of the <literal>BSD</literal> macro is
+ <literal>199506</literal> for the 4.4BSD-Lite2 code base. This is
+ stated for informational purposes only. It should not be used to
+ distinguish between version of FreeBSD based only on 4.4-Lite vs.
+ versions that have merged in changes from 4.4-Lite2. The
+ <literal>__FreeBSD__</literal> macro should be used
+ instead.</para>
+
+ <para>Use sparingly:</para>
+
+
+ <itemizedlist>
+
+ <listitem>
+ <para><literal>__FreeBSD__</literal> is defined in all
+ versions of FreeBSD. Use it if the change you are making
+ <emphasis>only</emphasis> affects FreeBSD. Porting gotchas like the use of
+ <literal>sys_errlist[]</literal> vs
+ <function>strerror()</function> are Berkeleyisms, not
+ FreeBSD changes.</para>
+ </listitem>
+
+ <listitem>
+ <para>In FreeBSD 2.x, <literal>__FreeBSD__</literal> is
+ defined to be <literal>2</literal>. In earlier
+ versions, it is <literal>1</literal>. Later
+ versions will bump it to match their major version number.</para>
+ </listitem>
+
+ <listitem>
+ <para>If you need to tell the difference between a FreeBSD
+ 1.x system and a FreeBSD 2.x or 3.x system, usually the
+ right answer is to use the <literal>BSD</literal> macros
+ described above. If there actually is a FreeBSD specific
+ change (such as special shared library options when using
+ <command>ld</command>) then it is OK to use
+ <literal>__FreeBSD__</literal> and <literal>#if
+ __FreeBSD__ > 1</literal> to detect a FreeBSD 2.x
+ and later system. If you need more granularity in
+ detecting FreeBSD systems since 2.0-RELEASE you can use
+ the following:</para>
+
+ <programlisting>
+#if __FreeBSD__ >= 2
+#include <osreldate.h>
+# if __FreeBSD_version >= 199504
+ /* 2.0.5+ release specific code here */
+# endif
+#endif</programlisting>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Release</entry>
+ <entry><literal>_FreeBSD_version</literal></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>2.0-RELEASE</entry>
+ <entry>119411</entry>
+ </row>
+
+ <row>
+ <entry>2.1-currents</entry>
+ <entry>199501, 199503</entry>
+ </row>
+
+ <row>
+ <entry>2.0.5-RELEASE</entry>
+ <entry>199504</entry>
+ </row>
+
+ <row>
+ <entry>2.2-current before 2.1</entry>
+ <entry>199508</entry>
+ </row>
+
+ <row>
+ <entry>2.1.0-RELEASE</entry>
+ <entry>199511</entry>
+ </row>
+
+ <row>
+ <entry>2.2-current before 2.1.5</entry>
+ <entry>199512</entry>
+ </row>
+
+ <row>
+ <entry>2.1.5-RELEASE</entry>
+ <entry>199607</entry>
+ </row>
+
+ <row>
+ <entry>2.2-current before 2.1.6</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 (no change)</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.1-RELEASE</entry>
+ <entry>220000 (no change)</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after texinfo-3.9</entry>
+ <entry>221001</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after top</entry>
+ <entry>221002</entry>
+ </row>
+
+ <row>
+ <entry>2.2.2-RELEASE</entry>
+ <entry>222000</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.2-RELEASE</entry>
+ <entry>222001</entry>
+ </row>
+
+ <row>
+ <entry>2.2.5-RELEASE</entry>
+ <entry>225000</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.5-RELEASE</entry>
+ <entry>225001</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after ldconfig -R merge</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-STABLE after 2.2.7-RELEASE</entry>
+ <entry>227001</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after semctl(2) change</entry>
+ <entry>227002</entry>
+ </row>
+
+ <row>
+ <entry>2.2.8-RELEASE</entry>
+ <entry>228000</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.8-RELEASE</entry>
+ <entry>228001</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current before mount(2) change</entry>
+ <entry>300000</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after mount(2) change</entry>
+ <entry>300001</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after semctl(2) change</entry>
+ <entry>300002</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after ioctl arg changes</entry>
+ <entry>300003</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after ELF conversion</entry>
+ <entry>300004</entry>
+ </row>
+
+ <row>
+ <entry>3.0-RELEASE</entry>
+ <entry>300005</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after 3.0-RELEASE</entry>
+ <entry>300006</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </listitem>
+ </itemizedlist>
+
+ <note>
+ <para>Note that 2.2-STABLE sometimes identifies itself as
+ “2.2.5-STABLE” after the 2.2.5-RELEASE. The pattern used to
+ be year followed by the month, but we decided to change it
+ to a more straightforward major/minor system starting from
+ 2.2. This is because the parallel development on several
+ branches made it infeasible to classify the releases simply
+ by their real release dates. If you are making a port now,
+ you don't have to worry about old -current's; they are
+ listed here just for your reference.</para>
+ </note>
+
+
+ <para>In the hundreds of ports that have been done, there have
+ only been one or two cases where <literal>__FreeBSD__</literal>
+ should have been used. Just because an earlier port screwed up
+ and used it in the wrong place does not mean you should do so
+ too.</para>
+ </sect3>
+
+ <sect3>
+ <title>Writing something after
+ <filename>bsd.port.mk</filename></title>
+
+ <para>Do not write anything after the <literal>.include
+ <bsd.port.mk></literal> line. it usually can be avoided by
+ including <filename>bsd.port.pre.mk</filename> somewhere in the
+ middle of your <filename>Makefile</filename> and
+ <filename>bsd.port.post.mk</filename> at the end.</para>
+
+ <note>
+ <para>You need to include either the
+ <filename>pre.mk</filename>/<filename>post.mk</filename> pair or
+ <filename>bsd.port.mk</filename> only; don't mix these
+ two.</para>
+ </note>
+
+ <para><filename>bsd.port.pre.mk</filename> only defines a few
+ variables, which can be used in tests in the
+ <filename>Makefile</filename>,
+ <filename>bsd.port.post.mk</filename> defines the rest.</para>
+
+ <para>Here are some important variables defined in
+ <filename>bsd.port.pre.mk</filename> (this is not the complete
+ list, please read <filename>bsd.port.mk</filename> for the
+ complete list).</para>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Variable</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><makevar>ARCH</makevar></entry>
+ <entry>The architecture as returned by <command>uname
+ -m</command> (e.g., <literal>i386</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>OPSYS</makevar></entry>
+ <entry>The operating system type, as returned by
+ <command>uname -s</command> (e.g.,
+ <literal>FreeBSD</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>OSREL</makevar></entry>
+ <entry>The release version of the operating system (e.g.,
+ <literal>2.1.5</literal> or
+ <literal>2.2.7</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>OSVERSION</makevar></entry>
+ <entry>The numeric version of the operating system, same as
+ <link
+ linkend="porting-versions"><literal>__FreeBSD_version</literal></link>.</entry>
+ </row>
+
+ <row>
+ <entry><makevar>PORTOBJFORMAT</makevar></entry>
+ <entry>The object format of the system
+ (<literal>aout</literal> or <literal>elf</literal></entry>
+ </row>
+
+ <row>
+ <entry><makevar>LOCALBASE</makevar></entry>
+ <entry>The base of the “local” tree (e.g.,
+ <literal>/usr/local/</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>X11BASE</makevar></entry>
+ <entry>The base of the “X11” tree (e.g.,
+ <literal>/usr/X11R6</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>PREFIX</makevar></entry>
+ <entry>Where the port installs itself (see <link
+ linkend="porting-prefix">more on
+ <makevar>PREFIX</makevar></link>).</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <note>
+ <para>If you have to define the variables
+ <makevar>USE_IMAKE</makevar>, <makevar>USE_X_PREFIX</makevar>,
+ or <makevar>MASTERDIR</makevar>, do so before including
+ <filename>bsd.port.pre.mk</filename>.</para>
+ </note>
+
+ <para>Here are some examples of things you can write after
+ <filename>bsd.port.pre.mk</filename>;</para>
+
+ <programlisting>
+# no need to compile lang/perl5 if perl5 is already in system
+.if ${OSVERSION} > 300003
+BROKEN= perl is in system
+.endif
+
+# only one shlib version number for ELF
+.if ${PORTOBJFORMAT} == "elf"
+TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}
+.else
+TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}.${SHLIB_MINOR}
+.endif
+
+# software already makes link for ELF, but not for a.out
+post-install:
+.if ${PORTOBJFORMAT} == "aout"
+ ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so
+.endif</programlisting>
+ </sect3>
+
+ <sect3>
+ <title>Install additional documentation</title>
+
+ <para>If your software has some documentation other than the
+ standard man and info pages that you think is useful for the
+ user, install it under
+ <filename><makevar>PREFIX</makevar>/share/doc</filename>. This can be
+ done, like the previous item, in the <maketarget>post-install</maketarget> target.</para>
+
+ <para>Create a new directory for your port. The directory name
+ should reflect what the port is. This usually means <makevar>PKGNAME</makevar> minus the version part.
+ However, if you think the user might want different versions
+ of the port to be installed at the same time, you can use the
+ whole <makevar>PKGNAME</makevar>.</para>
+
+ <para>Make the installation dependent to the variable
+ <makevar>NOPORTDOCS</makevar> so that users can disable it in
+ <filename>/etc/make.conf</filename>, like this:</para>
+
+ <programlisting>
+post-install:
+.if !defined(NOPORTDOCS)
+ ${MKDIR}${PREFIX}/share/doc/xv
+ ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
+.endif</programlisting>
+
+ <para>Do not forget to add them to
+ <filename>pkg/PLIST</filename> too! (Do not worry about
+ <makevar>NOPORTDOCS</makevar> here; there is currently no way
+ for the packages to read variables from
+ <filename>/etc/make.conf</filename>.)</para>
+
+ <para>Also you can use the <filename>pkg/MESSAGE</filename> file to
+ display messages upon installation. See the <link
+ linkend="porting-message">using
+ <filename>pkg/MESSAGE</filename></link> section for
+ details.</para>
+
+ <note>
+ <para><filename>MESSAGE</filename> does not need to be added
+ to <filename>pkg/PLIST</filename>).</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><makevar>DIST_SUBDIR</makevar></title>
+
+ <para>Do not let your port clutter
+ <filename>/usr/ports/distfiles</filename>. If your port
+ requires a lot of files to be fetched, or contains a file that
+ has a name that might conflict with other ports (e.g.,
+ <filename>Makefile</filename>), set <makevar>DIST_SUBDIR</makevar> to the name of the
+ port (<makevar>PKGNAME</makevar> without the
+ version part should work fine). This will change <makevar>DISTDIR</makevar> from the default
+ <filename>/usr/ports/distfiles</filename> to
+ <filename>/usr/ports/distfiles/<makevar>DIST_SUBDIR</makevar></filename>,
+ and in effect puts everything that is required for your port
+ into that subdirectory.</para>
+
+ <para>It will also look at the subdirectory with the same name
+ on the backup master site at
+ <filename>ftp.freebsd.org</filename>. (Setting <makevar>DISTDIR</makevar> explicitly in your
+ <makevar>Makefile</makevar> will not accomplish this, so please use <makevar>DIST_SUBDIR</makevar>.)</para>
+
+ <note>
+ <para>This does not affect the <makevar>MASTER_SITES</makevar> you define in your
+ Makefile.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>Package information</title>
+
+ <para>Do include package information, i.e.
+ <filename>COMMENT</filename>, <filename>DESCR</filename>, and
+ <filename>PLIST</filename>, in <filename>pkg</filename>.</para>
+
+ <note>
+ <para>Note that these files are not used only for packaging
+ anymore, and are <emphasis>mandatory</emphasis> now, even if
+ <makevar>NO_PACKAGE</makevar> is
+ set.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>RCS strings</title>
+
+ <para>Do not put RCS strings in patches. CVS will mangle them
+ when we put the files into the ports tree, and when we check
+ them out again, they will come out different and the patch
+ will fail. RCS strings are surrounded by dollar (<literal>$</literal>) signs, and typically start with
+ <literal>$Id</literal> or <literal>$RCS</literal>.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Recursive diff</title>
+
+ <para>Using the recurse (<option>-r</option>) option to
+ <command>diff</command> to generate patches is
+ fine, but please take a look at the resulting patches to make
+ sure you don't have any unnecessary junk in there. In
+ particular, diffs between two backup files, <filename>Makefiles</filename> when the
+ port uses <command>Imake</command> or GNU <command>configure</command>, etc., are unnecessary and
+ should be deleted. If you had to edit
+ <filename>configure.in</filename> and run
+ <command>autoconf</command> to regenerate
+ <command>configure</command>, do not take the diffs of
+ <command>configure</command> (it often grows to a few thousand
+ lines!); define <literal>USE_AUTOCONF=yes</literal> and take the
+ diffsof <filename>configure.in</filename>.</para>
+
+ <para>Also, if you had to delete a file, then you
+ can do it in the <maketarget>post-extract</maketarget>
+ target rather than as part of the patch. Once you are happy
+ with the resulting diff, please split it up into one source
+ file per patch file.</para>
+
+ </sect3>
+
+ <sect3 id="porting-prefix">
+ <title><makevar>PREFIX</makevar></title>
+
+ <para>Do try to make your port install relative to <makevar>PREFIX</makevar>. (The value of this
+ variable will be set to <makevar>LOCALBASE</makevar> (default
+ <filename>/usr/local</filename>), unless <makevar>USE_X_PREFIX</makevar> or <makevar>USE_IMAKE</makevar> is set, in which case it
+ will be <makevar>X11BASE</makevar> (default
+ <filename>/usr/X11R6</filename>).)</para>
+
+ <para>Not hard-coding <filename>/usr/local</filename> or
+ <filename>/usr/X11R6</filename> anywhere in the source will
+ make the port much more flexible and able to cater to the
+ needs of other sites. For X ports that use <command>imake</command>, this is
+ automatic; otherwise, this can often be done by simply
+ replacing the occurrences of <filename>/usr/local</filename>
+ (or <filename>/usr/X11R6</filename> for X ports that do not
+ use imake) in the various scripts/Makefiles in the port to
+ read <makevar>PREFIX</makevar>, as this
+ variable is automatically passed down to every stage of the
+ build and install processes.</para>
+
+ <para>Do not set <makevar>USE_X_PREFIX</makevar> unless your port
+ truly require it (i.e., it links against X libs or it needs to
+ reference files in <makevar>X11BASE</makevar>).</para>
+
+ <para>The variable <makevar>PREFIX</makevar>
+ can be reassigned in your <filename>Makefile</filename> or in the user's
+ environment. However, it is strongly discouraged for
+ individual ports to set this variable explicitly in the
+ <filename>Makefiles</filename>.</para>
+
+ <para>Also, refer to programs/files from other ports with the
+ variables mentioned above, not explicit pathnames. For
+ instance, if your port requires a macro
+ <literal>PAGER</literal> to be the full pathname of <command>less</command>, use the compiler flag:
+
+ <programlisting>
+-DPAGER=\"${PREFIX}/bin/less\"</programlisting>
+
+ or
+
+ <programlisting>
+-DPAGER=\"${LOCALBASE}/bin/less\"</programlisting>
+
+ if this is an X port, instead of <literal>-DPAGER=\"/usr/local/bin/less\".</literal> This way it will have a better chance of working if the system administrator has moved the whole `/usr/local' tree somewhere else.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Subdirectories</title>
+
+ <para>Try to let the port put things in the right subdirectories
+ of <makevar>PREFIX</makevar>. Some ports
+ lump everything and put it in the subdirectory with the port's
+ name, which is incorrect. Also, many ports put everything
+ except binaries, header files and manual pages in the a
+ subdirectory of <filename>lib</filename>, which does not
+ bode well with the BSD paradigm. Many of the files should be
+ moved to one of the following: <filename>etc</filename>
+ (setup/configuration files), <filename>libexec</filename>
+ (executables started internally), <filename>sbin</filename>
+ (executables for superusers/managers),
+ <filename>info</filename> (documentation for info browser)
+ or <filename>share</filename> (architecture independent
+ files). See man <citerefentry><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+ details, the rule governing <filename>/usr</filename> pretty
+ much applies to <filename>/usr/local</filename> too. The
+ exception are ports dealing with USENET “news”. They may use
+ <filename><makevar>PREFIX</makevar>/news</filename> as a destination for
+ their files.</para>
+
+ </sect3>
+
+ <sect3 id="porting-cleaning">
+ <title>Cleaning up empty directories</title>
+
+ <para>Do make your ports clean up after themselves when they are
+ deinstalled. This is usually accomplished by adding
+ <literal>@dirrm</literal> lines for all directories that are
+ specifically created by the port. You need to delete
+ subdirectories before you can delete parent directories.</para>
+
+ <programlisting>
+ :
+lib/X11/oneko/pixmaps/cat.xpm
+lib/X11/oneko/sounds/cat.au
+ :
+@dirrm lib/X11/oneko/pixmals
+@dirrm lib/X11/oneko/sounds
+@dirrm lib/X11/oneko</programlisting>
+
+ <para>However, sometimes <literal>@dirrm</literal> will give you
+ errors because other ports also share the same subdirectory. You
+ can call <command>rmdir</command> from <literal>@unexec</literal>
+ to remove only empty directories without warning.</para>
+
+ <programlisting>
+@unexec rmdir %D/share/doc/gimp 2>/dev/null || true</programlisting>
+
+ <para>This will neither print any error messages nor cause
+ <command>pkg_delete</command> to exit abnormally even if
+ <filename><makevar>PREFIX</makevar>/share/doc/gimp</filename> is
+ not empty due to other ports installing some files in there.</para>
+ </sect3>
+
+
+ <sect3>
+ <title>UIDs</title>
+
+ <para>If your port requires a certain user to be on the
+ installed system, let the <filename>pkg/INSTALL</filename>
+ script call <command>pw</command> to create it
+ automatically. Look at <filename>net/cvsup-mirror</filename>
+ for an example.</para>
+
+ <para>If your port must use the same user/group ID number when it is
+ installed a binarypackage as when it was compiled, then you mus
+ choose a free UID from 50 to 99 and register it below. Look at
+ <filename>japanese/Wnn</filename> for an example.</para>
+
+ <para>Make sure you don't use a UID already used by the system
+ or other ports. This is the current list of UIDs between 50
+ and 99.</para>
+
+ <programlisting>
+majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent
+cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent
+gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh
+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:/nonexistent
+wnn:*:69:7:Wnn:/nonexistent:/nonexistent
+ifmail:*:70:66:Ifmail user:/nonexistent:/nonexistent
+pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh
+ircd:*:72:72:IRCd hybrid:/nonexistent:/nonexistent
+alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent
+qmaill:*:83:81:QMail user:/var/qmail:/nonexistent
+qmaild:*:82:81:QMail user:/var/qmail:/nonexistent
+qmailq:*:85:82:QMail user:/var/qmail:/nonexistent
+qmails:*:87:82:QMail user:/var/qmail:/nonexistent
+qmailp:*:84:81:QMail user:/var/qmail:/nonexistent
+qmailr:*:86:82:QMail user:/var/qmail:/nonexistent
+msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh</programlisting>
+
+ <para>Please include a notice when you submit a port (or an
+ upgrade) that reserves a new UID or GID in this range. This allows
+ us to keep the list of reserved IDs up to date.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Do things rationally</title>
+
+ <para>The <filename>Makefile</filename> should do things simply and
+ reasonably. If you can make it a couple of lines shorter or more
+ readable, then do so. Examples include using a make
+ <literal>.if</literal> construct instead of a shell
+ <literal>if</literal> construct, not redefining
+ <maketarget>do-extract</maketarget> if you can redefine
+ <makevar>EXTRACT*</makevar> instead, and using
+ <makevar>GNU_CONFIGURE</makevar> instead of
+ <literal>CONFIGURE_ARGS +=
+ --prefix=${PREFIX}</literal>.</para>
+ </sect3>
+
+ <sect3>
+ <title>Respect <makevar>CFLAGS</makevar></title>
+
+ <para>The port should respect the <makevar>CFLAGS</makevar>
+ variable. If it doesn't, please add <literal>NO_PACKAGE=ignores
+ cflags</literal> to the <filename>Makefile</filename>.</para>
+ </sect3>
+
+ <sect3>
+ <title>Configuration files</title>
+
+ <para>If your port requires some configuration files in
+ <filename><makevar>PREFIX</makevar>/etc</filename>, do
+ <emphasis>not</emphasis> just install them and list them in
+ <filename>pkg/PLIST</filename>. That will cause
+ <command>pkg_delete</command> to delete files carefully edited by
+ the user and a new installation to wipe them out.</para>
+
+ <para>Instead, install sample files with a suffix
+ (<filename><replaceable>filename</replaceable>.sample</filename>
+ will work well) and print out a <link
+ linkend="porting-message">message</link> pointing out that the
+ user has to copy and edit the file before the software can be made
+ to work.</para>
+ </sect3>
+
+ <sect3>
+ <title>Portlint</title>
+
+ <para>Do check your work with <link
+ linkend="porting-portlint"><command>portlint</command></link>
+ before you submit or commit it.</para>
+ </sect3>
+
+ <sect3>
+ <title>Feedback</title>
+
+ <para>Do send applicable changes/patches to the original
+ author/maintainer for inclusion in next release of the code. This
+ will only make your job that much easier for the next
+ release.</para>
+ </sect3>
+
+ <sect3>
+ <title>Miscellanea</title>
+
+ <para>The files <filename>pkg/DESCR</filename>,
+ <filename>pkg/COMMENT</filename>, and
+ <filename>pkg/PLIST</filename> should each be double-checked. If
+ you are reviewing a port and feel they can be worded better, do
+ so.</para>
+
+ <para>Don't copy more copies of the GNU General Public License into
+ our system, please.</para>
+
+ <para>Please be careful to note any legal issues! Don't let us
+ illegally distribute software!</para>
+ </sect3>
+
+ <sect3>
+ <title>If you are stuck…</title>
+
+ <para>Do look at existing examples and the
+ <filename>bsd.port.mk</filename> file before asking us
+ questions! <!-- smiley --><emphasis>;)</emphasis></para>
+
+ <para>Do ask us questions if you have any trouble! Do not just
+ beat your head against a wall! <!-- smiley --><emphasis>:)</emphasis></para>
+
+ </sect3>
+ </sect2>
+
+ <sect2 id="porting-samplem">
+ <title>A Sample <filename>Makefile</filename></title>
+
+ <para>Here is a sample <filename>Makefile</filename> that you can
+ use to create a new port. Make sure you remove all the extra
+ comments (ones between brackets)!</para>
+
+ <para>It is recommended that you follow this format (ordering of
+ variables, empty lines between sections, etc.). This format is
+ designed so that the most important information is easy to
+ locate. We recommend that you use <link
+ linkend="porting-portlint">portlint</link> to check the <filename>Makefile</filename>.</para>
+
+ <programlisting>
+[the header...just to make it easier for us to identify the ports.]
+# New ports collection makefile for: xdvi
+[the version required header should updated when upgrading a port.]
+# Version required: pl18 [things like "1.5alpha" are fine here too]
+[this is the date when the first version of this Makefile was created.
+Never change this when doing an update of the port.]
+# Date created: 26 May 1995
+[this is the person who did the original port to FreeBSD, in particular, the
+person who wrote the first version of this Makefile. Remember, this should
+not be changed when upgrading the port later.]
+# Whom: Satoshi Asami <asami@FreeBSD.ORG>
+#
+# $Id$
+[ ^^^^ This will be automatically replaced with RCS ID string by CVS
+when it is committed to our repository.]
+#
+
+[section to describe the port itself and the master site - DISTNAME
+ is always first, followed by PKGNAME (if necessary), CATEGORIES,
+ and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR.
+ After those, one of EXTRACT_SUFX or DISTFILES can be specified too.]
+DISTNAME= xdvi
+PKGNAME= xdvi-pl18
+CATEGORIES= print
+[do not forget the trailing slash ("/")!
+ if you aren't using MASTER_SITE_* macros]
+MASTER_SITES= ${MASTER_SITE_XCONTRIB}
+MASTER_SITE_SUBDIR= applications
+[set this if the source is not in the standard ".tar.gz" form]
+EXTRACT_SUFX= .tar.Z
+
+[section for distributed patches -- can be empty]
+PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/
+PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz
+
+[maintainer; *mandatory*! This is the person (preferably with commit
+ privileges) who a user can contact for questions and bug reports - this
+ person should be the porter or someone who can forward questions to the
+ original porter reasonably promptly. If you really do not want to have
+ your address here, set it to "ports@FreeBSD.ORG".]
+MAINTAINER= asami@FreeBSD.ORG
+
+[dependencies -- can be empty]
+RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript
+LIB_DEPENDS= Xpm.5:${PORTSDIR}/graphics/xpm
+
+[this section is for other standard bsd.port.mk variables that do not
+ belong to any of the above]
+[If it asks questions during configure, build, install...]
+IS_INTERACTIVE= yes
+[If it extracts to a directory other than ${DISTNAME}...]
+WRKSRC= ${WRKDIR}/xdvi-new
+[If the distributed patches were not made relative to ${WRKSRC}, you
+ may need to tweak this]
+PATCH_DIST_STRIP= -p1
+[If it requires a "configure" script generated by GNU autoconf to be run]
+GNU_CONFIGURE= yes
+[If it requires GNU make, not /usr/bin/make, to build...]
+USE_GMAKE= yes
+[If it is an X application and requires "xmkmf -a" to be run...]
+USE_IMAKE= yes
+[et cetera.]
+
+[non-standard variables to be used in the rules below]
+MY_FAVORITE_RESPONSE= "yeah, right"
+
+[then the special rules, in the order they are called]
+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
+
+[and then the epilogue]
+.include <bsd.port.mk></programlisting>
+
+ </sect2>
+
+ <sect2 id="porting-pkgname">
+ <title>Package Names</title>
+
+ <para>The following are the conventions you should follow in
+ naming your packages. This is to have our package directory
+ easy to scan, as there are already lots and lots of packages and
+ users are going to turn away if they hurt their eyes!</para>
+
+ <para>The package name should look like <filename><replaceable>language-</replaceable>name<replaceable>-compiled.specifics</replaceable><replaceable>-version.numbers</replaceable></filename>.</para>
+
+ <para>If your <makevar>DISTNAME</makevar>
+ doesn't look like that, set <makevar>PKGNAME</makevar> to something in that
+ format.</para>
+
+
+ <orderedlist>
+
+ <listitem>
+ <para>FreeBSD strives to support the native language of its
+ users. The <replaceable>language-</replaceable> part should be a two letter
+ abbreviation of the natural language defined by ISO-639 if
+ the port is specific to a certain language. Examples are
+ <literal>ja</literal> for Japanese, <literal>ru</literal> for Russian, <literal>vi</literal> for Vietnamese,
+ <literal>zh</literal> for Chinese, <literal>ko</literal> for Korean and <literal>de</literal> for German.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <filename>name</filename> part
+ should be all lowercases, except for a really large
+ package (with lots of programs in it). Things like
+ XFree86 (yes there really is a port of it, check it
+ out) and ImageMagick fall into this category. Otherwise,
+ convert the name (or at least the first letter) to
+ lowercase. If the capital letters are
+ important to the name (for example, with one-letter names
+ like <literal>R</literal> or <literal>V</literal>) you may use capital letters at your discretion.
+ There is a tradition of naming Perl 5 modules by prepending
+ <literal>p5-</literal> and converting the double-colon separator to a hyphen;
+ for example, the <literal>Data::Dumper</literal> module becomes
+ <literal>p5-Data-Dumper</literal>. If the software in question has numbers,
+ hyphens, or underscores in its name, you may include them as
+ well (like <literal>kinput2</literal>).</para>
+ </listitem>
+
+ <listitem>
+ <para>If the port can be built with different <link linkend="porting-masterdir">hardcoded
+ defaults</link> (usually part of the directory name in a
+ family of ports), the
+ <replaceable>-compiled.specifics</replaceable> part should state the
+ compiled-in defaults (the hyphen is optional). Examples
+ are papersize and font units.</para>
+ </listitem>
+
+ <listitem>
+ <para>The version string should be a period-separated list
+ of integers and single lowercase alphabetics. The only
+ exception is the string <literal>pl</literal> (meaning `patchlevel'), which
+ can be used <emphasis>only</emphasis> when there are no
+ major and minor version numbers in the software.</para>
+ </listitem>
+
+ </orderedlist>
+
+
+ <para>Here are some (real) examples on how to convert a <makevar>DISTNAME</makevar> into a suitable <makevar>PKGNAME</makevar>:</para>
+
+ <informaltable frame="none">
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Distribution Name</entry>
+ <entry>Package Name</entry>
+ <entry>Reason</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>mule-2.2.2.</entry>
+ <entry>mule-2.2.2</entry>
+ <entry>No changes required</entry>
+ </row>
+
+ <row>
+ <entry>XFree86-3.1.2</entry>
+ <entry>XFree86-3.1.2</entry>
+ <entry>No changes required</entry>
+ </row>
+
+ <row>
+ <entry>EmiClock-1.0.2</entry>
+ <entry>emiclock-1.0.2</entry>
+ <entry>No uppercase names for single programs</entry>
+ </row>
+
+ <row>
+ <entry>gmod1.4</entry>
+ <entry>gmod-1.4</entry>
+ <entry>Need a hyphen before version numbers</entry>
+ </row>
+
+ <row>
+ <entry>xmris.4.0.2</entry>
+ <entry>xmris-4.0.2</entry>
+ <entry>Need a hyphen before version numbers</entry>
+ </row>
+
+ <row>
+ <entry>rdist-1.3alpha</entry>
+ <entry>rdist-1.3a</entry>
+ <entry>No strings like <literal>alpha</literal>
+ allowed</entry>
+ </row>
+
+ <row>
+ <entry>es-0.9-beta1</entry>
+ <entry>es-0.9b1</entry>
+ <entry>No strings like <literal>beta</literal>
+ allowed</entry>
+ </row>
+
+ <row>
+ <entry>v3.3beta021.src</entry>
+ <entry>tiff-3.3</entry>
+ <entry>What the heck was that anyway?</entry>
+ </row>
+
+ <row>
+ <entry>tvtwm</entry>
+ <entry>tvtwm-pl11</entry>
+ <entry>Version string always required</entry>
+ </row>
+
+ <row>
+ <entry>piewm</entry>
+ <entry>piewm-1.0</entry>
+ <entry>Version string always required</entry>
+ </row>
+
+ <row>
+ <entry>xvgr-2.10pl1</entry>
+ <entry>xvgr-2.10.1</entry>
+ <entry><literal>pl</literal> allowed only when no
+ major/minor version numbers</entry>
+ </row>
+
+ <row>
+ <entry>gawk-2.15.6</entry>
+ <entry>ja-gawk-2.15.6</entry>
+ <entry>Japanese language version</entry>
+ </row>
+
+ <row>
+ <entry>psutils-1.13</entry>
+ <entry>psutils-letter-1.13</entry>
+ <entry>Papersize hardcoded at package build time</entry>
+ </row>
+
+ <row>
+ <entry>pkfonts</entry>
+ <entry>pkfonts300-1.0</entry>
+ <entry>Package for 300dpi fonts</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>If there is absolutely no trace of version information in
+ the original source and it is unlikely that the original author
+ will ever release another version, just set the version string
+ to <literal>1.0</literal> (like the piewm example above). Otherwise, ask the
+ original author or use the date string (<literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>) as the
+ version.</para>
+
+ </sect2>
+
+ <sect2 id="porting-categories">
+ <title>Categories</title>
+
+ <para>As you already know, ports are classified in several
+ categories. But for this to wor, it is important that porters and
+ users understand what each category and how we deicde what to put in
+ each category.</para>
+
+ <sect3>
+ <title>Current list of categories</title>
+
+ <para>First, this is the current list of port categories. Those
+ marked with an asterisk (<literal>*</literal>) are
+ <emphasis>virtual</emphasis> categories—those that do not
+ have a corresponding subdirectory in the ports tree.</para>
+
+ <note>
+ <para>For non-virtual categories, you will find a one-line
+ description in the <filename>pkg/COMMENT</filename> file in that
+ subdirectory (e.g.,
+ <filename>archivers/pkg/COMMENT</filename>).</para>
+ </note>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Category</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><filename>archivers</filename></entry>
+ <entry>Archiving tools.</entry>
+ </row>
+
+ <row>
+ <entry><filename>astro</filename></entry>
+ <entry>Astronomical ports.</entry>
+ </row>
+
+ <row>
+ <entry><filename>audio</filename></entry>
+ <entry>Sound support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>benchmarks</filename></entry>
+ <entry>Benchmarking utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>biology</filename></entry>
+ <entry>Biology-related software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>cad</filename></entry>
+ <entry>Computer aided design tools.</entry>
+ </row>
+
+ <row>
+ <entry><filename>chinese</filename></entry>
+ <entry>Chinese language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>comms</filename></entry>
+ <entry>Communication software. Mostly software to talk to
+ your serial port.</entry>
+ </row>
+
+ <row>
+ <entry><filename>converters</filename></entry>
+ <entry>Character code converters.</entry>
+ </row>
+
+ <row>
+ <entry><filename>databases</filename></entry>
+ <entry>Databases.</entry>
+ </row>
+
+ <row>
+ <entry><filename>deskutils</filename></entry>
+ <entry>Things that used to be on the desktop before
+ computers were invented.</entry>
+ </row>
+
+ <row>
+ <entry><filename>devel</filename></entry>
+ <entry>Development utilities. Do not put libraries here just
+ because they are libraries—unless they truly don't
+ belong to anywhere else, they shouldn't be in this
+ category.</entry>
+ </row>
+
+ <row>
+ <entry><filename>editors</filename></entry>
+ <entry>General editors. Specialized editors go in the
+ section for those tools (e.g., a mathematical-formula
+ editor will go in <filename>math</filename>).</entry>
+ </row>
+
+ <row>
+ <entry><filename>elisp</filename></entry>
+ <entry>Emacs-lisp ports.</entry>
+ </row>
+
+ <row>
+ <entry><filename>emulators</filename></entry>
+ <entry>Emulators for other operating systems. Terminal
+ emulators do <emphasis>not</emphasis> belong
+ here—X-based ones should go to
+ <filename>x11</filename> and text-based ones to either
+ <filename>comms</filename> or <filename>misc</filename>,
+ depending on the exact functionality.</entry>
+ </row>
+
+ <row>
+ <entry><filename>games</filename></entry>
+ <entry>Games.</entry>
+ </row>
+
+ <row>
+ <entry><filename>german</filename></entry>
+ <entry>German language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>graphics</filename></entry>
+ <entry>Graphics utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>japanese</filename></entry>
+ <entry>Japanese language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>kde*</filename></entry>
+ <entry>Ports that form the K Desktop Environment
+ (kde).</entry>
+ </row>
+
+ <row>
+ <entry><filename>korean</filename></entry>
+ <entry>Korean language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>lang</filename></entry>
+ <entry>Programming languages.</entry>
+ </row>
+
+ <row>
+ <entry><filename>mail</filename></entry>
+ <entry>Mail software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>math</filename></entry>
+ <entry>Numerical computation software and other utilities
+ for mathematics.</entry>
+ </row>
+
+ <row>
+ <entry><filename>mbone</filename></entry>
+ <entry>MBone applications.</entry>
+ </row>
+
+ <row>
+ <entry><filename>misc</filename></entry>
+ <entry>Miscellaneous utilities—basically things that
+ doesn't belong to anywhere else. This is the only category
+ that should not appear with any other non-virtual
+ category. If you have <literal>misc</literal> with
+ something else in your <makevar>CATEGORIES</makevar> line,
+ that means you can safely delete <literal>misc</literal>
+ and just put the port in that other subdirectory!</entry>
+ </row>
+
+ <row>
+ <entry><filename>net</filename></entry>
+ <entry>Miscellaneous networking software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>news</filename></entry>
+ <entry>USENET news software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>offix*</filename></entry>
+ <entry>Ports from the OffiX suite.</entry>
+ </row>
+
+ <row>
+ <entry><filename>perl5*</filename></entry>
+ <entry>Ports that require perl version 5 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>pilot*</filename></entry>
+ <entry>Software to use with the 3Com PalmPilot.</entry>
+ </row>
+
+ <row>
+ <entry><filename>plan9</filename></entry>
+ <entry>Various programs from Plan9.</entry>
+ </row>
+
+ <row>
+ <entry><filename>print</filename></entry>
+ <entry>Printing software. Desktop publishing tools
+ (previewers, etc.) belong here too.</entry>
+ </row>
+
+ <row>
+ <entry><filename>python*</filename></entry>
+ <entry>Software written in python.</entry>
+ </row>
+
+ <row>
+ <entry><filename>russian</filename></entry>
+ <entry>Russian language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>security</filename></entry>
+ <entry>Security utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>shells</filename></entry>
+ <entry>Command line shells.</entry>
+ </row>
+
+ <row>
+ <entry><filename>sysutils</filename></entry>
+ <entry>System utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl75*</filename></entry>
+ <entry>Ports that use tcl version 7.5 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl76*</filename></entry>
+ <entry>Ports that use tcl version 7.6 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl80*</filename></entry>
+ <entry>Ports that use tcl version 8.0 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl81*</filename></entry>
+ <entry>Ports that use tcl version 8.1 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>textproc</filename></entry>
+ <entry>Text processing utilities. It does not include
+ desktop publishing tools, which go to print/.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk41*</filename></entry>
+ <entry>Ports that use tk version 4.1 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk42*</filename></entry>
+ <entry>Ports that use tk version 4.2 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk80*</filename></entry>
+ <entry>Ports that use tk version 8.0 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk81*</filename></entry>
+ <entry>Ports that use tk version 8.1 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>vietnamese</filename></entry>
+ <entry>Vietnamese language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>www</filename></entry>
+ <entry>Software related to the World Wide Web. HTML language
+ support belong here too.</entry>
+ </row>
+
+ <row>
+ <entry>x11</entry>
+ <entry>The X window system and friends. This category is
+ only for software that directly support the window system.
+ Do not put regular X applications here. If your port is
+ an X application, define <makevar>USE_XLIB</makevar>
+ (implied by <makevar>USE_IMAKE</makevar>) and put it in
+ appropriate categories. Also, many of them go into other
+ <filename>x11-*</filename> categories (see below).</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-clocks</filename></entry>
+ <entry>X11 clocks.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-fm</filename></entry>
+ <entry>X11 file managers.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-fonts</filename></entry>
+ <entry>X11 fonts and font utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-toolkits</filename></entry>
+ <entry>X11 toolkits.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-wm</filename></entry>
+ <entry>X11 window managers.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect3>
+
+ <sect3>
+ <title>Choosing the right category</title>
+
+ <para>As many of the categories overlap, you often have to choose
+ which of the categories should be the primary category of your
+ port. There are several rules that govern this usse. Here is the
+ list of priorities, in decreasing order of precedence.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Language specific categories alwasys come first. For
+ example, if your port installs Japanese X11 fonts, then your
+ <makevar>CATEGORIES</makevar> line would read
+ <literal>japanese x11</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Specific categories win over less-specific ones. For
+ instance, an HTML editor should be listed as <literal>www
+ editors</literal>, not the other way around. Also, you don't
+ need to list <literal>net</literal> when the port belongs to
+ either of <literal>mail</literal>, <literal>mbone</literal>,
+ <literal>news</literal>, <literal>security</literal>, or
+ <literal>www</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>x11</literal> is used as a secondary category
+ only when the primary category is a natural language. In
+ particular, you should not put <literal>x11</literal> in the
+ category line for X applications.</para>
+ </listitem>
+
+ <listitem>
+ <para>If your port truly does not belong anywhere else, put it
+ in <literal>misc</literal>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>If you are not sure about the category, please put a comment
+ to that effect in your <command>send-pr</command> submission so we
+ can discuss it before import it. (If you are a committer, send a
+ note &a.ports; so we can discuss it first—too often new
+ ports are imported to a wrong category only to be moved right
+ away.)</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Changes to this document and the ports system</title>
+
+ <para>If you maintain a lot of ports, you should consider following
+ the &a.ports;. Important changes to
+ the way ports work will be announced there. You can always
+ find more detailed information on the latest changes by
+ looking at <ulink
+ url="http://www.FreeBSD.ORG/cgi/cvsweb.cgi/src/share/mk/bsd.port.mk">
+ the bsd.port.mk CVS log</ulink>.</para>
+ </sect2>
+
+ <sect2>
+ <title>That is It, Folks!</title>
+
+ <para>Boy, this sure was a long tutorial, wasn't it? Thanks for
+ following us to here, really.</para>
+
+ <para>Well, now that you know how to do a port, let us go at it
+ and convert everything in the world into ports! That is the
+ easiest way to start contributing to the FreeBSD Project!
+ <!-- smiley --><emphasis>:)</emphasis></para>
+
+ </sect2>
+ </sect1>
+
</chapter>
@@ -1053,9 +4516,7 @@ grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arc
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO8859-1/share/sgml/authors.ent b/en_US.ISO8859-1/share/sgml/authors.ent
index a8c95c2ac6..80e0daca31 100644
--- a/en_US.ISO8859-1/share/sgml/authors.ent
+++ b/en_US.ISO8859-1/share/sgml/authors.ent
@@ -7,7 +7,7 @@
Please keep this list in alphabetical order by entity names.
- $Id: authors.ent,v 1.3 1998-11-12 01:26:17 nik Exp $
+ $Id: authors.ent,v 1.4 1998-12-10 20:43:39 nik Exp $
-->
<!ENTITY a.abial "Andrzej Bialecki <email>abial@FreeBSD.ORG</email>">
@@ -30,10 +30,12 @@
<!ENTITY a.awebster "Andrew Webster <email>awebster@pubnix.net</email>">
-<!ENTITY a.brandon "Brandon Gillespie <email>brandon@FreeBSD.ORG</email>">
-
<!ENTITY a.bde "Bruce Evans <email>bde@FreeBSD.ORG</email>">
+<!ENTITY a.billf "Bill Fumerola <email>billf@FreeBSD.ORG</email>">
+
+<!ENTITY a.brandon "Brandon Gillespie <email>brandon@FreeBSD.ORG</email>">
+
<!ENTITY a.brian "Brian Somers <email>brian@FreeBSD.ORG</email>">
<!ENTITY a.cawimm "Charles A. Wimmer <email>cawimm@FreeBSD.ORG</email>">
@@ -88,6 +90,8 @@
<!ENTITY a.fenner "Bill Fenner <email>fenner@FreeBSD.ORG</email>">
+<!ENTITY a.flathill "Seiichirou Hiraoka <email>flathill@FreeBSD.ORG</email>">
+
<!ENTITY a.fsmp "Steve Passe <email>fsmp@FreeBSD.ORG</email>">
<!ENTITY a.gclarkii "Gary Clark II <email>gclarkii@FreeBSD.ORG</email>">
@@ -98,6 +102,8 @@
<!ENTITY a.gibbs "Justin T. Gibbs <email>gibbs@FreeBSD.ORG</email>">
+<!ENTITY a.mjacob "Matthew Jacob <email>mjacob@FreeBSD.ORG</email>">
+
<!ENTITY a.gj "Gary Jennejohn <email>gj@FreeBSD.ORG</email>">
<!ENTITY a.gpalmer "Gary Palmer <email>gpalmer@FreeBSD.ORG</email>">
@@ -218,6 +224,8 @@
<!ENTITY a.nectar "Jacques Vidrine <email>nectar@FreeBSD.ORG</email>">
+<!ENTITY a.nhibma "Nick Hibma <email>n_hibma@FreeBSD.ORG</email>">
+
<!ENTITY a.nik "Nik Clayton <email>nik@FreeBSD.ORG</email>">
<!ENTITY a.nsj "Nate Johnson <email>nsj@FreeBSD.ORG</email>">
@@ -258,6 +266,8 @@
<!ENTITY a.rse "Ralf S. Engelschall <email>rse@FreeBSD.ORG</email>">
+<!ENTITY a.sada "Kenji SADA <email>sada@FreeBSD.ORG</email>">
+
<!ENTITY a.scrappy "Marc G. Fournier <email>scrappy@FreeBSD.ORG</email>">
<!ENTITY a.se "Stefan Esser <email>se@FreeBSD.ORG</email>">
@@ -288,6 +298,8 @@
<!ENTITY a.torstenb "Torsten Blum <email>torstenb@FreeBSD.ORG</email>">
+<!ENTITY a.truckman "Don “Truck” Lewis <email>truckman@FreeBSD.ORG</email>">
+
<!ENTITY a.ugen "Ugen J.S.Antsilevich <email>ugen@FreeBSD.ORG</email>">
<!ENTITY a.uhclem "Frank Durda IV <email>uhclem@FreeBSD.ORG</email>">
@@ -296,6 +308,8 @@
<!ENTITY a.vanilla "Vanilla I. Shu <email>vanilla@FreeBSD.ORG</email>">
+<!ENTITY a.wes "Wes Peters <email>wes@FreeBSD.ORG</email>">
+
<!ENTITY a.whiteside "Don Whiteside <email>whiteside@acm.org</email>">
<!ENTITY a.wilko "Wilko Bulte <email>wilko@yedi.iaf.nl</email>">
diff --git a/en_US.ISO_8859-1/books/handbook/advanced-networking/chapter.sgml b/en_US.ISO_8859-1/books/handbook/advanced-networking/chapter.sgml
index 4fbe1987b1..4f00275b26 100644
--- a/en_US.ISO_8859-1/books/handbook/advanced-networking/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/advanced-networking/chapter.sgml
@@ -976,9 +976,7 @@ ISDN BRI line</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/authors.ent b/en_US.ISO_8859-1/books/handbook/authors.ent
index a8c95c2ac6..80e0daca31 100644
--- a/en_US.ISO_8859-1/books/handbook/authors.ent
+++ b/en_US.ISO_8859-1/books/handbook/authors.ent
@@ -7,7 +7,7 @@
Please keep this list in alphabetical order by entity names.
- $Id: authors.ent,v 1.3 1998-11-12 01:26:17 nik Exp $
+ $Id: authors.ent,v 1.4 1998-12-10 20:43:39 nik Exp $
-->
<!ENTITY a.abial "Andrzej Bialecki <email>abial@FreeBSD.ORG</email>">
@@ -30,10 +30,12 @@
<!ENTITY a.awebster "Andrew Webster <email>awebster@pubnix.net</email>">
-<!ENTITY a.brandon "Brandon Gillespie <email>brandon@FreeBSD.ORG</email>">
-
<!ENTITY a.bde "Bruce Evans <email>bde@FreeBSD.ORG</email>">
+<!ENTITY a.billf "Bill Fumerola <email>billf@FreeBSD.ORG</email>">
+
+<!ENTITY a.brandon "Brandon Gillespie <email>brandon@FreeBSD.ORG</email>">
+
<!ENTITY a.brian "Brian Somers <email>brian@FreeBSD.ORG</email>">
<!ENTITY a.cawimm "Charles A. Wimmer <email>cawimm@FreeBSD.ORG</email>">
@@ -88,6 +90,8 @@
<!ENTITY a.fenner "Bill Fenner <email>fenner@FreeBSD.ORG</email>">
+<!ENTITY a.flathill "Seiichirou Hiraoka <email>flathill@FreeBSD.ORG</email>">
+
<!ENTITY a.fsmp "Steve Passe <email>fsmp@FreeBSD.ORG</email>">
<!ENTITY a.gclarkii "Gary Clark II <email>gclarkii@FreeBSD.ORG</email>">
@@ -98,6 +102,8 @@
<!ENTITY a.gibbs "Justin T. Gibbs <email>gibbs@FreeBSD.ORG</email>">
+<!ENTITY a.mjacob "Matthew Jacob <email>mjacob@FreeBSD.ORG</email>">
+
<!ENTITY a.gj "Gary Jennejohn <email>gj@FreeBSD.ORG</email>">
<!ENTITY a.gpalmer "Gary Palmer <email>gpalmer@FreeBSD.ORG</email>">
@@ -218,6 +224,8 @@
<!ENTITY a.nectar "Jacques Vidrine <email>nectar@FreeBSD.ORG</email>">
+<!ENTITY a.nhibma "Nick Hibma <email>n_hibma@FreeBSD.ORG</email>">
+
<!ENTITY a.nik "Nik Clayton <email>nik@FreeBSD.ORG</email>">
<!ENTITY a.nsj "Nate Johnson <email>nsj@FreeBSD.ORG</email>">
@@ -258,6 +266,8 @@
<!ENTITY a.rse "Ralf S. Engelschall <email>rse@FreeBSD.ORG</email>">
+<!ENTITY a.sada "Kenji SADA <email>sada@FreeBSD.ORG</email>">
+
<!ENTITY a.scrappy "Marc G. Fournier <email>scrappy@FreeBSD.ORG</email>">
<!ENTITY a.se "Stefan Esser <email>se@FreeBSD.ORG</email>">
@@ -288,6 +298,8 @@
<!ENTITY a.torstenb "Torsten Blum <email>torstenb@FreeBSD.ORG</email>">
+<!ENTITY a.truckman "Don “Truck” Lewis <email>truckman@FreeBSD.ORG</email>">
+
<!ENTITY a.ugen "Ugen J.S.Antsilevich <email>ugen@FreeBSD.ORG</email>">
<!ENTITY a.uhclem "Frank Durda IV <email>uhclem@FreeBSD.ORG</email>">
@@ -296,6 +308,8 @@
<!ENTITY a.vanilla "Vanilla I. Shu <email>vanilla@FreeBSD.ORG</email>">
+<!ENTITY a.wes "Wes Peters <email>wes@FreeBSD.ORG</email>">
+
<!ENTITY a.whiteside "Don Whiteside <email>whiteside@acm.org</email>">
<!ENTITY a.wilko "Wilko Bulte <email>wilko@yedi.iaf.nl</email>">
diff --git a/en_US.ISO_8859-1/books/handbook/basics/chapter.sgml b/en_US.ISO_8859-1/books/handbook/basics/chapter.sgml
index 574ee8a3f7..761f1146f4 100644
--- a/en_US.ISO_8859-1/books/handbook/basics/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/basics/chapter.sgml
@@ -141,9 +141,7 @@
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/bibliography/chapter.sgml b/en_US.ISO_8859-1/books/handbook/bibliography/chapter.sgml
index 429b519caf..a549e0ca67 100644
--- a/en_US.ISO_8859-1/books/handbook/bibliography/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/bibliography/chapter.sgml
@@ -499,9 +499,7 @@ url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/misc/bsd-family
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/book.sgml b/en_US.ISO_8859-1/books/handbook/book.sgml
index 78ff7e72ca..a4c9c067df 100644
--- a/en_US.ISO_8859-1/books/handbook/book.sgml
+++ b/en_US.ISO_8859-1/books/handbook/book.sgml
@@ -3,7 +3,10 @@
<!ENTITY % authors SYSTEM "authors.ent"> %authors;
<!ENTITY % mailing-lists SYSTEM "mailing-lists.ent"> %mailing-lists;
-<!ENTITY rel.current CDATA "3.0">
+<!-- The currently released version of FreeBSD. This value is used to
+ create some links on web sites and such, so do NOT change it until
+ it's really release time -->
+<!ENTITY rel.current CDATA "2.2.8">
]>
<book>
@@ -103,8 +106,6 @@ url="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/docs/">FreeBSD FTP server</ulink> or one
mode: sgml
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/contrib/chapter.sgml b/en_US.ISO_8859-1/books/handbook/contrib/chapter.sgml
index c04d625c12..2dffa913a2 100644
--- a/en_US.ISO_8859-1/books/handbook/contrib/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/contrib/chapter.sgml
@@ -1,5 +1,4 @@
-
- <chapter id="contrib">
+<chapter id="contrib">
<title>Contributing to FreeBSD</title>
<para><emphasis>Contributed by &a.jkh;.</emphasis></para>
@@ -724,2529 +723,7 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</sect2>
- <sect2 id="porting">
- <title>Porting an existing piece of free software</title>
-
- <para><emphasis>Contributed by &a.jkh;, &a.gpalmer;, &a.asami; and
- &a.obrien;.<!-- <br> -->28 August 1996.</emphasis></para>
-
- <para>The porting of freely available software, while perhaps not as
- gratifying as developing your own from scratch, is still a vital
- part of FreeBSD's growth and of great usefulness to those who
- would not otherwise know where to turn for it. All ported
- software is organized into a carefully organized hierarchy known
- as “the ports collection”. The collection enables a new user to
- get a quick and complete overview of what is available for FreeBSD
- in an easy-to-compile form. It also saves considerable space by
- not actually containing the majority of the sources being ported,
- but merely those differences required for running under FreeBSD.</para>
-
- <para>What follows are some guidelines for creating a new port for
- FreeBSD. The bulk of the work is done by
- <filename>/usr/share/mk/bsd.port.mk</filename>, which all port
- Makefiles include. Please refer to that file for more details on
- the inner workings of the ports collection. Even if you don't
- hack Makefiles daily, it is well commented, and you will still
- gain much knowledge from it.</para>
-
-
- <sect3 id="porting-starting">
- <title>Before Starting the Port</title>
- <note>
- <para>Only a fraction of the overridable variables
- are mentioned in
- this document. Most (if not all) are documented at the start
- of <filename>bsd.port.mk</filename>. This file uses a
- non-standard tab setting. <command>Emacs</command> and
- <command>Vim</command> should recognize the setting on loading
- the file. <command>vi</command> or <command>ex</command> can
- be set to using the correct value by typing <literal>:set
- tabstop=4</literal> once the file has been loaded.</para>
- </note>
-
- <para>You may come across code that needs modifications or
- conditional compilation based upon what version of UNIX it is
- running under. If you need to make such changes to the code for
- conditional compilation, make sure you make the changes as
- general as possible so that we can back-port code to FreeBSD 1.x
- systems and cross-port to other BSD systems such as 4.4BSD from
- CSRG, BSD/386, 386BSD, NetBSD, and OpenBSD.</para>
-
- <para>The preferred way to tell 4.3BSD/Reno (1990) and newer
- versions of the BSD code apart is by using the
- <acronym>BSD</acronym> macro defined in
- <filename><sys/param.h></filename>. Hopefully that file
- is already included; if not, add the code:</para>
-
- <programlisting>
-#if (defined(__unix__) || defined(unix)) && !defined(USG)
-#include <sys/param.h>
-#endif</programlisting>
-
- <para>to the proper place in the <filename>.c</filename> file. We
- believe that every system that defines these to symbols has
- <filename>sys/param.h</filename>. If you find a system that
- doesn't, we would like to know. Please send mail to
- &a.ports;.</para>
-
- <para>Another way is to use the GNU Autoconf style of doing
- this:</para>
-
- <programlisting>
-#ifdef HAVE_SYS_PARAM_H
-#include <sys/param.h>
-#endif</programlisting>
-
- <para>Don't forget to add <literal>-DHAVE_SYS_PARAM_H</literal> to
- the <makevar>CFLAGS</makevar> in the Makefile for this
- method.</para>
-
- <para>Once you have <filename>sys/param.h</filename>
- included, you may use:</para>
-
- <programlisting>
-#if (defined(BSD) && (BSD >= 199103))</programlisting>
-
- <para>to detect if the code is being compiled on a 4.3 Net2 code
- base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD,
- BSD/386 1.1 and below).</para>
-
- <para>Use:</para>
-
- <programlisting>
-#if (defined(BSD) && (BSD >= 199306))</programlisting>
-
- <para>to detect if the code is being compiled on a 4.4 code base
- or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or
- above).</para>
-
- <para>The value of the BSD macro is 199506 for the 4.4BSD-Lite2
- code base. This is stated for informational purposes only. It
- should not be used to distinguish between version of FreeBSD
- based only on 4.4-Lite vs. versions that have merged in changes
- from 4.4-Lite2. The __FreeBSD__ macro should be used
- instead.</para>
-
- <para>Use sparingly:</para>
-
-
- <itemizedlist>
-
- <listitem>
- <para><literal>__FreeBSD__</literal> is defined in all
- versions of FreeBSD. Use it if the change you are making
- ONLY affects FreeBSD. Porting gotchas like the use of
- <literal>sys_errlist[]</literal> vs
- <function>strerror()</function> are Berkeleyisms, not
- FreeBSD changes.</para>
- </listitem>
-
- <listitem>
- <para>In FreeBSD 2.x, <literal>__FreeBSD__</literal> is
- defined to be <literal>2</literal>. In earlier
- versions, it is <literal>1</literal>. Later
- versions will bump it to match their major version number.</para>
- </listitem>
-
- <listitem>
- <para>If you need to tell the difference between a FreeBSD
- 1.x system and a FreeBSD 2.x or 3.x system, usually the
- right answer is to use the <acronym>BSD</acronym> macros
- described above. If there actually is a FreeBSD specific
- change (such as special shared library options when using
- <command>ld</command>) then it is OK to use
- <literal>__FreeBSD__</literal> and <literal>#if
- __FreeBSD__ > 1</literal> to detect a FreeBSD 2.x
- and later system. If you need more granularity in
- detecting FreeBSD systems since 2.0-RELEASE you can use
- the following:</para>
-
- <programlisting>
-#if __FreeBSD__ >= 2
-#include <osreldate.h>
-# if __FreeBSD_version >= 199504
- /* 2.0.5+ release specific code here */
-# endif
-#endif</programlisting>
-
- <informaltable frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Release</entry>
- <entry><literal>_FreeBSD_version</literal></entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>2.0-RELEASE</entry>
- <entry>119411</entry>
- </row>
-
- <row>
- <entry>2.1-currents</entry>
- <entry>199501, 199503</entry>
- </row>
-
- <row>
- <entry>2.0.5-RELEASE</entry>
- <entry>199504</entry>
- </row>
-
- <row>
- <entry>2.2-current before 2.1</entry>
- <entry>199508</entry>
- </row>
-
- <row>
- <entry>2.1.0-RELEASE</entry>
- <entry>199511</entry>
- </row>
-
- <row>
- <entry>2.2-current before 2.1.5</entry>
- <entry>199512</entry>
- </row>
-
- <row>
- <entry>2.1.5-RELEASE</entry>
- <entry>199607</entry>
- </row>
-
- <row>
- <entry>2.2-current before 2.1.6</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 (no change)</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after 2.2.1-RELEASE</entry>
- <entry>220000 (no change)</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after texinfo-3.9</entry>
- <entry>221001</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after top</entry>
- <entry>221002</entry>
- </row>
-
- <row>
- <entry>2.2.2-RELEASE</entry>
- <entry>222000</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after 2.2.2-RELEASE</entry>
- <entry>222001</entry>
- </row>
-
- <row>
- <entry>2.2.5-RELEASE</entry>
- <entry>225000</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after 2.2.5-RELEASE</entry>
- <entry>225001</entry>
- </row>
-
- <row>
- <entry>2.2-STABLE after ldconfig -R merge</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-STABLE after 2.2.7-RELEASE</entry>
- <entry>227001</entry>
- </row>
-
- <row>
- <entry>3.0-current before mount(2) change</entry>
- <entry>300000</entry>
- </row>
-
- <row>
- <entry>3.0-current as of November 1996</entry>
- <entry>300001</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </listitem>
- </itemizedlist>
-
- <note>
- <para>Note that 2.2-STABLE sometimes identifies itself as
- “2.2.5-STABLE” after the 2.2.5-RELEASE. The pattern used to
- be year followed by the month, but we decided to change it
- to a more straightforward major/minor system starting from
- 2.2. This is because the parallel development on several
- branches made it infeasible to classify the releases simply
- by their real release dates. If you are making a port now,
- you don't have to worry about old -current's; they are
- listed here just for your reference.</para>
- </note>
-
-
- <para>In the hundreds of ports that have been done, there have
- only been one or two cases where <literal>__FreeBSD__</literal>
- should have been used. Just because an earlier port screwed up
- and used it in the wrong place does not mean you should do so
- too.</para>
-
- </sect3>
-
- <sect3>
- <title>Quick Porting</title>
-
- <para>This section tells you how to do a quick port. In many
- cases, it is not enough, but we will see.</para>
-
- <para>First, get the original tarball and put it into <makevar>DISTDIR</makevar>, which defaults to
- <filename>/usr/ports/distfiles</filename>.</para>
-
- <note>
- <para>The following assumes that the software compiled
- out-of-the-box, i.e., there was absolutely no change required
- for the port to work on your FreeBSD box. If you needed to
- change something, you will have to refer to the next section
- too.</para>
- </note>
-
- <sect4>
- <title>Writing the <filename>Makefile</filename></title>
-
- <para>The minimal <filename>Makefile</filename> would
- look something like this:</para>
-
- <programlisting>
-# New ports collection makefile for: oneko
-# Version required: 1.1b
-# Date created: 5 December 1994
-# Whom: asami
-#
-# $Id$
-#
-
-DISTNAME= oneko-1.1b
-CATEGORIES= games
-MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
-
-MAINTAINER= asami@FreeBSD.ORG
-
-MAN1= oneko.1
-MANCOMPRESSED= yes
-USE_IMAKE= yes
-
-.include <bsd.port.mk></programlisting>
-
- <para>See if you can figure it out. Do not worry about the
- contents of the <literal>$Id$</literal>
- line, it will be filled in automatically by CVS when the port
- is imported to our main ports tree. You can find a more
- detailed example in the <link
- linkend="porting-samplem">sample Makefile</link>
- section.</para>
-
- </sect4>
-
- <sect4>
- <title>Writing the description files</title>
-
- <para>There are three required description files that are
- required for any port, whether they actually package or not.
- They are <filename>COMMENT</filename>,
- <filename>DESCR</filename>, and <filename>PLIST</filename>,
- and reside in the <filename>pkg</filename>
- subdirectory.</para>
-
-
- <sect5>
- <title><filename>COMMENT</filename></title>
-
- <para>This is the one-line description of the port.
- <emphasis>Please</emphasis> do not include the package name (or version
- number of the software) in the comment. Here is
- an example:</para>
-
- <programlisting>
-A cat chasing a mouse all over the screen.</programlisting>
-
- </sect5>
-
- <sect5>
- <title><filename>DESCR</filename></title>
-
- <para>This is a longer description of the port. One to a few
- paragraphs concisely explaining what the port does is
- sufficient.</para>
-
- <note>
- <para>This is <emphasis>not</emphasis> a manual or an
- in-depth description on how to use or compile the port!
- <emphasis>Please be careful if you are copying from the
- <filename>README</filename> or manpage</emphasis>; too often
- they are not a concise description of the port or are in an
- awkward format (e.g., manpages have justified spacing). If the
- ported software has an official WWW homepage, you should list
- it here.</para>
- </note>
-
- <para>It is recommended that you sign the name at the end of
- this file, as in:</para>
-
- <programlisting>
-This is a port of oneko, in which a cat chases a poor mouse all over
-the screen.
- :
-(etc.)
-
-http://www.oneko.org/
-
-- Satoshi
-asami@cs.berkeley.edu</programlisting>
-
- </sect5>
-
- <sect5>
- <title><filename>PLIST</filename></title>
-
- <para>This file lists all the files installed by the port. It
- is also called the `packing list' because the package is
- generated by packing the files listed here. The pathnames
- are relative to the installation prefix (usually
- <filename>/usr/local</filename> or
- <filename>/usr/X11R6</filename>). If you are using the
- <makevar>MAN<replaceable>n</replaceable></makevar> variables (as
- you should be), do not list any manpages here.</para>
-
- <para>Here is a small example:</para>
-
- <programlisting>
-bin/oneko
-lib/X11/app-defaults/Oneko
-lib/X11/oneko/cat1.xpm
-lib/X11/oneko/cat2.xpm
-lib/X11/oneko/mouse.xpm</programlisting>
-
- <para>Refer to the <citerefentry><refentrytitle>pkg_create</refentrytitle><manvolnum>1</manvolnum></citerefentry> man page
- for details on the packing list.</para>
-
- </sect5>
- </sect4>
-
- <sect4>
- <title>Creating the checksum file</title>
-
- <para>Just type <command>make makesum</command>.
- The ports make rules will automatically generate the file
- <filename>files/md5</filename>.</para>
-
- </sect4>
-
- <sect4>
- <title>Testing the port</title>
-
- <para>You should make sure that the port rules do exactly what
- you want it to do, including packaging up the port. Try doing
- <command>make install</command>, <command>make package</command> and then <command>make deinstall</command> and see if all the files
- and directories are correctly deleted. Then do a <command>pkg_add `make package-name`.tgz</command> and see
- if everything re-appears and works correctly. Then do another
- <command>make deinstall</command> and then
- <command>make reinstall; make package</command>
- to make sure you haven't included in the packing list any
- files that are not installed by your port.</para>
-
- </sect4>
-
- <sect4 id="porting-submitting">
- <title>Submitting the port</title>
-
- <para>First, make sure you have read the <link
- linkend="porting-dads">Do's and Dont's</link> section.</para>
-
- <para>Now that you are happy with your port, the only thing
- remaining is to put it in the main FreeBSD ports tree and make
- everybody else happy about it too. We do not need your
- <filename>work</filename> directory or the
- <filename>pkgname.tgz</filename> package, so delete them
- now. Next, simply include the output of <command>shar `find
- port_dir`</command> in a bug report and send it with the
- <citerefentry>
- <refentrytitle>send-pr</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> program. If the uncompressed port is larger than
- 20KB, you should compress it into a tarfile and use <citerefentry>
- <refentrytitle>uuencode</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> before including it in the bug report (uuencoded
- tarfiles are acceptable even if the bug report is smaller than
- 20KB but are not preferred). Be sure to classify the bug report as
- category <literal>ports</literal> and class
- <literal>change-request</literal>.</para>
-
- <para>One more time, <emphasis>do not include the original source
- distfile, the <filename>work</filename> directory, or the
- package you built with <command>make
- package</command></emphasis>.</para>
-
- <para>See <link linkend="contrib-general">Bug Reports and General
- Commentary</link> for more information.</para>
-
- <para>We will look at your port,
- get back to you if necessary, and put it in the
- tree. Your name will also appear in the list of “Additional
- FreeBSD contributors” on the FreeBSD Handbook and other files.
- Isn't that great?!? <!-- smiley -->:)</para>
-
- </sect4>
- </sect3>
-
- <sect3>
- <title>Slow Porting</title>
-
- <para>Ok, so it was not that simple, and the port required some
- modifications to get it to work. In this section, we will
- explain, step by step, how to modify it to get it to work with
- the ports paradigm.</para>
-
-
- <sect4>
- <title>How things work</title>
-
- <para>First, this is the sequence of events which occurs when
- the user first types <command>make</command> in
- your port's directory, and you may find that having
- <filename>bsd.port.mk</filename> in another window while you
- read this really helps to understand it.</para>
-
- <para>But do not worry if you do not really understand what
- <filename>bsd.port.mk</filename> is doing, not many people
- do... <!-- smiley --><emphasis>:></emphasis></para>
-
-
- <procedure>
-
- <step>
- <para>The <maketarget>fetch</maketarget> target is run. The <maketarget>fetch</maketarget> target is
- responsible for making sure that the tarball exists
- locally in <makevar>DISTDIR</makevar>.
- If <maketarget>fetch</maketarget> cannot find the required files in <makevar>DISTDIR</makevar> it will look up the
- URL <makevar>MASTER_SITES</makevar>,
- which is set in the Makefile, as well as our main ftp
- site at <ulink
- URL="ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/">ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/,</ulink> where we put sanctioned distfiles as backup. It will then attempt to fetch the named distribution file with <makevar>FETCH</makevar>, assuming that the requesting site has direct access to the Internet. If that succeeds, it will save the file in <makevar>DISTDIR</makevar> for future use and proceed.</para>
- </step>
-
- <step>
- <para>The <maketarget>extract</maketarget> target is run. It looks for your port's
- distribution file in <makevar>DISTDIR</makevar> (typically a gzip'd
- tarball) and unpacks it into a temporary subdirectory
- specified by <makevar>WRKDIR</makevar>
- (defaults to <filename>work</filename>).</para>
- </step>
-
- <step>
- <para>The <maketarget>patch</maketarget> target is run. First, any patches defined
- in <makevar>PATCHFILES</makevar> are
- applied. Second, if any patches are found in <makevar>PATCHDIR</makevar> (defaults to the
- <filename>patches</filename> subdirectory), they are
- applied at this time in alphabetical order.</para>
- </step>
-
- <step>
- <para>The <maketarget>configure</maketarget> target is run. This can do any one of
- many different things.</para>
-
- <orderedlist>
-
- <listitem>
- <para>If it exists,
- <filename>scripts/configure</filename> is run.</para>
- </listitem>
-
- <listitem>
- <para>If <makevar>HAS_CONFIGURE</makevar> or
- <makevar>GNU_CONFIGURE</makevar>
- is set,
- <filename><makevar>WRKSRC</makevar>/configure</filename> is
- run.</para>
- </listitem>
-
- <listitem>
- <para>If <makevar>USE_IMAKE</makevar> is set,
- <makevar>XMKMF</makevar>
- (default: <command>xmkmf
- -a</command>) is run.</para>
- </listitem>
-
- </orderedlist>
-
- </step>
-
- <step>
- <para>The <maketarget>build</maketarget> target is run. This is responsible for
- descending into the ports' private working directory
- (<makevar>WRKSRC</makevar>) and
- building it. If <makevar>USE_GMAKE</makevar> is set, GNU
- <command>make</command> will be used,
- otherwise the system <command>make</command>
- will be used.</para>
- </step>
-
- </procedure>
-
-
- <para>The above are the default actions. In addition, you can
- define targets <maketarget>pre-<replaceable>something</replaceable></maketarget> or <maketarget>post-<replaceable>something</replaceable></maketarget>, or put scripts
- with those names, in the <filename>scripts</filename>
- subdirectory, and they will be run before or after the default
- actions are done.</para>
-
- <para>For example, if you have a <maketarget>post-extract</maketarget> target defined in your
- Makefile, and a file <filename>pre-build</filename> in the
- <filename>scripts</filename> subdirectory, the
- <maketarget>post-extract</maketarget> target will be
- called after the regular extraction actions, and the
- <filename>pre-build</filename> script will be executed before
- the default build rules are done. It is recommended that you
- use <filename>Makefile</filename> targets if the actions are
- simple enough, because it will be easier for someone to figure
- out what kind of non-default action the port requires.</para>
-
- <para>The default actions are done by the
- <filename>bsd.port.mk</filename> targets <maketarget>do-<replaceable>something</replaceable></maketarget>. For example, the
- commands to extract a port are in the target <maketarget>do-extract</maketarget>. If you are not happy with
- the default target, you can fix it by redefining the
- <maketarget>do-<replaceable>something</replaceable></maketarget> target in
- your <filename>Makefile</filename>.</para>
-
- <note>
- <para>The “main” targets (e.g., <maketarget>extract</maketarget>, <maketarget>configure</maketarget>, etc.) do nothing more than
- make sure all the stages up to that one is completed and
- call the real targets or scripts, and they are not intended
- to be changed. If you want to fix the extraction, fix
- <maketarget>do-extract</maketarget>, but never ever
- touch <maketarget>extract</maketarget>!</para>
- </note>
-
- <para>Now that you understand what goes on when the user types
- <command>make</command>, let us go through the
- recommended steps to create the perfect port.</para>
-
- </sect4>
-
- <sect4>
- <title>Getting the original sources</title>
-
- <para>Get the original sources (normally) as a compressed
- tarball (<filename><replaceable>foo</replaceable>.tar.gz</filename> or
- <filename><replaceable>foo</replaceable>.tar.Z</filename>) and copy it into
- <makevar>DISTDIR</makevar>. Always use
- <emphasis>mainstream</emphasis> sources when and where you
- can.</para>
-
- <para>If you cannot find a ftp/http site that is well-connected
- to the net, or can only find sites that have irritatingly
- non-standard formats, you might want to put a copy on a
- reliable http or ftp server that you control. If you are a FreeBSD
- committer, your <filename>public_html</filename> directory on
- <hostid>freefall</hostid> is ideal. Make sure you set
- <makevar>MASTER_SITE</makevar> to reflect your choice. If you
- cannot find somewhere convenient and reliable to put the distfile,
- we can “house” it ourselves by putting
- it on <filename>ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/LOCAL_PORTS/</filename> as the last resort. Please refer to this
- location as <makevar>MASTER_SITE_LOCAL</makevar>. Send mail to
- the &a.ports;if you are not sure what to do.</para>
-
- <para>If your port requires some additional `patches' that are
- available on the Internet, fetch them too and put them in
- <makevar>DISTDIR</makevar>. Do not worry if
- they come from site other than where you got the main source
- tarball, we have a way to handle these situations (see the
- description of <link
- linkend="porting-patchfiles">PATCHFILES</link> below).</para>
-
- </sect4>
-
- <sect4>
- <title>Modifying the port</title>
-
- <para>Unpack a copy of the tarball in a private directory and
- make whatever changes are necessary to get the port to compile
- properly under the current version of FreeBSD. Keep
- <emphasis>careful track</emphasis> of everything you do, as
- you will be automating the process shortly. Everything,
- including the deletion, addition or modification of files
- should be doable using an automated script or patch file when
- your port is finished.</para>
-
- <para>If your port requires significant user
- interaction/customization to compile or install, you should
- take a look at one of Larry Wall's classic <application>Configure</application> scripts
- and perhaps do something similar yourself. The goal of the
- new ports collection is to make each port as “plug-and-play”
- as possible for the end-user while using a minimum of disk
- space.</para>
-
- <note>
- <para>Unless explicitly stated, patch files, scripts, and
- other files you have created and contributed to the FreeBSD
- ports collection are assumed to be covered by the standard
- BSD copyright conditions.</para>
- </note>
- </sect4>
-
- <sect4>
- <title>Patching</title>
-
- <para>In the preparation of the port, files that have been added
- or changed can be picked up with a recursive diff for later
- feeding to patch. Each set of patches you wish to apply
- should be collected into a file named
- <filename>patch-<replaceable>xx</replaceable></filename> where
- <replaceable>xx</replaceable> denotes the sequence in which
- the patches will be applied — these are done in
- <emphasis>alphabetical order</emphasis>, thus
- <literal>aa</literal> first, <literal>ab</literal> second and so on. These files
- should be stored in <makevar>PATCHDIR</makevar>, from where they will be
- automatically applied. All patches should be relative to
- <makevar>WRKSRC</makevar> (generally the
- directory your port's tarball unpacks itself into, that being
- where the build is done). To make fixes and upgrades easier
- you should avoid having more than one patch fix the same file
- (e.g., patch-aa and patch-ab both changing <makevar>WRKSRC</makevar>/foobar.c).</para>
-
- </sect4>
-
- <sect4>
- <title>Configuring</title>
-
- <para>Include any additional customization commands to your
- <filename>configure</filename> script and save it in the
- <filename>scripts</filename> subdirectory. As mentioned
- above, you can also do this as <filename>Makefile</filename>
- targets and/or scripts with the name
- <filename>pre-configure</filename> or
- <filename>post-configure</filename>.</para>
-
- </sect4>
-
- <sect4>
- <title>Handling user input</title>
-
- <para>If your port requires user input to build, configure or
- install, then set <makevar>IS_INTERACTIVE</makevar> in your
- Makefile. This will allow “overnight builds” to skip your port
- if the user sets the variable <envar>BATCH</envar> in his
- environment (and if the user sets the variable
- <envar>INTERACTIVE</envar>, then <emphasis>only</emphasis>
- those ports requiring interaction are built).</para>
-
- </sect4>
- </sect3>
-
- <sect3>
- <title>Configuring the Makefile</title>
-
- <para>Configuring the Makefile is pretty simple, and again we
- suggest that you look at existing examples before starting.
- Also, there is a <link linkend="porting-samplem">sample
- Makefile</link> in this handbook, so take a look and please follow
- the ordering of variables and sections in that template to make
- your port easier for others to read.</para>
-
- <para>Now, consider the following problems in sequence as you
- design your new Makefile:</para>
-
-
- <sect4>
- <title>The original source</title>
-
- <para>Does it live in <makevar>DISTDIR</makevar> as a standard gzip'd
- tarball? If so, you can go on to the next step. If not, you
- should look at overriding any of the <makevar>EXTRACT_CMD</makevar>, <makevar>EXTRACT_BEFORE_ARGS</makevar>, <makevar>EXTRACT_AFTER_ARGS</makevar>, <makevar>EXTRACT_SUFX</makevar>, or <makevar>DISTFILES</makevar> variables, depending on
- how alien a format your port's distribution file is. (The
- most common case is <literal>EXTRACT_SUFX=.tar.Z</literal>,
- when the tarball is condensed by regular compress, not
- gzip.)</para>
-
- <para>In the worst case, you can simply create your own
- <maketarget>do-extract</maketarget> target to override
- the default, though this should be rarely, if ever,
- necessary.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>DISTNAME</makevar></title>
-
- <para>You should set <makevar>DISTNAME</makevar> to be the base name of
- your port. The default rules expect the distribution file
- list (<makevar>DISTFILES</makevar>) to be
- named <makevar>DISTNAME</makevar><makevar>EXTRACT_SUFX</makevar> by
- default which, if it is a normal tarball, is going to be
- something like <literal>foozolix-1.0.tar.gz</literal> for a setting of
- <programlisting>
-DISTNAME=foozolix-1.0</programlisting>.</para>
-
- <para>The default rules also expect the tarball(s) to extract
- into a subdirectory called
- <filename>work/<makevar>DISTNAME</makevar></filename>, e.g. <filename>work/foozolix-1.0/</filename>.</para>
-
- <para>All this behavior can be overridden, of course; it simply
- represents the most common time-saving defaults. For a port
- requiring multiple distribution files, simply set <makevar>DISTFILES</makevar> explicitly. If only a
- subset of <makevar>DISTFILES</makevar> are
- actual extractable archives, then set them up in <makevar>EXTRACT_ONLY</makevar>, which will override
- the <makevar>DISTFILES</makevar> list when
- it comes to extraction, and the rest will be just left in
- <makevar>DISTDIR</makevar> for later
- use.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>CATEGORIES</makevar></title>
-
- <para>When a package is created, it is put under
- <filename>/usr/ports/packages/All</filename> and links are
- made from one or more subdirectories of
- <filename>/usr/ports/packages</filename>. The names of these
- subdirectories are specified by the variable <makevar>CATEGORIES</makevar>. It is intended to
- make life easier for the user when he is wading through the
- pile of packages on the ftp site or the CD-ROM. Please take a
- look at the existing categories (you can find them in <ulink
- URL="http://www.freebsd.org/ports/">the ports
- page</ulink>) and pick the ones that are suitable for your
- port. If your port truly belongs to something that is
- different from all the existing ones, you can even create a
- new category name.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>MASTER_SITES</makevar></title>
-
- <para>Record the directory part of the ftp/http-URL pointing at
- the original tarball in <makevar>MASTER_SITES</makevar>. Do not forget the
- trailing slash (<filename>/</filename>)!</para>
-
- <para>The <command>make</command> macros will try to use this specification for
- grabbing the distribution file with <makevar>FETCH</makevar> if they cannot find it
- already on the system.</para>
-
- <para>It is recommended that you put multiple sites on this
- list, preferably from different continents. This will
- safeguard against wide-area network problems, and we are even
- planning to add support for automatically determining the
- closest master site and fetching from there!</para>
-
- <para>If the original tarball is part of one of the following
- popular archives: X-contrib, GNU, Perl CPAN, TeX CTAN, or
- Linux Sunsite, you refer to those sites in an easy compact
- form using <makevar>MASTER_SITE_XCONTRIB</makevar>, <makevar>MASTER_SITE_GNU</makevar>,
- <makevar>MASTER_SITE_PERL_CPAN</makevar>, <makevar>MASTER_SITE_TEX_CTAN</makevar>, and
- <makevar>MASTER_SITE_SUNSITE</makevar>. Simply set <makevar>MASTER_SITE_SUBDIR</makevar> to the
- path with in the archive. Here is an example:</para>
-
- <programlisting>
-MASTER_SITES= ${MASTER_SITE_XCONTRIB}
-MASTER_SITE_SUBDIR= applications</programlisting>
-
- <para>The user can also set the <makevar>MASTER_SITE_*</makevar> variables in
- <filename>/etc/make.conf</filename> to override our choices,
- and use their favorite mirrors of these popular archives
- instead.</para>
-
- </sect4>
-
- <sect4 id="porting-patchfiles">
- <title><makevar>PATCHFILES</makevar></title>
-
- <para>If your port requires some additional patches that are
- available by ftp or http, set <makevar>PATCHFILES</makevar> to the names of the
- files and <makevar>PATCH_SITES</makevar> to
- the URL of the directory that contains them (the format is the
- same as <makevar>MASTER_SITES</makevar>).</para>
-
- <para>If the patch is not relative to the top of the source tree
- (i.e., <makevar>WKRSRC</makevar>) because it
- contains some extra pathnames, set <makevar>PATCH_DIST_STRIP</makevar> accordingly.
- For instance, if all the pathnames in the patch has an extra
- <literal>foozolix-1.0/</literal> in front of the
- filenames, then set
- <literal>PATCH_DIST_STRIP=-p1</literal>.</para>
-
- <para>Do not worry if the patches are compressed, they will be
- decompressed automatically if the filenames end with
- <filename>.gz</filename> or
- <filename>.Z</filename>.</para>
-
- <para>If the patch is distributed with some other files, such as
- documentation, in a gzip'd tarball, you can't just use
- <makevar>PATCHFILES</makevar>. If that is
- the case, add the name and the location of the patch tarball
- to <makevar>DISTFILES</makevar> and
- <makevar>MASTER_SITES</makevar>. Then, from
- the <maketarget>pre-patch</maketarget> target, apply the
- patch either by running the patch command from there, or
- copying the patch file into the <makevar>PATCHDIR</makevar> directory and calling it
- <filename>patch-<replaceable>xx</replaceable></filename>.</para>
-
- <note>
- <para>Note the tarball will have been extracted alongside the
- regular source by then, so there is no need to explicitly
- extract it if it is a regular gzip'd or compress'd tarball.
- If you do the latter, take extra care not to overwrite
- something that already exists in that directory. Also do
- not forget to add a command to remove the copied patch in
- the <maketarget>pre-clean</maketarget> target.</para>
- </note>
-
- </sect4>
-
- <sect4>
- <title><makevar>MAINTAINER</makevar></title>
-
- <para>Set your mail-address here. Please. <!-- smiley --><emphasis>:)</emphasis></para>
-
- <para>For detailed description of the responsibility of
- maintainers, refer to <link
- linkend="policies-maintainer">MAINTAINER
- on Makefiles</link> section.</para>
-
- </sect4>
-
- <sect4>
- <title>Dependencies</title>
-
- <para>Many ports depend on other ports. There are five
- variables that you can use to ensure that all the required
- bits will be on the user's machine.</para>
-
-
- <sect5>
- <title><makevar>LIB_DEPENDS</makevar></title>
-
- <para>This variable specifies the shared libraries this port
- depends on. It is a list of <replaceable>lib</replaceable>:<replaceable>dir</replaceable> pairs where
- <replaceable>lib</replaceable> is the name of the shared library,
- and <replaceable>dir</replaceable> is the directory in which to
- find it in case it is not available. For example,
-
- <programlisting>
-LIB_DEPENDS= jpeg\\.6\\.:${PORTSDIR}/graphics/jpeg</programlisting>
-
- will check for a shared jpeg library with
- major version 6, and descend into the
- <filename>graphics/jpeg</filename> subdirectory of your
- ports tree to build and install it if it is not
- found.</para>
-
- <note>
- <para>The <replaceable>lib</replaceable> part is just an argument
- given to <command>ldconfig -r | grep</command>, so
- periods should be escaped by two backslashes like in the
- example above.</para>
- </note>
-
- <para>The dependency is checked from within the <maketarget>extract</maketarget> target. Also, the name of the
- dependency is put in to the package so that
- <command>pkg_add</command> will automatically install it if it
- is not on the user's system.</para>
-
- </sect5>
-
- <sect5>
- <title><makevar>RUN_DEPENDS</makevar></title>
-
- <para>This variable specifies executables or files this port
- depends on during run-time. It is a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable> pairs where
- <replaceable>path</replaceable> is the name of the executable or
- file, and <replaceable>dir</replaceable> is the directory in which
- to find it in case it is not available. If
- <replaceable>path</replaceable> starts with a slash
- (<literal>/</literal>), it is treated as a file and its
- existence is tested with <command>test -e</command>;
- otherwise, it is assumed to be an executable, and
- <command>which -s</command> is used to determine if the
- program exists in the user's search path.</para>
-
- <para>For example,
-
- <programlisting>
-RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \
- wish:${PORTSDIR}/x11/tk</programlisting>
-
- will check if the file
- <filename>/usr/local/etc/innd</filename> exists, and build
- and install it from the <filename>news/inn</filename>
- subdirectory of the ports tree if it is not found. It will
- also see if an executable called <command>wish</command> is in your search path, and
- descend into the <filename>x11/tk</filename> subdirectory of
- your ports tree to build and install it if it is not
- found.</para>
-
- <note>
- <para>In this case, <command>innd</command> is actually an
- executable; if an executable is in a place that is not
- expected to be in a normal user's search path, you should
- use the full pathname.</para>
- </note>
-
- <para>The dependency is checked from within the <maketarget>install</maketarget> target. Also, the name of the
- dependency is put in to the package so that
- <command>pkg_add</command> will automatically install it if it
- is not on the user's system.</para>
-
- </sect5>
-
- <sect5>
- <title><makevar>BUILD_DEPENDS</makevar></title>
-
- <para>This variable specifies executables or files this port
- requires to build. Like <makevar>RUN_DEPENDS</makevar>, it is
- a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable> pairs.
- For example,
-
- <programlisting>
-BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>
-
- will check for an executable called
- <command>unzip</command>, and descend into the
- <filename>archivers/unzip</filename> subdirectory of your
- ports tree to build and install it if it is not
- found.</para>
-
- <note>
- <para>“build” here means everything from extracting to
- compilation. The dependency is checked from within the
- <maketarget>extract</maketarget> target.</para>
- </note>
- </sect5>
-
- <sect5>
- <title><makevar>FETCH_DEPENDS</makevar></title>
-
- <para>This variable specifies executables or files this port
- requires to fetch. Like the previous two, it is a list of
- <replaceable>path</replaceable>:<replaceable>dir</replaceable> pairs. For
- example,
-
- <programlisting>
-FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting>
-
- will check for an executable called
- <command>ncftp2</command>, and descend into the
- <filename>net/ncftp2</filename> subdirectory of your ports
- tree to build and install it if it is not found.</para>
-
- <para>The dependency is checked from within the <maketarget>fetch</maketarget> target.</para>
-
- </sect5>
-
- <sect5>
- <title><makevar>DEPENDS</makevar></title>
-
- <para>If there is a dependency that does not fall into either
- of the above four categories, or your port requires to have
- the source of the other port extracted (i.e., having them
- installed is not enough), then use this variable. This is
- just a list of directories, as there is nothing to check,
- unlike the previous four.</para>
-
- </sect5>
- </sect4>
-
- <sect4>
- <title>Building mechanisms</title>
-
- <para>If your package uses GNU <command>make</command>, set
- <literal>USE_GMAKE=yes</literal>. If your package uses GNU
- <command>configure</command>, set
- <literal>GNU_CONFIGURE=yes</literal>. If you want to give
- some extra arguments to GNU <command>configure</command> (other than the default
- <literal>--prefix=${PREFIX}</literal>), set those extra
- arguments in <makevar>CONFIGURE_ARGS</makevar>.</para>
-
- <para>If your package is an X application that creates
- <filename>Makefile</filename>s from
- <filename>Imakefile</filename>s using <command>imake</command>, then set
- <literal>USE_IMAKE=yes</literal>. This will cause the
- configure stage to automatically do an <command>xmkmf
- -a</command>. If the <option>-a</option> flag is a
- problem for your port, set
- <literal>XMKMF=xmkmf</literal>.</para>
-
- <para>If your port's source <filename>Makefile</filename> has
- something else than <maketarget>all</maketarget> as the
- main build target, set <makevar>ALL_TARGET</makevar> accordingly. Same
- goes for <maketarget>install</maketarget> and <makevar>INSTALL_TARGET</makevar>.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>NO_INSTALL_MANPAGES</makevar></title>
-
- <para>If the port uses <command>imake</command> but does not understand the
- <filename>install.man</filename> target,
- <literal>NO_INSTALL_MANPAGES=yes</literal> should be set.
- In addition, the author of the original port should be shot.
- <!-- smiley --><emphasis>:></emphasis></para>
-
- </sect4>
- </sect3>
-
- <sect3>
- <title>Ports that require Motif</title>
-
- <para>There are many programs that require a Motif library
- (available from several commercial vendors, while there is (at
- least) one effort to create a free clone) to compile. Since it
- is a popular toolkit and their licenses usually permit
- redistribution of statically linked binaries, we have made
- special provisions for handling ports that require Motif in a
- way that we can easily compile binaries linked either
- dynamically or statically.</para>
-
-
- <sect4>
- <title><makevar>REQUIRES_MOTIF</makevar></title>
-
- <para>If your port requires Motif, define this variable in the
- Makefile. This will prevent people who don't own a copy of
- Motif from even attempting to build it.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>MOTIFLIB</makevar></title>
-
- <para>This variable will be set by
- <filename>bsd.port.mk</filename> to be the appropriate
- reference to the Motif library. Please patch the source to
- use this wherever the Motif library is referenced in the
- Makefile or Imakefile.</para>
-
- <para>There are two common cases:</para>
-
- <orderedlist>
-
- <listitem>
- <para>If the port refers to the Motif library as
- <option>-lXm</option> in its Makefile or Imakefile,
- simply substitute <makevar>MOTIFLIB</makevar> for it.</para>
- </listitem>
-
- <listitem>
- <para>If the port uses <literal>XmClientLibs</literal> in its Imakefile,
- change it to <literal>${MOTIFLIB}
- ${XTOOLLIB} ${XLIB}</literal>.</para>
- </listitem>
-
- </orderedlist>
-
- <note>
- <para><makevar>MOTIFLIB</makevar> (usually)
- expands to <literal>-L/usr/X11R6/lib -lXm</literal> or
- <literal>/usr/X11R6/lib/libXm.a</literal>, so there is
- no need to add <option>-L</option> or
- <option>-l</option> in front.</para>
- </note>
- </sect4>
- </sect3>
-
- <sect3>
- <title>ELF support</title>
-
- <para>Since FreeBSD is moving to ELF from 3.0-release onwards,
- 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 that there will
- be one more release (2.2.8) from the 2.2 branch. 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 awhile for reference
- in case you have come across some old port you wish to
- upgrade.</para>
-
- <sect4>
- <title>Moving a.out libraries out of the way</title>
-
- <para>A.out libraries should be moved out of
- <filename>/usr/local/lib</filename> and similar to an
- <filename>aout</filename> subdirectory. (If you don't move them
- out of the way, ELF ports will happily overwrite a.out libraries.)
- The <maketarget>move-aout-libs</maketarget> target in the -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>
- </sect4>
-
- <sect4>
- <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>
- </sect4>
-
- <sect4>
- <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's always going to be
- <literal>aout</literal> in -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>
- </sect4>
-
- <sect4>
- <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 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>PLIST</filename> too, and it won't 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>
- </sect4>
-
- <sect4>
- <title><makevar>LIB_DEPENDS</makevar></title>
-
- <para>All port Makefiles 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>
- </sect4>
-
- <sect4>
- <title><filename>PLIST</filename></title>
-
- <para><filename>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>PLIST</filename> mentioned in the previous
- paragraph.</para>
- </sect4>
-
- <sect4>
- <title><literal>ldconfig</literal></title>
-
- <para>The <literal>ldconfig/ line in Makefiles should read:</literal></para>
-
- <programlisting>
-${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....</programlisting>
-
- <para>In <filename>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>
- </sect4>
- </sect3>
-
- <sect3>
- <title>Info files</title>
-
- <para>The new version of texinfo (included in 2.2.2-RELEASE and
- onwards) contains a utility called <command>install-info</command> to add and delete entries to
- the <filename>dir</filename> file. If your port installs any
- info documents, please follow these instructions so your
- port/package will correctly update the user's
- <filename>${PREFIX}/info/dir</filename> file. (Sorry for
- the length of this section, but it is imperative to weave all
- the info files together. If done correctly, it will produce a
- <emphasis>beautiful</emphasis> listing, so please bear with me!
- <!-- smiley --><emphasis>:)</emphasis></para>
-
- <para>First, this is what you (as a porter) need to know:</para>
-
- <informalexample>
- <screen>&prompt.user; <userinput>install-info --help</userinput>
-install-info [OPTION]... [INFO-FILE [DIR-FILE]]
- Install INFO-FILE in the Info directory file DIR-FILE.
-
-Options:
---delete Delete existing entries in INFO-FILE;
- don't insert any new entries.
- :
---entry=TEXT Insert TEXT as an Info directory entry.
- :
---section=SEC Put this file's entries in section SEC of the directory. :</screen>
- </informalexample>
-
- <note>
- <para>This program will not actually
- <emphasis>install</emphasis> info files; it merely inserts or
- deletes entries in the <filename>dir</filename> file.</para>
- </note>
-
- <para>Here's a seven-step procedure to convert ports to use
- <command>install-info</command>. I will use
- <filename>editors/emacs</filename> as an example.</para>
-
- <procedure>
- <step>
- <para>Look at the texinfo sources and make a patch to insert
- <literal>@dircategory</literal> and <literal>@direntry</literal>
- statements to files that don't have them. This is part of
- my patch:</para>
-
- <programlisting>
---- ./man/vip.texi.org Fri Jun 16 15:31:11 1995
-+++ ./man/vip.texi Tue May 20 01:28:33 1997
-@@ -2,6 +2,10 @@
-
- @setfilename ../info/vip
- @settitle VIP
-+@dircategory The Emacs editor and associated tools
-+@direntry
-+* VIP: (vip). A VI-emulation for Emacs.
-+@end direntry
-
- @iftex
- @finalout
- :</programlisting>
-
- <para>The format should be self-explanatory. Many authors
- leave a <filename>dir</filename> file in the source tree
- that contains all the entries you need, so look around
- before you try to write your own. Also, make sure you
- look into related ports and make the section names and
- entry indentations consistent (we recommend that all entry
- text start at the 4th tab stop).</para>
-
- <note>
- <para>Note that you can put only one info entry per file
- because of a bug in <command>install-info
- --delete</command> that deletes only the first entry
- if you specify multiple entries in the
- <email>@direntry</email> section.</para>
- </note>
-
- <para>You can give the <literal>dir</literal>
- entries to <command>install-info</command> as
- arguments (<option>--section</option> and
- <option>--entry</option>) instead of patching the texinfo
- sources. I do not think this is a good idea for ports
- because you need to duplicate the same information in
- <emphasis>three</emphasis> places
- (<filename>Makefile</filename> and
- <literal>@exec</literal>/<literal>@unexec</literal> of
- <filename>PLIST</filename>; see below). However, if you
- have a Japanese (or other multibyte encoding) info files,
- you will have to use the extra arguments to <command>install-info</command> because <command>makeinfo</command> can't handle those texinfo
- sources. (See <filename>Makefile</filename> and
- <filename>PLIST</filename> of
- <filename>japanese/skk</filename> for examples on how to
- do this).</para>
- </step>
-
- <step>
- <para>Go back to the port directory and do a <command>make clean; make</command> and verify that
- the info files are regenerated from the texinfo sources.
- Since the texinfo sources are newer than the info files,
- they should be rebuilt when you type <command>make</command>; but many
- <filename>Makefile</filename>s don't include correct
- dependencies for info files. In <command>emacs</command>' case, I had to
- patch the main <filename>Makefile.in</filename> so it will
- descend into the <filename>man</filename>
- subdirectory to rebuild the info pages.</para>
-
- <programlisting>
---- ./Makefile.in.org Mon Aug 19 21:12:19 1996
-+++ ./Makefile.in Tue Apr 15 00:15:28 1997
-@@ -184,7 +184,7 @@
- # Subdirectories to make recursively. `lisp' is not included
- # because the compiled lisp files are part of the distribution
- # and you cannot remake them without installing Emacs first.
--SUBDIR = lib-src src
-+SUBDIR = lib-src src man
-
- # The makefiles of the directories in $SUBDIR.
- SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile lwlib/Makefile
---- ./man/Makefile.in.org Thu Jun 27 15:27:19 1996
-+++ ./man/Makefile.in Tue Apr 15 00:29:52 1997
-@@ -66,6 +66,7 @@
- ${srcdir}/gnu1.texi \
- ${srcdir}/glossary.texi
-
-+all: info
- info: $(INFO_TARGETS)
-
- dvi: $(DVI_TARGETS)</programlisting>
-
- <para>The second hunk was necessary because the default
- target in the <filename>man</filename> subdir is called
- <maketarget>info</maketarget>, while the main
- <filename>Makefile</filename> wants to call <maketarget>all</maketarget>. I also deleted the installation
- of the <filename>info</filename> info file
- because we already have one with the same name in
- <filename>/usr/share/info</filename> (that patch is not
- shown here).</para>
- </step>
-
- <step>
- <para>If there is a place in the
- <filename>Makefile</filename> that is installing the
- <filename>dir</filename> file, delete it. Your
- port may not be doing it. Also, remove any commands that
- are otherwise mucking around with the
- <filename>dir</filename> file.</para>
-
- <programlisting>
---- ./Makefile.in.org Mon Aug 19 21:12:19 1996
-+++ ./Makefile.in Mon Apr 14 23:38:07 1997
-@@ -368,14 +368,8 @@
- if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \
- then \
- (cd ${infodir}; \
-- if [ -f dir ]; then \
-- if [ ! -f dir.old ]; then mv -f dir dir.old; \
-- else mv -f dir dir.bak; fi; \
-- fi; \
- cd ${srcdir}/info ; \
-- (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir); \
-- (cd $${thisdir}; chmod a+r ${infodir}/dir); \
- for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \
- (cd $${thisdir}; \
- ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \
- chmod a+r ${infodir}/$$f); \</programlisting>
- </step>
-
- <step>
- <para>(This step is only necessary if you are modifying an
- existing port.) Take a look at
- <filename>pkg/PLIST</filename> and delete anything that is
- trying to patch up <filename>info/dir</filename>. They
- may be in <filename>pkg/INSTALL</filename> or some other
- file, so search extensively.</para>
-
- <programlisting>
-Index: pkg/PLIST
-===================================================================
-RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v
-retrieving revision 1.15
-diff -u -r1.15 PLIST
---- PLIST 1997/03/04 08:04:00 1.15
-+++ PLIST 1997/04/15 06:32:12
-@@ -15,9 +15,6 @@
- man/man1/emacs.1.gz
- man/man1/etags.1.gz
- man/man1/ctags.1.gz
--@unexec cp %D/info/dir %D/info/dir.bak
--info/dir
--@unexec cp %D/info/dir.bak %D/info/dir
- info/cl
- info/cl-1
- info/cl-2</programlisting>
- </step>
-
- <step>
- <para>Add a <maketarget>post-install</maketarget>
- target to the <filename>Makefile</filename> to create a
- <filename>dir</filename> file if it is not there. Also,
- call <maketarget>install-info</maketarget> with the
- installed info files.</para>
-
- <programlisting>
-Index: Makefile
-===================================================================
-RCS file: /usr/cvs/ports/editors/emacs/Makefile,v
-retrieving revision 1.26
-diff -u -r1.26 Makefile
---- Makefile 1996/11/19 13:14:40 1.26
-+++ Makefile 1997/05/20 10:25:09 1.28
-@@ -20,5 +20,11 @@
- post-install:
- .for file in emacs-19.34 emacsclient etags ctags b2m
- strip ${PREFIX}/bin/${file}
- .endfor
-+ if [ ! -f ${PREFIX}/info/dir ]; then \
-+ ${SED} -ne '1,/Menu:/p' /usr/share/info/dir > ${PREFIX}/info/dir; \
-+ fi
-+.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode
-+ install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir
-+.endfor
-
- .include <bsd.port.mk></programlisting>
-
- <para>Do not use anything other than
- <filename>/usr/share/info/dir</filename> and the above
- command to create a new info file. In fact, I'd add the
- first three lines of the above patch to
- <filename>bsd.port.mk</filename> if you (the porter)
- wouldn't have to do it in <filename>PLIST</filename> by
- yourself anyway.</para>
- </step>
-
- <step>
- <para>Edit <filename>PLIST</filename> and add equivalent
- <literal>@exec</literal> statements and also
- <literal>@unexec</literal> for <command>pkg_delete</command>.
- You do not need to delete <filename>info/dir</filename>
- with <literal>@unexec</literal>.</para>
-
- <programlisting>
-Index: pkg/PLIST
-===================================================================
-RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v
-retrieving revision 1.15
-diff -u -r1.15 PLIST
---- PLIST 1997/03/04 08:04:00 1.15
-+++ PLIST 1997/05/20 10:25:12 1.17
-@@ -16,7 +14,15 @@
- man/man1/etags.1.gz
- man/man1/ctags.1.gz
-+@unexec install-info --delete %D/info/emacs %D/info/dir
- :
-+@unexec install-info --delete %D/info/ccmode %D/info/dir
- info/cl
- info/cl-1
-@@ -87,6 +94,18 @@
- info/viper-3
- info/viper-4
-+@exec [ -f %D/info/dir ] || sed -ne '1,/Menu:/p' /usr/share/info/dir > %D/info/dir
-+@exec install-info %D/info/emacs %D/info/dir
- :
-+@exec install-info %D/info/ccmode %D/info/dir
- libexec/emacs/19.34/i386--freebsd/cvtmail
- libexec/emacs/19.34/i386--freebsd/digest-doc</programlisting>
-
- <note>
- <para>The <literal>@unexec install-info
- --delete</literal> commands have to be listed before
- the info files themselves so they can read the files.
- Also, the <literal>@exec install-info</literal> commands
- have to be after the info files and the
- <literal>@exec</literal> command that creates the the
- <filename>dir</filename> file.</para>
- </note>
- </step>
-
- <step>
- <para>Test and admire your work. <!-- smiley --><emphasis>:)</emphasis> The sequence I recommend is:
- <command>make package</command>,
- <command>pkg_delete</command>, then
- <command>pkg_add</command>. Check the <filename>dir</filename> file before and after each
- step.</para>
- </step>
-
- </procedure>
-
-
- </sect3>
-
- <sect3>
- <title>Changing the <filename>PLIST</filename> based on <citerefentry>
- <refentrytitle>make</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> variables</title>
-
- <para>Some ports, particularly the <filename>p5-</filename> ports,
- need to change their <filename>PLIST</filename> depending on what
- options they are configured with (or version of perl, in the case of
- <filename>p5-</filename> ports). To make this easy, any instances in
- the <filename>PLIST</filename> of <literal>%%OSREL%%</literal>,
- <literal>%%PERL_VER%%</literal>, and
- <literal>%%PERL_VERSION%%</literal> will be substituted for
- appropriately. If you need to make other substitutions, you can set
- the <makevar>PLIST_SUB</makevar> variable with a list of
- <literal><replaceable>VAR</replaceable>=<replaceable>VALUE</replaceable></literal> pairs and instances of <literal>%%<replaceable>VAR</replaceable>%%</literal> will be substituted with <replaceable>VALUE</replaceable> in the <filename>PLIST</filename>.</para>
- </sect3>
-
- <sect3>
- <title>Licensing Problems</title>
-
- <para>Some software packages have restrictive licenses or can be
- in violation to the law (PKP's patent on public key crypto, ITAR
- (export of crypto software) to name just two of them). What we
- can do with them vary a lot, depending on the exact wordings of
- the respective licenses.</para>
-
- <note>
- <para>It is your responsibility as a porter to read the
- licensing terms of the software and make sure that the FreeBSD
- project will not be held accountable of violating them by
- redistributing the source or compiled binaries either via ftp
- or CD-ROM. If in doubt, please contact the &a.ports;.</para>
- </note>
-
- <para>There are two variables you can set in the Makefile to
- handle the situations that arise frequently:</para>
-
-
- <orderedlist>
-
- <listitem>
- <para>If the port has a “do not sell for profit” type of
- license, set the variable <makevar>NO_CDROM</makevar>. We
- will make sure such ports won't go into the CD-ROM come
- release time. The distfile and package will still be
- available via ftp.</para>
- </listitem>
-
- <listitem>
- <para>If the resulting package needs to be built uniquely
- for each site, or the resulting binary package can't be
- distributed due to licensing; set the variable
- <makevar>NO_PACKAGE</makevar>. We will make sure such
- packages won't go on the ftp site, nor into the CD-ROM
- come release time. The distfile will still be included on
- both however.</para>
- </listitem>
-
- <listitem>
- <para>If the port has legal restrictions on who can use it
- (e.g., crypto stuff) or has a “no commercial use” license,
- set the variable <makevar>RESTRICTED</makevar> to be the
- string describing the reason why. For such ports, the
- distfiles/packages will not be available even from our ftp
- sites.</para>
- </listitem>
-
- </orderedlist>
-
-
- <note>
- <para>The GNU General Public License (GPL), both version 1
- and 2, should not be a problem for ports.</para>
- </note>
-
- <note>
- <para>If you are a committer, make sure you update the
- <filename>ports/LEGAL</filename> file too.</para>
- </note>
- </sect3>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>When you notice that a port is out of date compared to the
- latest version from the original authors, first make sure you
- have the latest port. You can find them in the
- <filename>ports-current</filename> directory of the ftp mirror
- sites.</para>
-
- <para>The next step is to send a mail to the maintainer, if one is
- listed in the port's <filename>Makefile</filename>. That person may already be
- working on an upgrade, or have a reason to not upgrade the port
- right now (because of, for example, stability problems of the
- new version).</para>
-
- <para>If the maintainer asks you to do the upgrade or there isn't
- any such person to begin with, please make the upgrade and send
- the recursive diff (either unified or context diff is fine, but
- port committers appear to prefer unified diff more) of the new
- and old ports directories to us (e.g., if your modified port
- directory is called <filename>superedit</filename>
- and the original as in our tree is
- <filename>superedit.bak</filename>, then send us the result of
- <command>diff -ruN superedit.bak
- superedit</command>). Please examine the output to make
- sure all the changes make sense. The best way to send us the
- diff is by including it to <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- (category <literal>ports</literal>). Please mention any added or deleted files
- in the message, as they have to be explicitly specified to CVS
- when doing a commit. If the diff is more than about 20KB, please
- compress and uuencode it; otherwise, just include it in as is in
- the PR.</para>
-
- </sect3>
-
- <sect3>
- <title><anchor id="porting-dads">Do's and Dont's</title>
-
- <para>Here is a list of common do's and dont's that you encounter
- during the porting process.You should check your own port
- against this list, but you can also check ports in the PR
- database that others have submitted. Submit any comments on
- ports you check as described in <link linkend="contrib-general">Bug
- Reports and General Commentary</link>. Checking ports in
- the PR database will both make it faster for us to commit them,
- and prove that you know what you are doing.</para>
-
-
- <sect4>
- <title><makevar>WRKDIR</makevar></title>
-
- <para>Do not leave anything valuable lying around in the
- <filename>work</filename> subdirectory, <command>make clean</command> will
- <emphasis>nuke</emphasis> it completely! If you need
- auxiliary files that are not scripts or patches, put them in
- the <makevar>FILESDIR</makevar> subdirectory
- (<filename>files</filename> by default) and use the
- <maketarget>post-extract</maketarget> target to copy them
- to the <filename>work</filename> subdirectory.</para>
-
- </sect4>
-
- <sect4>
- <title>Portlint Clean</title>
-
- <para>Do use <command>portlint</command>! The <ulink
- url="http://www.freebsd.org/cgi/ports.cgi?portlint">portlint</ulink> program is part of the ports collection.</para>
- </sect4>
-
- <sect4>
- <title>Strip Binaries</title>
-
- <para>Do strip binaries. If the original source already strips the
- binaries, fine; otherwise you should add a
- <literal>post-install</literal> rule to to it yourself. Here is an
- example;</para>
-
- <programlisting>
-post-install:
- strip ${PREFIX}/bin/xdl</programlisting>
-
- <para>Use the <citerefentry>
- <refentrytitle>file</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> command on the installed executable to check
- whether the binary is stripped or not. If it does not say
- <literal>not stripped</literal>, it is stripped.</para>
- </sect4>
-
- <sect4>
- <title>Correctly Install Manpages</title>
-
- <para>Do use the <makevar>MAN<replaceable>n</replaceable></makevar>
- variables. These variables, will automatically add any manpages
- to <filename>pkg/PLIST</filename> (this means you must
- <emphasis>not</emphasis> list manpages in the
- <filename>PLIST</filename>) and automatically compress manpages
- (unless <makevar>NOMANCOMPRESS</makevar> is set in
- <filename>/etc/make.conf</filename>). If your port installs
- pre-compressed manpages, you must define the
- <makevar>MANCOMPRESSED</makevar> variable.</para>
-
- <programlisting>
-MAN1= foo.1 bar.1
-MAN5= foo.conf.5
-MAN8= baz.8</programlisting>
-
- <note>
- <para>This is not usually necessary with ports that are X
- applications and use <command>Imake</command> to build.</para>
- </note>
-
- <para>If your port anchors its man tree somewhere other than
- <makevar>PREFIX</makevar>, you can use the
- <makevar>MANPREFIX</makevar> to set it. Also, if only manpages in
- certain section go in a non-standard place, such as many Perl
- modules ports, you can set individual man paths using
- <makevar>MAN<replaceable>sect</replaceable>PREFIX</makevar> (where
- <replaceable>sect</replaceable> is one of <literal>1-9</literal>,
- <literal>L</literal> or <literal>N</literal>).</para>
- </sect4>
-
- <sect4>
- <title>INSTALL_* macros</title>
-
- <para>Do use the macros provided in <filename>bsd.port.mk</filename>
- to ensure correct modes and ownership of files in your own
- <maketarget>*-install</maketarget> targets. They are:</para>
-
- <itemizedlist>
- <listitem>
- <para><makevar>INSTALL_PROGRAM</makevar> is a command to install
- binary executables.</para>
- </listitem>
-
- <listitem>
- <para><makevar>INSTALL_SCRIPT</makevar> is a command to install
- executable scripts.</para>
- </listitem>
-
- <listitem>
- <para><makevar>INSTALL_DATA</makevar> is a command to install
- sharable data.</para>
- </listitem>
-
- <listitem>
- <para><makevar>INSTALL_MAN</makevar> is a command to install
- manpages and other documentation (it doesn't compress
- anything).</para>
- </listitem>
- </itemizedlist>
-
- <para>These are basically the <command>install</command> command
- with all the appropriate flags. See below for an example on how
- to use them.</para>
- </sect4>
-
- <sect4>
- <title><filename>INSTALL</filename> package script</title>
-
- <para>If your port needs execute commands when the binary package is
- installed with pkg_add you can do with via the
- <filename>pkg/INSTALL</filename> script. This script will
- automatically be added to the package, and will be run twice by
- <command>pkg_add</command>. The first time will as
- <command>INSTALL ${PKGNAME} PRE-INSTALL</command> and the second
- time as <command>INSTALL ${PKGNAME} POST-INSTALL</command>.
- <literal>$2</literal> can be tested to determine which mode
- the script is being run in.</para>
-
- <para>The <envar>PKG_PREFIX</envar> environmental variable will be
- set to the package installation directory. See <citerefentry>
- <refentrytitle>pkg_add</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry> for additional information.</para>
-
- <note>
- <para>This script is not run automatically if you install the port
- with <command>make install</command>. If you are depending on it
- being run, you will have to explicitly call it on your port's
- <filename>Makefile</filename>.</para>
- </note>
- </sect4>
-
- <sect4>
- <title><filename>REQ</filename> package script</title>
-
- <para>If your port needs to determine if it should install or
- not, you can create a <filename>pkg/REQ</filename>
- “requirements” script. It will be invoked automatically at
- installation/deinstallation time to determine whether or not
- installation/deinstallation should proceed. See man
- <citerefentry><refentrytitle>pkg_create</refentrytitle><manvolnum>1</manvolnum></citerefentry> and man
- <citerefentry><refentrytitle>pkg_add</refentrytitle><manvolnum>1</manvolnum></citerefentry> for more information.</para>
-
- </sect4>
-
- <sect4>
- <title>Install additional documentation</title>
-
- <para>If your software has some documentation other than the
- standard man and info pages that you think is useful for the
- user, install it under
- <filename><makevar>PREFIX</makevar>/share/doc</filename>. This can be
- done, like the previous item, in the <maketarget>post-install</maketarget> target.</para>
-
- <para>Create a new directory for your port. The directory name
- should reflect what the port is. This usually means <makevar>PKGNAME</makevar> minus the version part.
- However, if you think the user might want different versions
- of the port to be installed at the same time, you can use the
- whole <makevar>PKGNAME</makevar>.</para>
-
- <para>Make the installation dependent to the variable
- <makevar>NOPORTDOCS</makevar> so that users can disable it in
- <filename>/etc/make.conf</filename>, like this:</para>
-
- <programlisting>
-post-install:
-.if !defined(NOPORTDOCS)
- ${MKDIR}${PREFIX}/share/doc/xv
- ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
-.endif</programlisting>
-
- <para>Do not forget to add them to
- <filename>pkg/PLIST</filename> too! (Do not worry about
- <makevar>NOPORTDOCS</makevar> here; there is currently no way
- for the packages to read variables from
- <filename>/etc/make.conf</filename>.)</para>
-
- <para>If you need to display a message to the installer, you may
- place the message in <filename>pkg/MESSAGE</filename>. This
- capibility is often useful to display additional installation
- steps to be taken after a pkg_add, or to display licensing
- information.</para>
-
- <note>
- <para><filename>MESSAGE</filename> does not need to be added
- to <filename>pkg/PLIST</filename>).</para>
- </note>
- </sect4>
-
- <sect4>
- <title><makevar>DIST_SUBDIR</makevar></title>
-
- <para>Do not let your port clutter
- <filename>/usr/ports/distfiles</filename>. If your port
- requires a lot of files to be fetched, or contains a file that
- has a name that might conflict with other ports (e.g.,
- <filename>Makefile</filename>), set <makevar>DIST_SUBDIR</makevar> to the name of the
- port (<makevar>PKGNAME</makevar> without the
- version part should work fine). This will change <makevar>DISTDIR</makevar> from the default
- <filename>/usr/ports/distfiles</filename> to
- <filename>/usr/ports/distfiles/<makevar>DIST_SUBDIR</makevar></filename>,
- and in effect puts everything that is required for your port
- into that subdirectory.</para>
-
- <para>It will also look at the subdirectory with the same name
- on the backup master site at
- <filename>ftp.freebsd.org</filename>. (Setting <makevar>DISTDIR</makevar> explicitly in your
- <makevar>Makefile</makevar> will not accomplish this, so please use <makevar>DIST_SUBDIR</makevar>.)</para>
-
- <note>
- <para>This does not affect the <makevar>MASTER_SITES</makevar> you define in your
- Makefile.</para>
- </note>
- </sect4>
-
- <sect4>
- <title>Package information</title>
-
- <para>Do include package information, i.e.
- <filename>COMMENT</filename>, <filename>DESCR</filename>, and
- <filename>PLIST</filename>, in <filename>pkg</filename>.</para>
-
- <note>
- <para>Note that these files are not used only for packaging
- anymore, and are <emphasis>mandatory</emphasis> now, even if
- <makevar>NO_PACKAGE</makevar> is
- set.</para>
- </note>
- </sect4>
-
- <sect4>
- <title>Feedback</title>
-
- <para>Do send applicable changes/patches to the original
- author/maintainer for inclusion in next release of the code.
- This will only make your job that much easier for the next
- release.</para>
-
- </sect4>
-
- <sect4>
- <title>RCS strings</title>
-
- <para>Do not put RCS strings in patches. CVS will mangle them
- when we put the files into the ports tree, and when we check
- them out again, they will come out different and the patch
- will fail. RCS strings are surrounded by dollar (<literal>$</literal>) signs, and typically start with
- <literal>$Id</literal> or <literal>$RCS</literal>.</para>
-
- </sect4>
-
- <sect4>
- <title>Recursive diff</title>
-
- <para>Using the recurse (<option>-r</option>) option to
- <command>diff</command> to generate patches is
- fine, but please take a look at the resulting patches to make
- sure you don't have any unnecessary junk in there. In
- particular, diffs between two backup files, <filename>Makefiles</filename> when the
- port uses <command>Imake</command> or GNU <command>configure</command>, etc., are unnecessary and
- should be deleted. Also, if you had to delete a file, then you
- can do it in the <maketarget>post-extract</maketarget>
- target rather than as part of the patch. Once you are happy
- with the resulting diff, please split it up into one source
- file per patch file.</para>
-
- </sect4>
-
- <sect4>
- <title><makevar>PREFIX</makevar></title>
-
- <para>Do try to make your port install relative to <makevar>PREFIX</makevar>. (The value of this
- variable will be set to <makevar>LOCALBASE</makevar> (default
- <filename>/usr/local</filename>), unless <makevar>USE_X_PREFIX</makevar> or <makevar>USE_IMAKE</makevar> is set, in which case it
- will be <makevar>X11BASE</makevar> (default
- <filename>/usr/X11R6</filename>).)</para>
-
- <para>Not hard-coding <filename>/usr/local</filename> or
- <filename>/usr/X11R6</filename> anywhere in the source will
- make the port much more flexible and able to cater to the
- needs of other sites. For X ports that use <command>imake</command>, this is
- automatic; otherwise, this can often be done by simply
- replacing the occurrences of <filename>/usr/local</filename>
- (or <filename>/usr/X11R6</filename> for X ports that do not
- use imake) in the various scripts/Makefiles in the port to
- read <makevar>PREFIX</makevar>, as this
- variable is automatically passed down to every stage of the
- build and install processes.</para>
-
- <para>Do not set <makevar>USE_X_PREFIX</makevar> unless your port
- truly require it (i.e., it links against X libs or it needs to
- reference files in <makevar>X11BASE</makevar>.</para>
-
- <para>The variable <makevar>PREFIX</makevar>
- can be reassigned in your <filename>Makefile</filename> or in the user's
- environment. However, it is strongly discouraged for
- individual ports to set this variable explicitly in the
- <filename>Makefiles</filename>.</para>
-
- <para>Also, refer to programs/files from other ports with the
- variables mentioned above, not explicit pathnames. For
- instance, if your port requires a macro
- <literal>PAGER</literal> to be the full pathname of <command>less</command>, use the compiler flag:
-
- <programlisting>
--DPAGER=\"${PREFIX}/bin/less\"</programlisting>
-
- or
-
- <programlisting>
--DPAGER=\"${LOCALBASE}/bin/less\"</programlisting>
-
- if this is an X port, instead of <literal>-DPAGER=\"/usr/local/bin/less\".</literal> This way it will have a better chance of working if the system administrator has moved the whole `/usr/local' tree somewhere else.</para>
-
- </sect4>
-
- <sect4>
- <title>Subdirectories</title>
-
- <para>Try to let the port put things in the right subdirectories
- of <makevar>PREFIX</makevar>. Some ports
- lump everything and put it in the subdirectory with the port's
- name, which is incorrect. Also, many ports put everything
- except binaries, header files and manual pages in the a
- subdirectory of <filename>lib</filename>, which does not
- bode well with the BSD paradigm. Many of the files should be
- moved to one of the following: <filename>etc</filename>
- (setup/configuration files), <filename>libexec</filename>
- (executables started internally), <filename>sbin</filename>
- (executables for superusers/managers),
- <filename>info</filename> (documentation for info browser)
- or <filename>share</filename> (architecture independent
- files). See man <citerefentry><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
- details, the rule governing <filename>/usr</filename> pretty
- much applies to <filename>/usr/local</filename> too. The
- exception are ports dealing with USENET “news”. They may use
- <filename><makevar>PREFIX</makevar>/news</filename> as a destination for
- their files.</para>
-
- </sect4>
-
- <sect4>
- <title>ldconfig</title>
-
- <para>If your port installs a shared library, add a <maketarget>post-install</maketarget> target to your Makefile
- that runs <command>/sbin/ldconfig -m</command> on
- the directory where the new library is installed (usually
- <filename><makevar>PREFIX</makevar>/lib</filename>) to register it into
- the shared library cache.</para>
-
- <para>Also, add an <literal>@exec</literal> line to your
- <filename>pkg/PLIST</filename> file so that a user who
- installed the package can start using the shared library
- immediately. This line should immediately follow the line
- for the shared library itself, as in:</para>
-
- <programlisting>
-lib/libtcl80.so.1.0
-@exec /sbin/ldconfig -m %D/lib</programlisting>
-
- <para>Never, ever, <emphasis>ever</emphasis> add a line that
- says <command>ldconfig</command> without any
- arguments to your <filename>Makefile</filename> or <filename>pkg/PLIST</filename>. This will reset the
- shared library cache to the contents of
- <filename>/usr/lib</filename> only, and will royally screw up
- the user's machine (“Help, xinit does not run anymore after I
- install this port!”). Anybody who does this will be shot and
- cut into 65,536 pieces by a rusty knife and have his liver
- chopped out by a bunch of crows and will eternally rot to
- death in the deepest bowels of hell (not necessarily in that
- order)....</para>
-
- </sect4>
-
- <sect4>
- <title>UIDs</title>
-
- <para>If your port requires a certain user to be on the
- installed system, let the <filename>pkg/INSTALL</filename>
- script call <command>pw</command> to create it
- automatically. Look at <filename>net/cvsup-mirror</filename>
- for an example.</para>
-
- <para>If your port must use the same user/group ID number when it is
- installed a binarypackage as when it was compiled, then you mus
- choose a free UID from 50 to 99 and register it below. Look at
- <filename>japanese/Wnn</filename> for an example.</para>
-
- <para>Make sure you don't use a UID already used by the system
- or other ports. This is the current list of UIDs between 50
- and 99.</para>
-
- <programlisting>
-majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent
-cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent
-gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh
-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:/nonexistent
-wnn:*:69:7:Wnn:/nonexistent:/nonexistent
-ifmail:*:70:66:Ifmail user:/nonexistent:/nonexistent
-pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh
-ircd:*:72:72:IRCd hybrid:/nonexistent:/nonexistent
-alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent
-qmaill:*:83:81:QMail user:/var/qmail:/nonexistent
-qmaild:*:82:81:QMail user:/var/qmail:/nonexistent
-qmailq:*:85:82:QMail user:/var/qmail:/nonexistent
-qmails:*:87:82:QMail user:/var/qmail:/nonexistent
-qmailp:*:84:81:QMail user:/var/qmail:/nonexistent
-qmailr:*:86:82:QMail user:/var/qmail:/nonexistent
-msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh</programlisting>
-
- <para>Please include a notice when you submit a port (or an
- upgrade) that reserves a new UID or GID in this range. This allows
- us to keep the list of reserved IDs up to date.</para>
-
- </sect4>
-
- <sect4>
- <title>Doing things rationally</title>
-
- <para>The <filename>Makefile</filename> should do things simply and
- reasonably. If you can make it a couple of lines shorter or more
- readable, then do so. Examples include using a make
- <literal>.if</literal> construct instead of a shell
- <literal>if</literal> construct, not redefining
- <maketarget>do-extract</maketarget> if you can redefine
- <makevar>EXTRACT*</makevar> instead, and using
- <makevar>GNU_CONFIGURE</makevar> instead of
- <literal>CONFIGURE_ARGS +=
- --prefix=${PREFIX}</literal>.</para>
- </sect4>
-
- <sect4>
- <title>Respect <makevar>CFLAGS</makevar></title>
-
- <para>The port should respect the <makevar>CFLAGS</makevar>
- variable. If it doesn't, please add <literal>NO_PACKAGE=ignores
- cflags</literal> to the <filename>Makefile</filename>.</para>
- </sect4>
-
- <sect4>
- <title>Miscellanea</title>
-
- <para>The files <filename>pkg/DESCR</filename>,
- <filename>pkg/COMMENT</filename>, and
- <filename>pkg/PLIST</filename> should each be double-checked. If
- you are reviewing a port and feel they can be worded better, do
- so.</para>
-
- <para>Don't copy more copies of the GNU General Public License into
- our system, please.</para>
-
- <para>Please be careful to note any legal issues! Don't let us
- illegally distribute software!</para>
- </sect4>
-
- <sect4>
- <title>If you are stuck....</title>
-
- <para>Do look at existing examples and the
- <filename>bsd.port.mk</filename> file before asking us
- questions! <!-- smiley --><emphasis>;)</emphasis></para>
-
- <para>Do ask us questions if you have any trouble! Do not just
- beat your head against a wall! <!-- smiley --><emphasis>:)</emphasis></para>
-
- </sect4>
- </sect3>
-
- <sect3 id="porting-samplem">
- <title>A Sample <filename>Makefile</filename></title>
-
- <para>Here is a sample <filename>Makefile</filename> that you can
- use to create a new port. Make sure you remove all the extra
- comments (ones between brackets)!</para>
-
- <para>It is recommended that you follow this format (ordering of
- variables, empty lines between sections, etc.). Not all of the
- existing <filename>Makefile</filename>s are in this format
- (mostly old ones), but we are trying to uniformize how they
- look. This format is designed so that the most important
- information is easy to locate.</para>
-
- <programlisting>
-[the header...just to make it easier for us to identify the ports.]
-# New ports collection makefile for: xdvi
-[the version required header should updated when upgrading a port.]
-# Version required: pl18 [things like "1.5alpha" are fine here too]
-[this is the date when the first version of this Makefile was created.
-Never change this when doing an update of the port.]
-# Date created: 26 May 1995
-[this is the person who did the original port to FreeBSD, in particular, the
-person who wrote the first version of this Makefile. Remember, this should
-not be changed when upgrading the port later.]
-# Whom: Satoshi Asami <asami@FreeBSD.ORG>
-#
-# $Id$
-[ ^^^^ This will be automatically replaced with RCS ID string by CVS
-when it is committed to our repository.]
-#
-
-[section to describe the port itself and the master site - DISTNAME
- is always first, followed by PKGNAME (if necessary), CATEGORIES,
- and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR.
- After those, one of EXTRACT_SUFX or DISTFILES can be specified too.]
-DISTNAME= xdvi
-PKGNAME= xdvi-pl18
-CATEGORIES= print
-[do not forget the trailing slash ("/")!
- if you aren't using MASTER_SITE_* macros]
-MASTER_SITES= ${MASTER_SITE_XCONTRIB}
-MASTER_SITE_SUBDIR= applications
-[set this if the source is not in the standard ".tar.gz" form]
-EXTRACT_SUFX= .tar.Z
-
-[section for distributed patches -- can be empty]
-PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/
-PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz
-
-[maintainer; *mandatory*! This is the person (preferably with commit
- privileges) who a user can contact for questions and bug reports - this
- person should be the porter or someone who can forward questions to the
- original porter reasonably promptly. If you really do not want to have
- your address here, set it to "ports@FreeBSD.ORG".]
-MAINTAINER= asami@FreeBSD.ORG
-
-[dependencies -- can be empty]
-RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript
-LIB_DEPENDS= Xpm\\.4\\.:${PORTSDIR}/graphics/xpm
-
-[this section is for other standard bsd.port.mk variables that do not
- belong to any of the above]
-[If it asks questions during configure, build, install...]
-IS_INTERACTIVE= yes
-[If it extracts to a directory other than ${DISTNAME}...]
-WRKSRC= ${WRKDIR}/xdvi-new
-[If the distributed patches were not made relative to ${WRKSRC}, you
- may need to tweak this]
-PATCH_DIST_STRIP= -p1
-[If it requires a "configure" script generated by GNU autoconf to be run]
-GNU_CONFIGURE= yes
-[If it requires GNU make, not /usr/bin/make, to build...]
-USE_GMAKE= yes
-[If it is an X application and requires "xmkmf -a" to be run...]
-USE_IMAKE= yes
-[et cetera.]
-
-[non-standard variables to be used in the rules below]
-MY_FAVORITE_RESPONSE= "yeah, right"
-
-[then the special rules, in the order they are called]
-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
-
-[and then the epilogue]
-.include <bsd.port.mk></programlisting>
-
- </sect3>
-
- <sect3>
- <title>Package Names</title>
-
- <para>The following are the conventions you should follow in
- naming your packages. This is to have our package directory
- easy to scan, as there are already lots and lots of packages and
- users are going to turn away if they hurt their eyes!</para>
-
- <para>The package name should look like <filename><replaceable>language-</replaceable>name<replaceable>-compiled.specifics</replaceable><replaceable>-version.numbers</replaceable></filename>.</para>
-
- <para>If your <makevar>DISTNAME</makevar>
- doesn't look like that, set <makevar>PKGNAME</makevar> to something in that
- format.</para>
-
-
- <orderedlist>
-
- <listitem>
- <para>FreeBSD strives to support the native language of its
- users. The <replaceable>language-</replaceable> part should be a two letter
- abbreviation of the natural language defined by ISO-639 if
- the port is specific to a certain language. Examples are
- <literal>ja</literal> for Japanese, <literal>ru</literal> for Russian, <literal>vi</literal> for Vietnamese,
- <literal>zh</literal> for Chinese, <literal>ko</literal> for Korean and <literal>de</literal> for German.</para>
- </listitem>
-
- <listitem>
- <para>The <filename>name</filename> part
- should be all lowercases, except for a really large
- package (with lots of programs in it). Things like
- XFree86 (yes there really is a package of it, check it
- out) and ImageMagick fall into this category. Otherwise,
- convert the name (or at least the first letter) to
- lowercase. If the capital letters are
- important to the name (for example, with one-letter names
- like <literal>R</literal> or <literal>V</literal>) you may use capital letters at your discretion.
- There is a tradition of naming Perl 5 modules by prepending
- <literal>p5-</literal> and converting the double-colon separator to a hyphen;
- for example, the <literal>Data::Dumper</literal> module becomes
- <literal>p5-Data-Dumper</literal>. If the software in question has numbers,
- hyphens, or underscores in its name, you may include them as
- well (like <literal>kinput2</literal>).</para>
- </listitem>
-
- <listitem>
- <para>If the port can be built with different hardcoded
- defaults (usually specified as environment variables or on
- the <command>make</command> command line), the
- <replaceable>-compiled.specifics</replaceable> part should state the
- compiled-in defaults (the hyphen is optional). Examples
- are papersize and font units.</para>
- </listitem>
-
- <listitem>
- <para>The version string should be a period-separated list
- of integers and single lowercase alphabetics. The only
- exception is the string <literal>pl</literal> (meaning `patchlevel'), which
- can be used <emphasis>only</emphasis> when there are no
- major and minor version numbers in the software.</para>
- </listitem>
-
- </orderedlist>
-
-
- <para>Here are some (real) examples on how to convert a <makevar>DISTNAME</makevar> into a suitable <makevar>PKGNAME</makevar>:</para>
-
- <informaltable frame="none">
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Distribution Name</entry>
- <entry>Package Name</entry>
- <entry>Reason</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>mule-2.2.2.</entry>
- <entry>mule-2.2.2</entry>
- <entry>No changes required</entry>
- </row>
-
- <row>
- <entry>XFree86-3.1.2</entry>
- <entry>XFree86-3.1.2</entry>
- <entry>No changes required</entry>
- </row>
-
- <row>
- <entry>EmiClock-1.0.2</entry>
- <entry>emiclock-1.0.2</entry>
- <entry>No uppercase names for single programs</entry>
- </row>
-
- <row>
- <entry>gmod1.4</entry>
- <entry>gmod-1.4</entry>
- <entry>Need a hyphen before version numbers</entry>
- </row>
-
- <row>
- <entry>xmris.4.0.2</entry>
- <entry>xmris-4.0.2</entry>
- <entry>Need a hyphen before version numbers</entry>
- </row>
-
- <row>
- <entry>rdist-1.3alpha</entry>
- <entry>rdist-1.3a</entry>
- <entry>No strings like <literal>alpha</literal>
- allowed</entry>
- </row>
-
- <row>
- <entry>es-0.9-beta1</entry>
- <entry>es-0.9b1</entry>
- <entry>No strings like <literal>beta</literal>
- allowed</entry>
- </row>
-
- <row>
- <entry>v3.3beta021.src</entry>
- <entry>tiff-3.3</entry>
- <entry>What the heck was that anyway?</entry>
- </row>
-
- <row>
- <entry>tvtwm</entry>
- <entry>tvtwm-pl11</entry>
- <entry>Version string always required</entry>
- </row>
-
- <row>
- <entry>piewm</entry>
- <entry>piewm-1.0</entry>
- <entry>Version string always required</entry>
- </row>
-
- <row>
- <entry>xvgr-2.10pl1</entry>
- <entry>xvgr-2.10.1</entry>
- <entry><literal>pl</literal> allowed only when no
- major/minor version numbers</entry>
- </row>
-
- <row>
- <entry>gawk-2.15.6</entry>
- <entry>ja-gawk-2.15.6</entry>
- <entry>Japanese language version</entry>
- </row>
-
- <row>
- <entry>psutils-1.13</entry>
- <entry>psutils-letter-1.13</entry>
- <entry>Papersize hardcoded at package build time</entry>
- </row>
-
- <row>
- <entry>pkfonts</entry>
- <entry>pkfonts300-1.0</entry>
- <entry>Package for 300dpi fonts</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>If there is absolutely no trace of version information in
- the original source and it is unlikely that the original author
- will ever release another version, just set the version string
- to <literal>1.0</literal> (like the piewm example above). Otherwise, ask the
- original author or use the date string (<literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>) as the
- version.</para>
-
- </sect3>
-
- <sect3>
- <title>Changes to this document and the ports system</title>
-
- <para>If you maintain a lot of ports, you should consider following
- the <email>ports@FreeBSD.ORG</email> mailing-list. Important changes to
- the way ports work will be announced there. You can always
- find more detailed information on the latest changes by
- looking at <ulink
- url="http://www.FreeBSD.ORG/cgi/cvsweb.cgi/src/share/mk/bsd.port.mk">
- the bsd.port.mk CVS log</ulink>.</para>
- </sect3>
-
- <sect3>
- <title>That is It, Folks!</title>
-
- <para>Boy, this sure was a long tutorial, wasn't it? Thanks for
- following us to here, really.</para>
-
- <para>Well, now that you know how to do a port, let us go at it
- and convert everything in the world into ports! That is the
- easiest way to start contributing to the FreeBSD Project!
- <!-- smiley --><emphasis>:)</emphasis></para>
-
- </sect3>
- </sect2>
-
<sect2>
<title>Money, Hardware or Internet access</title>
@@ -3763,18 +1240,14 @@ box can be opened)</para>
<para>Ari Suutari <email>ari@suutari.iki.fi</email></para>
</listitem>
- <listitem>
- <para>Brent J. Nordquist <email>bjn@visi.com</email></para>
- </listitem>
-
+ <listitem>
+ <para>Ben Hutchinson <email>benhutch@xfiles.org.uk</email></para>
+ </listitem>
+
<listitem>
<para>Bernd Rosauer <email>br@schiele-ct.de</email></para>
</listitem>
- <listitem>
- <para>Bill Fumerola <email>billf@jade.chc-chimes.com</email></para>
- </listitem>
-
<listitem>
<para>Bill Kish <email>kish@osf.org</email></para>
</listitem>
@@ -3899,7 +1372,11 @@ box can be opened)</para>
<listitem>
<para>Chuck Hein <email>chein@cisco.com</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Clive Lin <email>clive@CiRX.ORG</email></para>
+ </listitem>
+
<listitem>
<para>Conrad Sabatier <email>conrads@neosoft.com</email></para>
</listitem>
@@ -4102,6 +1579,10 @@ box can be opened)</para>
<email>ginga@amalthea.phys.s.u-tokyo.ac.jp</email></para>
</listitem>
+ <listitem>
+ <para>Glenn Johnson <email>gljohns@bellsouth.net</email></para>
+ </listitem>
+
<listitem>
<para>Greg Ungerer <email>gerg@stallion.oz.au</email></para>
</listitem>
@@ -4141,7 +1622,11 @@ box can be opened)</para>
<listitem>
<para>Hironori Ikura <email>hikura@kaisei.org</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Hiroyuki NAKAJI <email>nakaji@zeisei3.dpri.kyoto-u.ac.jp</email></para>
+ </listitem>
+
<listitem>
<para>Holger Veit <email>Holger.Veit@gmd.de</email></para>
</listitem>
@@ -4182,10 +1667,6 @@ box can be opened)</para>
<para>Ishii Masahiro</para>
</listitem>
- <listitem>
- <para>Issei Suzuki <email>issei@t-cnet.or.jp</email></para>
- </listitem>
-
<listitem>
<para>Iseei Suzuki <email>issei@jp.FreeBSD.ORG</email></para>
</listitem>
@@ -4242,6 +1723,10 @@ box can be opened)</para>
<para>Jeffrey Wheat <email>jeff@cetlink.net</email></para>
</listitem>
+ <listitem>
+ <para>Jeremy Lea <email>reg@shale.csir.co.za</email></para>
+ </listitem>
+
<listitem>
<para>Jerry Hicks <email>jhicks@glenatl.glenayre.com</email></para>
</listitem>
@@ -4686,7 +2171,11 @@ box can be opened)</para>
<listitem>
<para>Randall Hopper <email>rhh@stealth.ct.picker.com</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Ricardas Cepas <email>rch@richard.eu.org</email></para>
+ </listitem>
+
<listitem>
<para>Richard Hwang <email>rhwang@bigpanda.com</email></para>
</listitem>
@@ -4739,10 +2228,6 @@ box can be opened)</para>
<para>Ruslan Shevchenko <email>rssh@cki.ipri.kiev.ua</email></para>
</listitem>
- <listitem>
- <para>SADA Kenji <email>sada@e-mail.ne.jp</email></para>
- </listitem>
-
<listitem>
<para>SURANYI Peter <email>suranyip@jks.is.tsukuba.ac.jp</email></para>
</listitem>
@@ -4986,7 +2471,11 @@ box can be opened)</para>
<listitem>
<para>Yen-Shuo Su <email>yssu@CCCA.NCTU.edu.tw</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Ying-Chieh Liao <email>ijliao@csie.NCTU.edu.tw</email></para>
+ </listitem>
+
<listitem>
<para>Yoshiaki Uchikawa <email>yoshiaki@kt.rim.or.jp</email></para>
</listitem>
@@ -4998,7 +2487,11 @@ box can be opened)</para>
<listitem>
<para>Yukihiro Nakai <email>nakai@technologist.com</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Yusuke Nawano <email>azuki@azkey.org</email></para>
+ </listitem>
+
<listitem>
<para>Yuval Yarom <email>yval@cs.huji.ac.il</email></para>
</listitem>
@@ -5133,7 +2626,7 @@ box can be opened)</para>
</listitem>
<listitem>
- <para>Guido van Rooij <email>guido@gvr.win.tue.nl</email></para>
+ <para>Guido van Rooij <email>guido@gvr.org</email></para>
</listitem>
<listitem>
@@ -5216,7 +2709,11 @@ box can be opened)</para>
<listitem>
<para>Julian Stacey <email>jhs@freebsd.org</email></para>
</listitem>
-
+
+ <listitem>
+ <para>Karl Dietz <email>Karl.Dietz@triplan.com</email></para>
+ </listitem>
+
<listitem>
<para>Karl Lehenbauer <email>karl@NeoSoft.com</email> <email>karl@one.neosoft.com</email></para>
</listitem>
@@ -5391,9 +2888,7 @@ box can be opened)</para>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml b/en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml
index 51cb7a5561..93ceb6062b 100644
--- a/en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml
@@ -275,14 +275,21 @@ subscribe cvs-all</programlisting>
<programlisting>
subscribe freebsd-stable</programlisting> In the body of your
- message. Optionally, you can also say `help' and Majordomo
+ message. Optionally, you can also say <literal>help</literal> and Majordomo
will send you full help on how to subscribe and unsubscribe
to the various other mailing lists we support.</para>
</listitem>
<listitem>
- <para>Grab the sources from <hostid role="fqdn">ftp.FreeBSD.ORG</hostid>. You can do
- this in three ways:</para>
+ <para>If you are installing a new system and want it to be as stable
+ as possible, you can simply grab the latest dated branch snapshot
+ from <ulink
+ url="ftp://releng22.freebsd.org/pub/FreeBSD/">ftp://releng22.freebsd.org/pub/FreeBSD/</ulink> and install it like any other release.</para>
+
+ <para>If you are already running a previous release of 2.2 and wish
+ to upgrade via sources then you can easily do so from <hostid
+ role="fqdn">ftp.FreeBSD.ORG</hostid>. This can be done in one of
+ three ways:</para>
<orderedlist>
@@ -295,7 +302,11 @@ subscribe freebsd-stable</programlisting> In the body of your
<listitem>
<para>Use the <link linkend="cvsup">cvsup</link>
program with <ulink
- URL="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/stable-supfile">this supfile</ulink>. This is the second most recommended method, since it allows you to grab the entire collection once and then only what has changed from then on. Many people run cvsup from cron to keep their sources up-to-date automatically.</para>
+ URL="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/stable-supfile">this supfile</ulink>. This is the second most recommended method, since it allows you to grab the entire collection once and then only what has changed from then on. Many people run cvsup from cron to keep their sources up-to-date automatically. For a fairly easy interface to this, simply type;</para>
+
+ <informalexample>
+ <screen>&prompt.root; <userinput>pkg_add -f ftp://ftp.freebsd.org/pub/FreeBSD/CVSup/cvsupit.tgz</userinput></screen>
+ </informalexample>
</listitem>
<listitem>
@@ -2479,9 +2490,7 @@ cvs-crypto</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/eresources/chapter.sgml b/en_US.ISO_8859-1/books/handbook/eresources/chapter.sgml
index 65f8af855a..c1fcd45ce2 100644
--- a/en_US.ISO_8859-1/books/handbook/eresources/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/eresources/chapter.sgml
@@ -320,101 +320,11 @@
</thead>
<tbody>
- <row>
- <entry>cvs-CVSROOT</entry>
- <entry>/usr/src/[A-Z]*</entry>
- <entry>Top level /usr/src file changes</entry>
- </row>
-
<row>
<entry>cvs-all</entry>
<entry>/usr/src</entry>
<entry>All changes to the tree (superset)</entry>
</row>
-
- <row>
- <entry>cvs-bin</entry>
- <entry>/usr/src/bin</entry>
- <entry>System binaries</entry>
- </row>
-
- <row>
- <entry>cvs-etc</entry>
- <entry>/usr/src/etc</entry>
- <entry>System files</entry>
- </row>
-
- <row>
- <entry>cvs-games</entry>
- <entry>/usr/src/games</entry>
- <entry>Games</entry>
- </row>
-
- <row>
- <entry>cvs-gnu</entry>
- <entry>/usr/src/gnu</entry>
- <entry>GPL'd utilities</entry>
- </row>
-
- <row>
- <entry>cvs-include</entry>
- <entry>/usr/src/include</entry>
- <entry>Include files</entry>
- </row>
-
- <row>
- <entry>cvs-kerberosIV</entry>
- <entry>/usr/src/kerberosIV</entry>
- <entry>Kerberos encryption code</entry>
- </row>
-
- <row>
- <entry>cvs-lib</entry>
- <entry>/usr/src/lib</entry>
- <entry>System libraries</entry>
- </row>
-
- <row>
- <entry>cvs-libexec</entry>
- <entry>/usr/src/libexec</entry>
- <entry>System binaries</entry>
- </row>
-
- <row>
- <entry>cvs-ports</entry>
- <entry>/usr/ports</entry>
- <entry>Ported software</entry>
- </row>
-
- <row>
- <entry>cvs-sbin</entry>
- <entry>/usr/src/sbin</entry>
- <entry>System binaries</entry>
- </row>
-
- <row>
- <entry>cvs-share</entry>
- <entry>/usr/src/share</entry>
- <entry>System shared files</entry>
- </row>
-
- <row>
- <entry>cvs-sys</entry>
- <entry>/usr/src/sys</entry>
- <entry>Kernel</entry>
- </row>
-
- <row>
- <entry>cvs-usrbin</entry>
- <entry>/usr/src/usr.bin</entry>
- <entry>Use binaries</entry>
- </row>
-
- <row>
- <entry>cvs-usrsbin</entry>
- <entry>/usr/src/usr.sbin</entry>
- <entry>System binaries</entry>
- </row>
</tbody>
</tgroup>
</informaltable>
@@ -1226,9 +1136,7 @@ help
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/hw/chapter.sgml b/en_US.ISO_8859-1/books/handbook/hw/chapter.sgml
index 111cde9410..867deea2f8 100644
--- a/en_US.ISO_8859-1/books/handbook/hw/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/hw/chapter.sgml
@@ -5677,9 +5677,7 @@ scsi -f $2 -s 100 -c "1b 0 0 $cdb3 $cdb4 $cdb5"</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/install/chapter.sgml b/en_US.ISO_8859-1/books/handbook/install/chapter.sgml
index 52485fd470..b11bbc33d0 100644
--- a/en_US.ISO_8859-1/books/handbook/install/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/install/chapter.sgml
@@ -1225,9 +1225,7 @@ ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/internals/chapter.sgml b/en_US.ISO_8859-1/books/handbook/internals/chapter.sgml
index e29013c26f..fe94901ffc 100644
--- a/en_US.ISO_8859-1/books/handbook/internals/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/internals/chapter.sgml
@@ -1657,9 +1657,7 @@
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/introduction/chapter.sgml b/en_US.ISO_8859-1/books/handbook/introduction/chapter.sgml
index a65b2bd0a8..163e13428a 100644
--- a/en_US.ISO_8859-1/books/handbook/introduction/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/introduction/chapter.sgml
@@ -615,9 +615,7 @@
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/kernelconfig/chapter.sgml b/en_US.ISO_8859-1/books/handbook/kernelconfig/chapter.sgml
index 42ce6deda9..94265ff68d 100644
--- a/en_US.ISO_8859-1/books/handbook/kernelconfig/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/kernelconfig/chapter.sgml
@@ -1695,9 +1695,7 @@ controller wcd0</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/kerneldebug/chapter.sgml b/en_US.ISO_8859-1/books/handbook/kerneldebug/chapter.sgml
index f4d06bba3a..796252e1d3 100644
--- a/en_US.ISO_8859-1/books/handbook/kerneldebug/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/kerneldebug/chapter.sgml
@@ -660,9 +660,7 @@ text_addr = 0xf5109020? (y or n) <userinput>y</userinput>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/kernelopts/chapter.sgml b/en_US.ISO_8859-1/books/handbook/kernelopts/chapter.sgml
index 30f5e9f461..0e6defe0cb 100644
--- a/en_US.ISO_8859-1/books/handbook/kernelopts/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/kernelopts/chapter.sgml
@@ -166,9 +166,7 @@ options notyet,notdef</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/l10n/chapter.sgml b/en_US.ISO_8859-1/books/handbook/l10n/chapter.sgml
index 4fda3de2f8..7ab182a604 100644
--- a/en_US.ISO_8859-1/books/handbook/l10n/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/l10n/chapter.sgml
@@ -357,9 +357,7 @@ XkbKeymap "xfree86(ru)"</programlisting> line into
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/linuxemu/chapter.sgml b/en_US.ISO_8859-1/books/handbook/linuxemu/chapter.sgml
index 187301676e..0e2bc3b76d 100644
--- a/en_US.ISO_8859-1/books/handbook/linuxemu/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/linuxemu/chapter.sgml
@@ -853,9 +853,7 @@ richc.isdn.bcm.tmc.edu 9845-03452-90255</screen>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/mail/chapter.sgml b/en_US.ISO_8859-1/books/handbook/mail/chapter.sgml
index e4c2d14f9e..18b2d73610 100644
--- a/en_US.ISO_8859-1/books/handbook/mail/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/mail/chapter.sgml
@@ -586,9 +586,7 @@ an A record in the DNS for "customer.com".</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/mirrors/chapter.sgml b/en_US.ISO_8859-1/books/handbook/mirrors/chapter.sgml
index bfef299630..0f4423b959 100644
--- a/en_US.ISO_8859-1/books/handbook/mirrors/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/mirrors/chapter.sgml
@@ -29,7 +29,13 @@
<para><ulink
URL="ftp://ftp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.FreeBSD.ORG/pub/FreeBSD</ulink>.</para>
</blockquote></para>
-
+
+ <para>The <ulink
+ url="http://www.itworks.com.au/~gavin/FBSDsites.php3">FreeBSD mirror
+ sites database</ulink> is more accurate than the mirror listing in the
+ handbook, as it gets its information form the DNS rather than relying
+ on static lists of hosts.</para>
+
<para>Additionally, FreeBSD is available via anonymous FTP from the
following mirror sites. If you choose to obtain FreeBSD via
anonymous FTP, please try to use a site near you.</para>
@@ -76,7 +82,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ar.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ar.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.ar.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ar.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -95,22 +101,22 @@
<listitem>
<para><ulink
- URL="ftp://ftp.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.au.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.au.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.au.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.au.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.au.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.au.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp4.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.au.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp4.au.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.au.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -129,37 +135,37 @@
<listitem>
<para><ulink
- URL="ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp4.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp4.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp5.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp5.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp6.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp6.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp7.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp7.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp7.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp7.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -178,7 +184,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ca.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ca.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.ca.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ca.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -194,7 +200,7 @@
<listitem>
<para><ulink
- URL="ftp://sunsite.mff.cuni.cz/OS/FreeBSD">ftp://sunsite.mff.cuni.cz/OS/FreeBSD</ulink><!-- <br> --> Contact: <email>jj@sunsite.mff.cuni.cz</email>.</para>
+ URL="ftp://sunsite.mff.cuni.cz/OS/FreeBSD">ftp://sunsite.mff.cuni.cz/OS/FreeBSD</ulink> Contact: <email>jj@sunsite.mff.cuni.cz</email>.</para>
</listitem>
</itemizedlist>
@@ -213,7 +219,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.dk.freeBSD.ORG/pub/FreeBSD">ftp://ftp.dk.freeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.dk.freeBSD.ORG/pub/FreeBSD">ftp://ftp.dk.freeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -232,7 +238,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ee.freebsd.ORG/pub/FreeBSD">ftp://ftp.ee.freebsd.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.ee.freebsd.ORG/pub/FreeBSD">ftp://ftp.ee.freebsd.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -251,7 +257,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.fi.freebsd.ORG/pub/FreeBSD">ftp://ftp.fi.freebsd.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.fi.freebsd.ORG/pub/FreeBSD">ftp://ftp.fi.freebsd.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -267,7 +273,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ibp.fr/pub/FreeBSD">ftp://ftp.ibp.fr/pub/FreeBSD</ulink><!-- <br> --> Contact: <email>Remy.Card@ibp.fr</email>.</para>
+ URL="ftp://ftp.ibp.fr/pub/FreeBSD">ftp://ftp.ibp.fr/pub/FreeBSD</ulink> Contact: <email>Remy.Card@ibp.fr</email>.</para>
</listitem>
</itemizedlist>
@@ -286,37 +292,37 @@
<listitem>
<para><ulink
- URL="ftp://ftp.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp4.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp4.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp5.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp5.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp6.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp6.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp7.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp7.de.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp7.de.FreeBSD.ORG/pub/FreeBSD">ftp://ftp7.de.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -332,7 +338,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.hk.super.net/pub/FreeBSD">ftp://ftp.hk.super.net/pub/FreeBSD</ulink><!-- <br> --> Contact: <email>ftp-admin@HK.Super.NET</email>.</para>
+ URL="ftp://ftp.hk.super.net/pub/FreeBSD">ftp://ftp.hk.super.net/pub/FreeBSD</ulink> Contact: <email>ftp-admin@HK.Super.NET</email>.</para>
</listitem>
</itemizedlist>
@@ -351,7 +357,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ie.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ie.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.ie.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ie.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -370,12 +376,12 @@
<listitem>
<para><ulink
- URL="ftp://ftp.il.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.il.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.il.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.il.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.il.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.il.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.il.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.il.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -394,32 +400,32 @@
<listitem>
<para><ulink
- URL="ftp://ftp.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.jp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.jp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.jp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.jp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.jp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.jp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp4.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.jp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp4.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.jp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp5.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.jp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp5.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.jp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp6.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.jp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp6.jp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.jp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -438,14 +444,25 @@
<listitem>
<para><ulink
- URL="ftp://ftp.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.kr.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.kr.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.kr.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.kr.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
-
+
+ <listitem>
+ <para><ulink url="ftp://ftp3.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.kr.FreeBSD.ORG/pub/FreeBSD</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="ftp://ftp4.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.kr.FreeBSD.ORG/pub/FreeBSD</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="ftp://ftp5.kr.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.kr.FreeBSD.ORG/pub/FreeBSD</ulink></para>
+ </listitem>
</itemizedlist>
</listitem>
@@ -462,7 +479,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.nl.freebsd.ORG/pub/FreeBSD">ftp://ftp.nl.freebsd.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.nl.freebsd.ORG/pub/FreeBSD">ftp://ftp.nl.freebsd.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -481,7 +498,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.pl.freebsd.ORG/pub/FreeBSD">ftp://ftp.pl.freebsd.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.pl.freebsd.ORG/pub/FreeBSD">ftp://ftp.pl.freebsd.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -500,12 +517,12 @@
<listitem>
<para><ulink
- URL="ftp://ftp.pt.freebsd.org/pub/FreeBSD">ftp://ftp.pt.freebsd.org/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.pt.freebsd.org/pub/FreeBSD">ftp://ftp.pt.freebsd.org/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.pt.freebsd.org/pub/FreeBSD">ftp://ftp2.pt.freebsd.org/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.pt.freebsd.org/pub/FreeBSD">ftp://ftp2.pt.freebsd.org/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -524,17 +541,17 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ru.freebsd.org/pub/FreeBSD">ftp://ftp.ru.freebsd.org/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.ru.freebsd.org/pub/FreeBSD">ftp://ftp.ru.freebsd.org/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.ru.freebsd.org/pub/FreeBSD">ftp://ftp2.ru.freebsd.org/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.ru.freebsd.org/pub/FreeBSD">ftp://ftp2.ru.freebsd.org/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.ru.freebsd.org/pub/FreeBSD">ftp://ftp3.ru.freebsd.org/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.ru.freebsd.org/pub/FreeBSD">ftp://ftp3.ru.freebsd.org/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
@@ -556,17 +573,17 @@
<listitem>
<para><ulink
- URL="ftp://ftp.za.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.za.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.za.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.za.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.za.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.za.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.za.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.za.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.za.FreeBSD.ORG/FreeBSD">ftp://ftp3.za.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.za.FreeBSD.ORG/FreeBSD">ftp://ftp3.za.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -600,7 +617,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.si.freebsd.ORG/pub/FreeBSD">ftp://ftp.si.freebsd.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.si.freebsd.ORG/pub/FreeBSD">ftp://ftp.si.freebsd.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -634,9 +651,19 @@
<listitem>
<para><ulink
- URL="ftp://ftp.se.freebsd.ORG/pub/FreeBSD">ftp://ftp.se.freebsd.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.se.freebsd.ORG/pub/FreeBSD">ftp://ftp.se.freebsd.ORG/pub/FreeBSD</ulink></para>
</listitem>
-
+
+ <listitem>
+ <para><ulink
+ URL="ftp://ftp2.se.freebsd.ORG/pub/FreeBSD">ftp://ftp2.se.freebsd.ORG/pub/FreeBSD</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ URL="ftp://ftp3.se.freebsd.ORG/pub/FreeBSD">ftp://ftp3.se.freebsd.ORG/pub/FreeBSD</ulink></para>
+ </listitem>
+
</itemizedlist>
</listitem>
@@ -653,17 +680,17 @@
<listitem>
<para><ulink
- URL="ftp://ftp.tw.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.tw.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.tw.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.tw.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.tw.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.tw.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.tw.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.tw.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.tw.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.tw.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.tw.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.tw.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -679,7 +706,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.nectec.or.th/pub/FreeBSD">ftp://ftp.nectec.or.th/pub/FreeBSD</ulink><!-- <br> --> Contact: <email>ftpadmin@ftp.nectec.or.th</email>.</para>
+ URL="ftp://ftp.nectec.or.th/pub/FreeBSD">ftp://ftp.nectec.or.th/pub/FreeBSD</ulink> Contact: <email>ftpadmin@ftp.nectec.or.th</email>.</para>
</listitem>
</itemizedlist>
@@ -695,7 +722,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.ua.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ua.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --> Contact: <email>archer@lucky.net</email>.</para>
+ URL="ftp://ftp.ua.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.ua.FreeBSD.ORG/pub/FreeBSD</ulink> Contact: <email>archer@lucky.net</email>.</para>
</listitem>
</itemizedlist>
@@ -714,22 +741,22 @@
<listitem>
<para><ulink
- URL="ftp://ftp.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.uk.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.uk.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.uk.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.uk.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.uk.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.uk.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp4.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.uk.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp4.uk.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.uk.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -748,32 +775,32 @@
<listitem>
<para><ulink
- URL="ftp://ftp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp3.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp3.FreeBSD.ORG/pub/FreeBSD">ftp://ftp3.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp4.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp4.FreeBSD.ORG/pub/FreeBSD">ftp://ftp4.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp5.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp5.FreeBSD.ORG/pub/FreeBSD">ftp://ftp5.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp6.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp6.FreeBSD.ORG/pub/FreeBSD">ftp://ftp6.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -800,12 +827,12 @@
<listitem>
<para><ulink
- URL="ftp://ftp.internat.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.internat.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.internat.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.internat.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ftp2.internat.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.internat.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp2.internat.FreeBSD.ORG/pub/FreeBSD">ftp://ftp2.internat.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -824,7 +851,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD</ulink><!-- <br> --></para>
+ URL="ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD">ftp://ftp.br.FreeBSD.ORG/pub/FreeBSD</ulink></para>
</listitem>
</itemizedlist>
@@ -840,7 +867,7 @@
<listitem>
<para><ulink
- URL="ftp://nic.funet.fi/pub/unix/FreeBSD/eurocrypt">ftp://nic.funet.fi/pub/unix/FreeBSD/eurocrypt</ulink><!-- <br> --> Contact: <email>count@nic.funet.fi</email>.</para>
+ URL="ftp://nic.funet.fi/pub/unix/FreeBSD/eurocrypt">ftp://nic.funet.fi/pub/unix/FreeBSD/eurocrypt</ulink> Contact: <email>count@nic.funet.fi</email>.</para>
</listitem>
</itemizedlist>
@@ -871,7 +898,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.freebsd.org/pub/FreeBSD/CTM">ftp://ftp.freebsd.org/pub/FreeBSD/CTM</ulink><!-- <br> --></para>
+ URL="ftp://ftp.freebsd.org/pub/FreeBSD/CTM">ftp://ftp.freebsd.org/pub/FreeBSD/CTM</ulink></para>
</listitem>
</itemizedlist>
@@ -887,7 +914,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.uni-trier.de/pub/unix/systems/BSD/FreeBSD/CTM">ftp://ftp.uni-trier.de/pub/unix/systems/BSD/FreeBSD/CTM</ulink><!-- <br> --></para>
+ URL="ftp://ftp.uni-trier.de/pub/unix/systems/BSD/FreeBSD/CTM">ftp://ftp.uni-trier.de/pub/unix/systems/BSD/FreeBSD/CTM</ulink></para>
</listitem>
</itemizedlist>
@@ -904,7 +931,7 @@
<listitem>
<para><ulink
- URL="ftp://ftp.internat.freebsd.org/pub/FreeBSD/CTM">ftp://ftp.internat.freebsd.org/pub/FreeBSD/CTM</ulink><!-- <br> --></para>
+ URL="ftp://ftp.internat.freebsd.org/pub/FreeBSD/CTM">ftp://ftp.internat.freebsd.org/pub/FreeBSD/CTM</ulink></para>
</listitem>
</itemizedlist>
@@ -920,17 +947,17 @@
<listitem>
<para><ulink
- URL="ftp://ctm.tw.freebsd.org/pub/FreeBSD/CTM">ftp://ctm.tw.freebsd.org/pub/FreeBSD/CTM</ulink><!-- <br> --></para>
+ URL="ftp://ctm.tw.freebsd.org/pub/FreeBSD/CTM">ftp://ctm.tw.freebsd.org/pub/FreeBSD/CTM</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ctm2.tw.freebsd.org/pub/FreeBSD/CTM">ftp://ctm2.tw.freebsd.org/pub/FreeBSD/CTM</ulink><!-- <br> --></para>
+ URL="ftp://ctm2.tw.freebsd.org/pub/FreeBSD/CTM">ftp://ctm2.tw.freebsd.org/pub/FreeBSD/CTM</ulink></para>
</listitem>
<listitem>
<para><ulink
- URL="ftp://ctm3.tw.freebsd.org/pub/freebsd/CTM">ftp://ctm3.tw.freebsd.org/pub/freebsd/CTM</ulink><!-- <br> --></para>
+ URL="ftp://ctm3.tw.freebsd.org/pub/freebsd/CTM">ftp://ctm3.tw.freebsd.org/pub/freebsd/CTM</ulink></para>
</listitem>
</itemizedlist>
@@ -1147,7 +1174,19 @@
</listitem>
</varlistentry>
-
+
+ <varlistentry>
+ <term>Poland</term>
+
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para>cvsup.pl.FreeBSD.ORG (maintainer <email>Mariusz@kam.pl</email>)</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
<varlistentry><term>Russia</term>
<listitem>
@@ -1163,6 +1202,14 @@
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>Sweden</term>
+
+ <listitem>
+ <para>cvsup.se.FreeBSD.ORG (maintainer <email>pantzer@ludd.luth.se</email>)</para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>Slovak Republic</term>
@@ -1338,6 +1385,45 @@
</sect1>
+
+ <sect1 id="mirrors-afs">
+ <title>AFS Sites</title>
+
+ <para>AFS servers for FreeBSD are running at the following sites;</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Sweden</term>
+
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para><hostid role="fqdn">stacken.kth.se</hostid>, Stacken
+ Computer Club, KTH, Sweden</para>
+ </listitem>
+
+ <listitem>
+ <para><hostid role="ipaddr">130.237.234.3</hostid>, <hostid
+ role="fqdn">milko.stacken.kth.se</hostid></para>
+ </listitem>
+
+ <listitem>
+ <para><hostid role="ipaddr">130.237.234.43</hostid>, <hostid
+ role="fqdn">hot.stacken.kth.se</hostid></para>
+ </listitem>
+
+ <listitem>
+ <para><hostid role="ipaddr">130.237.234.44</hostid>, <hostid role="fqdn">dog.stacken.kth.se</hostid></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Maintainer <email>ftp@stacken.kth.se</email></para>
+ </listitem>
+
+
+ </varlistentry>
+ </variablelist>
+ </sect1>
</chapter>
@@ -1347,9 +1433,7 @@
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/pgpkeys/chapter.sgml b/en_US.ISO_8859-1/books/handbook/pgpkeys/chapter.sgml
index bb512fb1bc..cb1b9b9d1f 100644
--- a/en_US.ISO_8859-1/books/handbook/pgpkeys/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/pgpkeys/chapter.sgml
@@ -503,9 +503,7 @@ vvlVQ0UbcR0N2+5F6Mb5GqrXZpIesn7jFJpkQKPU
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/policies/chapter.sgml b/en_US.ISO_8859-1/books/handbook/policies/chapter.sgml
index cd77ca0ba2..500b2b1d46 100644
--- a/en_US.ISO_8859-1/books/handbook/policies/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/policies/chapter.sgml
@@ -301,9 +301,7 @@ obrien@freebsd.org - 30 March 1997</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/ports/chapter.sgml b/en_US.ISO_8859-1/books/handbook/ports/chapter.sgml
index aa5d962c4a..092d021ad9 100644
--- a/en_US.ISO_8859-1/books/handbook/ports/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/ports/chapter.sgml
@@ -88,7 +88,7 @@
<title>How Does the Ports Collection Work?</title>
<para>Programs are typically distributed on the Internet as a
- <xref linkend="ports-tarball" remap="tarball"> consisting of a
+ <link linkend="ports-tarball">tarball</link> consisting of a
Makefile and the source code for the program and usually some
instructions (which are unfortunately not always as instructive as
they could be), with perhaps a configuration script.</para>
@@ -100,18 +100,18 @@
from the source.</para>
<para>FreeBSD ports still use the tarball mechanism, but use a
- <xref linkend="ports-skeleton" remap="skeleton"> to hold the
+ <link linkend="ports-skeleton">skeleton</link> to hold the
"knowledge" of how to get the program working on FreeBSD,
rather than expecting the user to be able to work it out. They also
supply their own customised
- <xref linkend="ports-makefile" remap="Makefile">, so that almost
+ <link linkend="ports-makefile">Makefile</link>, so that almost
every port can be built in the same way.</para>
<para>If you look at a port skeleton (either on <ulink
URL="file://localhost/usr/ports/devel/ElectricFence">your FreeBSD
system</ulink> or <ulink
- URL="ftp://ftp.freebsd.org/pub/FreeBSD/ports/devel/ElectricFence">the FTP site</ulink>) and expect to find all sorts of pointy-headed rocket science lurking there, you may be disappointed by the one or two rather unexciting-looking files and directories you find there. (We will discuss in a minute how to go about <xref
- linkend="ports-getting" remap="Getting a port">).</para>
+ URL="ftp://ftp.freebsd.org/pub/FreeBSD/ports/devel/ElectricFence">the FTP site</ulink>) and expect to find all sorts of pointy-headed rocket science lurking there, you may be disappointed by the one or two rather unexciting-looking files and directories you find there. (We will discuss in a minute how to go about <link
+ linkend="ports-getting">Getting a port</link>).</para>
<para>“How on earth can this do anything?” I hear you cry. “There
is no source code there!”</para>
@@ -171,13 +171,12 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<procedure>
<step>
- <para>Locate the source code <xref linkend="ports-tarball"
- remap="tarball."> If it is not available locally, try to
+ <para>Locate the source code <link linkend="ports-tarball">tarball.</link> If it is not available locally, try to
grab it from an FTP site.</para>
</step>
<step>
- <para>Run a <xref linkend="ports-checksum" remap="checksum">
+ <para>Run a <link linkend="ports-checksum">checksum</link>
test on the tarball to make sure it has not been tampered
with, accidentally truncated, downloaded in ASCII mode, struck
by neutrinos while in transit, etc.</para>
@@ -188,7 +187,7 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
</step>
<step>
- <para>Apply any <xref linkend="ports-patch" remap="patches">
+ <para>Apply any <link linkend="ports-patch">patches</link>
needed to get the source to compile and run under FreeBSD.</para>
</step>
@@ -212,8 +211,8 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<step>
<para>Register the installation in a database. This means that,
- if you do not like the program, you can cleanly <xref
- linkend="ports-remove" remap="remove"> all traces of it from
+ if you do not like the program, you can cleanly <link
+ linkend="ports-remove">remove</link> all traces of it from
your system.</para>
</step>
@@ -230,85 +229,28 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<title>Getting a FreeBSD Port</title>
<para>There are two ways of getting hold of the FreeBSD port for a
- program. One requires a <xref linkend="ports-cd" remap="FreeBSD
- CDROM">, the other involves using an <xref linkend="ports-inet"
- remap="Internet Connection."></para>
+ program. One requires a <link linkend="ports-cd">FreeBSD
+ CDROM</link>, the other involves using an <link linkend="ports-inet">Internet Connection.</link></para>
<sect2 id="ports-cd">
<title>Compiling ports from CDROM</title>
-
- <para>If you answered yes to the question “Do you want to link the
- ports collection to your CDROM” during the FreeBSD installation,
- the initial setting up will already have been done for you.</para>
-
- <para>If not, make sure the <emphasis>FreeBSD</emphasis> CDROM is in
- the drive and mounted on, say, <filename>/cdrom</filename>. Then
- do</para>
-
- <informalexample>
- <screen>&prompt.root; <userinput>mkdir /usr/ports</userinput>
-&prompt.root; <userinput>cd /usr/ports</userinput>
-&prompt.root; <userinput>ln -s /cdrom/ports/distfiles distfiles</userinput></screen>
- </informalexample>
-
- <para>to enable the ports make mechanism to find the tarballs (it
- expects to find them in <filename>/usr/ports/distfiles</filename>,
- which is why we sym-linked the CDROM's tarball directory to that
- directory).</para>
-
- <para>Now, suppose you want to install the gnats program from the
- databases directory. Here is how to do it:-</para>
-
- <informalexample>
- <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
-&prompt.root; <userinput>mkdir databases</userinput>
-&prompt.root; <userinput>cp -R /cdrom/ports/databases/gnats databases</userinput>
-&prompt.root; <userinput>cd databases/gnats</userinput>
-&prompt.root; <userinput>make install</userinput></screen>
- </informalexample>
-
- <para>Or if you are a serious database user and you want to compare
- all the ones available in the Ports collection, do</para>
-
- <informalexample>
- <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
-&prompt.root; <userinput>cp -R /cdrom/ports/databases .</userinput>
-&prompt.root; <userinput>cd databases</userinput>
-&prompt.root; <userinput>make install</userinput></screen>
- </informalexample>
-
- <para>(yes, that really is a dot on its own after the <command>cp</command> command and
- not a mistake. It is Unix-ese for “the current
- directory”) and the ports make mechanism will automatically compile and
- install all the ports in the databases directory for you!</para>
-
- <para>If you do not like this method, here is a completely different
- way of doing it:-</para>
-
- <para>Create a “link tree” to it using the
- <citerefentry><refentrytitle>lndir</refentrytitle><manvolnum>1</manvolnum></citerefentry> command that comes with the
- <emphasis>XFree86</emphasis> distribution. Find a location with
- some free space, create a directory there and then cd to it. Then
- invoke the <citerefentry><refentrytitle>lndir</refentrytitle><manvolnum>1</manvolnum></citerefentry> command with the full
- pathname of the <filename>ports</filename> directory on the CDROM as the first
- argument and . (the current directory) as the second. This might
- be, for example, something like:</para>
- <informalexample>
- <screen>&prompt.root; <userinput>lndir /cdrom/ports .</userinput></screen>
- </informalexample>
-
- <para>Then you can build ports directly off the CDROM by building
- them in the link tree you have created.</para>
-
- <para>Note that there are some ports for which we cannot provide the
+ <para>Assuming that your FreeBSD CDROM is in the drive and mounted on
+ <filename>/cdrom</filename> (and the mount point
+ <emphasis>must</emphasis> be <filename>/cdrom</filename>), you should
+ then be able to build ports just as you normally do and the port
+ collection's built in search path should find the tarballs in
+ <filename>/cdrom/ports/distfiles/</filename> (if they exist there)
+ rather than downloading them over the net.</para>
+
+ <note>
+ <para>There are some ports for which we cannot provide the
original source in the CDROM due to licensing limitations. In
- that case, you will need to look at the section on <xref
- linkend="ports-inet"
- remap="Compiling ports using an Internet connection."></para>
-
- </sect2>
+ that case, you will need to look at the section on <link
+ linkend="ports-inet">Compiling ports using an Internet connection.</link></para>
+ </note>
+ </sect2>
<sect2 id="ports-inet">
<title>Compiling ports from the Internet</title>
@@ -316,13 +258,20 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<para>If you do not have a CDROM, or you want to make sure you get
the very latest version of the port you want, you will need to
download the
- <xref linkend="ports-skeleton" remap="skeleton"> for the port. Now
+ <link linkend="ports-skeleton">skeleton</link> for the port. Now
this might sound like rather a fiddly job full of pitfalls, but
it is actually very easy.</para>
-
- <para>The key to it is that the FreeBSD FTP server can create
+
+ <para>First, if you are running a release version of FreeBSD, make
+ sure you get the appropriate “upgradekiet” for your
+ replease from the <ulink url="http://www.freebsd.org/ports/">ports
+ web page</ulink>. These packages include files that have been
+ updated since the release that you may need to compile new
+ ports.</para>
+
+ <para>The key to the skeletons is that the FreeBSD FTP server can create
on-the-fly
- <xref linkend="ports-tarball" remap="tarballs"> for you. Here is
+ <link linkend="ports-tarball">tarballs</link> for you. Here is
how it works, with the gnats program in the databases directory as
an example (the bits in square brackets are comments. Do not type
them in if you are trying this yourself!):-</para>
@@ -347,14 +296,12 @@ password. Remember to use binary (also known as image) mode!]
<para>What happened here? We connected to the FTP server in the
usual way and went to its <filename>databases</filename> sub-directory. When we gave it
- the command <command>get gnats.tar</command>, the FTP server <xref
- linkend="ports-tarball"
- remap="tarred"> up the gnats directory for us.</para>
+ the command <command>get gnats.tar</command>, the FTP server <link
+ linkend="ports-tarball">tarred</link> up the gnats directory for us.</para>
<para>We then extracted the gnats skeleton and went into the gnats
- directory to build the port. As we explained <xref
- linkend="ports-fetch"
- remap="earlier">, the make process noticed we did not have a
+ directory to build the port. As we explained <link
+ linkend="ports-fetch">earlier</link>, the make process noticed we did not have a
copy of the source locally, so it fetched one before extracting,
patching and building it.</para>
@@ -436,16 +383,17 @@ do-install:
the benefit of human readers (as in most Unix script
files).</para>
- <para><literal>DISTNAME</literal> specifies the name of the <xref
- linkend="ports-tarball" remap="tarball">, but without the
+ <para><literal>DISTNAME</literal> specifies the name of the <link
+ linkend="ports-tarball">tarball</link>, but without the
extension.</para>
<para><literal>CATEGORIES</literal> states what kind of program this is. In
- this case, a utility for developers.</para>
+ this case, a utility for developers. See the <link
+ linkend="porting-categories">categories</link> section of this
+ handbook for a complete list.</para>
<para><literal>MASTER_SITES</literal> is the URL(s) of the master FTP site,
- which is used to retrieve the <xref linkend="ports-tarball"
- remap="tarball"> if it is not available on the local system.
+ which is used to retrieve the <link linkend="ports-tarball">tarball</link> if it is not available on the local system.
This is a site which is regarded as reputable, and is normally the
one from which the program is officially distributed (in so far
as any software is "officially" distributed on the
@@ -477,8 +425,7 @@ do-install:
<sect2>
<title>The <filename>files</filename> directory</title>
- <para>The file containing the <xref linkend="ports-checksum"
- remap="checksum"> for the port is called
+ <para>The file containing the <link linkend="ports-checksum">checksum</link> for the port is called
<filename>md5</filename>, after the MD5 algorithm used for ports
checksums. It lives in a directory with the slightly confusing
name of <filename>files</filename>.</para>
@@ -491,8 +438,7 @@ do-install:
<sect2>
<title>The <filename>patches</filename> directory</title>
- <para>This directory contains the <xref linkend="ports-patch"
- remap="patches"> needed to make everything work properly under
+ <para>This directory contains the <link linkend="ports-patch">patches</link> needed to make everything work properly under
FreeBSD.</para>
</sect2>
@@ -536,7 +482,7 @@ do-install:
<listitem>
<para>Fix it yourself. Technical details on how ports work can
be found in
- <xref linkend="porting" remap="Porting applications."></para>
+ <link linkend="porting">Porting applications.</link></para>
</listitem>
<listitem>
@@ -568,15 +514,6 @@ do-install:
</sect1>
- <sect1>
- <title>I Want to Make a Port!</title>
-
- <para>Great! Please see the <xref linkend="porting"
- remap="guidelines"> for detailed instructions on how to do
- this.</para>
-
- </sect1>
-
<sect1>
<title>Some Questions and Answers</title>
@@ -707,8 +644,7 @@ do-install:
</listitem>
<listitem>
- <para>Q. I did what you said for <xref linkend="ports-cd"
- remap="compiling ports from a CDROM"> and it worked great
+ <para>Q. I did what you said for <link linkend="ports-cd">compiling ports from a CDROM</link> and it worked great
until I tried to install the kermit port:-</para>
<informalexample>
@@ -884,7 +820,16 @@ do-install:
<para>Q. There are so many ports it is hard to find the one I
want. Is there a list anywhere of what ports are available?</para>
- <para>A. Look in the <filename>INDEX</filename> file in <filename>/usr/ports</filename>.</para>
+ <para>A. Look in the <filename>INDEX</filename> file in
+ <filename>/usr/ports</filename>. If you would like to search the
+ ports collection for a keyword, you can do that too. For example,
+ you can find ports relevant to the LISP programming language
+ using:</para>
+
+ <informalexample>
+ <screen>&prompt.user; <userinput>cd /usr/ports</userinput>
+&prompt.user; <userinput>make search key=lisp</userinput></screen>
+ </informalexample>
</listitem>
<listitem>
@@ -1044,6 +989,3524 @@ grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arc
</sect1>
+
+ <sect1 id="porting">
+ <title>Making a port yourself</title>
+
+ <para><emphasis>Contributed by &a.jkh;, &a.gpalmer;, &a.asami;
+ &a.obrien; and &a.hoek;. 28 August 1996.</emphasis></para>
+
+ <para>So, now you are interested in making your own port?
+ Great!</para>
+
+ <para>What follows are some guidelines for creating a new port for
+ FreeBSD. The bulk of the work is done by
+ <filename>/usr/share/mk/bsd.port.mk</filename>, which all port
+ Makefiles include. Please refer to that file for more details on
+ the inner workings of the ports collection. Even if you don't
+ hack Makefiles daily, it is well commented, and you will still
+ gain much knowledge from it.</para>
+
+ <note>
+ <para>Only a fraction of the overridable variables
+ (<makevar><replaceable>VAR</replaceable></makevar>) are mentioned
+ in this document. Most (if not all) are documented at the start of
+ <filename>bsd.port.mk</filename>. This file users a non-standard
+ tab setting. <application>Emacs</application> and
+ <application>Vim</application> should recognise the setting on
+ loading the file. <command>vi</command> or <command>ex</command>
+ can be set to use the correct value by typing <command>:set
+ tabstop=4</command> once the file has been loaded.</para>
+ </note>
+
+ <sect2>
+ <title>Quick Porting</title>
+
+ <para>This section tells you how to do a quick port. In many
+ cases, it is not enough, but we will see.</para>
+
+ <para>First, get the original tarball and put it into <makevar>DISTDIR</makevar>, which defaults to
+ <filename>/usr/ports/distfiles</filename>.</para>
+
+ <note>
+ <para>The following assumes that the software compiled
+ out-of-the-box, i.e., there was absolutely no change required
+ for the port to work on your FreeBSD box. If you needed to
+ change something, you will have to refer to the next section
+ too.</para>
+ </note>
+
+ <sect3>
+ <title>Writing the <filename>Makefile</filename></title>
+
+ <para>The minimal <filename>Makefile</filename> would
+ look something like this:</para>
+
+ <programlisting>
+# New ports collection makefile for: oneko
+# Version required: 1.1b
+# Date created: 5 December 1994
+# Whom: asami
+#
+# $Id$
+#
+
+DISTNAME= oneko-1.1b
+CATEGORIES= games
+MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
+
+MAINTAINER= asami@FreeBSD.ORG
+
+MAN1= oneko.1
+MANCOMPRESSED= yes
+USE_IMAKE= yes
+
+.include <bsd.port.mk></programlisting>
+
+ <para>See if you can figure it out. Do not worry about the
+ contents of the <literal>$Id$</literal>
+ line, it will be filled in automatically by CVS when the port
+ is imported to our main ports tree. You can find a more
+ detailed example in the <link
+ linkend="porting-samplem">sample Makefile</link>
+ section.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Writing the description files</title>
+
+ <para>There are three description files that are
+ required for any port, whether they actually package or not.
+ They are <filename>COMMENT</filename>,
+ <filename>DESCR</filename>, and <filename>PLIST</filename>,
+ and reside in the <filename>pkg</filename>
+ subdirectory.</para>
+
+
+ <sect4>
+ <title><filename>COMMENT</filename></title>
+
+ <para>This is the one-line description of the port.
+ <emphasis>Please</emphasis> do not include the package name (or version
+ number of the software) in the comment. Here is
+ an example:</para>
+
+ <programlisting>
+A cat chasing a mouse all over the screen.</programlisting>
+
+ </sect4>
+
+ <sect4>
+ <title><filename>DESCR</filename></title>
+
+ <para>This is a longer description of the port. One to a few
+ paragraphs concisely explaining what the port does is
+ sufficient.</para>
+
+ <note>
+ <para>This is <emphasis>not</emphasis> a manual or an
+ in-depth description on how to use or compile the port!
+ <emphasis>Please be careful if you are copying from the
+ <filename>README</filename> or manpage</emphasis>; too often
+ they are not a concise description of the port or are in an
+ awkward format (e.g., manpages have justified spacing). If the
+ ported software has an official WWW homepage, you should list
+ it here.</para>
+ </note>
+
+ <para>It is recommended that you sign the name at the end of
+ this file, as in:</para>
+
+ <programlisting>
+This is a port of oneko, in which a cat chases a poor mouse all over
+the screen.
+ :
+(etc.)
+
+http://www.oneko.org/
+
+- Satoshi
+asami@cs.berkeley.edu</programlisting>
+
+ </sect4>
+
+ <sect4>
+ <title><filename>PLIST</filename></title>
+
+ <para>This file lists all the files installed by the port. It
+ is also called the “packing list” because the package is
+ generated by packing the files listed here. The pathnames
+ are relative to the installation prefix (usually
+ <filename>/usr/local</filename> or
+ <filename>/usr/X11R6</filename>). If you are using the
+ <makevar>MAN<replaceable>n</replaceable></makevar> variables (as
+ you should be), do not list any manpages here.</para>
+
+ <para>Here is a small example:</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>Refer to the <citerefentry><refentrytitle>pkg_create</refentrytitle><manvolnum>1</manvolnum></citerefentry> man page
+ for details on the packing list.</para>
+
+ <note>
+ <para>You should list all the files, but not the name
+ directories, in the list. Also, if the port creates
+ directories for itself during installtion, make sure to add
+ <literal>@dirrm</literal> lines as necessary to remove them
+ when the port is deleted.</para>
+
+ <para>It is recommended that you keep all the filenames in
+ this file sorted alphabetically. It will make verifying the
+ changes when you upgrade the port much easier.</para>
+ </note>
+ </sect4>
+ </sect3>
+
+ <sect3>
+ <title>Creating the checksum file</title>
+
+ <para>Just type <command>make makesum</command>.
+ The ports make rules will automatically generate the file
+ <filename>files/md5</filename>.</para>
+
+ </sect3>
+
+ <sect3 id="porting-testing">
+ <title>Testing the port</title>
+
+ <para>You should make sure that the port rules do exactly what
+ you want it to do, including packaging up the port. These are
+ the important points you need to verify.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename>PLIST</filename> does not contain anything not
+ installed by your port</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>PLIST</filename> contains everything that is
+ installed by your port</para>
+ </listitem>
+
+ <listitem>
+ <para>Your port can be installed multiple times using the
+ <maketarget>reinstall</maketarget> target</para>
+ </listitem>
+
+ <listitem>
+ <para>Your port <link linkend="porting-cleaning">cleans
+ up</link> after itself upon deinstall</para>
+ </listitem>
+ </itemizedlist>
+
+ <procedure>
+ <title>Recommended test ordering</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 `make package-name`</command></para>
+ </step>
+
+ <step>
+ <para><command>make deinstall</command></para>
+ </step>
+
+ <step>
+ <para><command>make reinstall</command></para>
+ </step>
+
+ <step>
+ <para><command>make package</command></para>
+ </step>
+ </procedure>
+
+ <para>Make sure that there aren't any warnings issued in any of
+ the <maketarget>package</maketarget> and
+ <maketarget>deinstall</maketarget> stages, After step 3, check
+ to see if all the new directories are correctly deleted. Also,
+ try using the software after step 4, to ensure that is works
+ correctly when installed from a package.</para>
+ </sect3>
+
+ <sect3 id="porting-portlint">
+ <title>Checking your port with <command>portlint</command></title>
+
+ <para>Please use <command>portlint</command> to see if your port
+ conforms to our guidelines. The <command>portlint</command>
+ program is part of the ports collection. In particular, your may
+ want to check if the <link
+ linkend="porting-samplem">Makefile</link> is in the right
+ shape and the <link linkend="porting-pkgname">package</link> is
+ named appropriately.</para>
+ </sect3>
+
+ <sect3 id="porting-submitting">
+ <title>Submitting the port</title>
+
+ <para>First, make sure you have read the <link
+ linkend="porting-dads">Do's and Dont's</link> section.</para>
+
+ <para>Now that you are happy with your port, the only thing
+ remaining is to put it in the main FreeBSD ports tree and make
+ everybody else happy about it too. We do not need your
+ <filename>work</filename> directory or the
+ <filename>pkgname.tgz</filename> package, so delete them
+ now. Next, simply include the output of <command>shar `find
+ port_dir`</command> in a bug report and send it with the
+ <citerefentry>
+ <refentrytitle>send-pr</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry> program (see <link linkend="contrib-general">Bug
+ Reports and General Commentary</link> for more information
+ about <citerefentry>
+ <refentrytitle>send-pr</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>. If the uncompressed port is larger than
+ 20KB, you should compress it into a tarfile and use <citerefentry>
+ <refentrytitle>uuencode</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry> before including it in the bug report (uuencoded
+ tarfiles are acceptable even if the bug report is smaller than
+ 20KB but are not preferred). Be sure to classify the bug report as
+ category <literal>ports</literal> and class
+ <literal>change-request</literal>. (Do not mark the report
+ <literal>confidential</literal>!)</para>
+
+ <para>One more time, <emphasis>do not include the original source
+ distfile, the <filename>work</filename> directory, or the
+ package you built with <command>make
+ package</command></emphasis>.</para>
+
+ <note>
+ <para>In the past, we asked you to upload new port submissions
+ in our ftp site (<hostid
+ role="fqdn">ftp.freebsd.org</hostid>). This is no longer
+ recommended as read access is turned off on that
+ <filename>incoming/</filename> directory of that site due to
+ the large amount of pirated software showing up there.</para>
+ </note>
+
+ <para>We will look at your port,
+ get back to you if necessary, and put it in the
+ tree. Your name will also appear in the list of “Additional
+ FreeBSD contributors” on the FreeBSD Handbook and other files.
+ Isn't that great?!? <!-- smiley -->:)</para>
+
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Slow Porting</title>
+
+ <para>Ok, so it was not that simple, and the port required some
+ modifications to get it to work. In this section, we will
+ explain, step by step, how to modify it to get it to work with
+ the ports paradigm.</para>
+
+
+ <sect3>
+ <title>How things work</title>
+
+ <para>First, this is the sequence of events which occurs when
+ the user first types <command>make</command> in
+ your port's directory, and you may find that having
+ <filename>bsd.port.mk</filename> in another window while you
+ read this really helps to understand it.</para>
+
+ <para>But do not worry if you do not really understand what
+ <filename>bsd.port.mk</filename> is doing, not many people
+ do... <!-- smiley --><emphasis>:></emphasis></para>
+
+
+ <procedure>
+
+ <step>
+ <para>The <maketarget>fetch</maketarget> target is run. The <maketarget>fetch</maketarget> target is
+ responsible for making sure that the tarball exists
+ locally in <makevar>DISTDIR</makevar>.
+ If <maketarget>fetch</maketarget> cannot find the required files in <makevar>DISTDIR</makevar> it will look up the
+ URL <makevar>MASTER_SITES</makevar>,
+ which is set in the Makefile, as well as our main ftp
+ site at <ulink
+ URL="ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/">ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/,</ulink> where we put sanctioned distfiles as backup. It will then attempt to fetch the named distribution file with <makevar>FETCH</makevar>, assuming that the requesting site has direct access to the Internet. If that succeeds, it will save the file in <makevar>DISTDIR</makevar> for future use and proceed.</para>
+ </step>
+
+ <step>
+ <para>The <maketarget>extract</maketarget> target is run. It looks for your port's
+ distribution file (typically a gzip'd tarball) in <makevar>DISTDIR</makevar> and unpacks it into a temporary subdirectory
+ specified by <makevar>WRKDIR</makevar>
+ (defaults to <filename>work</filename>).</para>
+ </step>
+
+ <step>
+ <para>The <maketarget>patch</maketarget> target is run. First, any patches defined
+ in <makevar>PATCHFILES</makevar> are
+ applied. Second, if any patches are found in <makevar>PATCHDIR</makevar> (defaults to the
+ <filename>patches</filename> subdirectory), they are
+ applied at this time in alphabetical order.</para>
+ </step>
+
+ <step>
+ <para>The <maketarget>configure</maketarget> target is run. This can do any one of
+ many different things.</para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>If it exists,
+ <filename>scripts/configure</filename> is run.</para>
+ </listitem>
+
+ <listitem>
+ <para>If <makevar>HAS_CONFIGURE</makevar> or
+ <makevar>GNU_CONFIGURE</makevar>
+ is set,
+ <filename><makevar>WRKSRC</makevar>/configure</filename> is
+ run.</para>
+ </listitem>
+
+ <listitem>
+ <para>If <makevar>USE_IMAKE</makevar> is set,
+ <makevar>XMKMF</makevar>
+ (default: <command>xmkmf
+ -a</command>) is run.</para>
+ </listitem>
+
+ </orderedlist>
+
+ </step>
+
+ <step>
+ <para>The <maketarget>build</maketarget> target is run. This is responsible for
+ descending into the ports' private working directory
+ (<makevar>WRKSRC</makevar>) and
+ building it. If <makevar>USE_GMAKE</makevar> is set, GNU
+ <command>make</command> will be used,
+ otherwise the system <command>make</command>
+ will be used.</para>
+ </step>
+
+ </procedure>
+
+
+ <para>The above are the default actions. In addition, you can
+ define targets <maketarget>pre-<replaceable>something</replaceable></maketarget> or <maketarget>post-<replaceable>something</replaceable></maketarget>, or put scripts
+ with those names, in the <filename>scripts</filename>
+ subdirectory, and they will be run before or after the default
+ actions are done.</para>
+
+ <para>For example, if you have a <maketarget>post-extract</maketarget> target defined in your
+ Makefile, and a file <filename>pre-build</filename> in the
+ <filename>scripts</filename> subdirectory, the
+ <maketarget>post-extract</maketarget> target will be
+ called after the regular extraction actions, and the
+ <filename>pre-build</filename> script will be executed before
+ the default build rules are done. It is recommended that you
+ use <filename>Makefile</filename> targets if the actions are
+ simple enough, because it will be easier for someone to figure
+ out what kind of non-default action the port requires.</para>
+
+ <para>The default actions are done by the
+ <filename>bsd.port.mk</filename> targets <maketarget>do-<replaceable>something</replaceable></maketarget>. For example, the
+ commands to extract a port are in the target <maketarget>do-extract</maketarget>. If you are not happy with
+ the default target, you can fix it by redefining the
+ <maketarget>do-<replaceable>something</replaceable></maketarget> target in
+ your <filename>Makefile</filename>.</para>
+
+ <note>
+ <para>The “main” targets (e.g., <maketarget>extract</maketarget>, <maketarget>configure</maketarget>, etc.) do nothing more than
+ make sure all the stages up to that one is completed and
+ call the real targets or scripts, and they are not intended
+ to be changed. If you want to fix the extraction, fix
+ <maketarget>do-extract</maketarget>, but never ever
+ touch <maketarget>extract</maketarget>!</para>
+ </note>
+
+ <para>Now that you understand what goes on when the user types
+ <command>make</command>, let us go through the
+ recommended steps to create the perfect port.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Getting the original sources</title>
+
+ <para>Get the original sources (normally) as a compressed
+ tarball (<filename><replaceable>foo</replaceable>.tar.gz</filename> or
+ <filename><replaceable>foo</replaceable>.tar.Z</filename>) and copy it into
+ <makevar>DISTDIR</makevar>. Always use
+ <emphasis>mainstream</emphasis> sources when and where you
+ can.</para>
+
+ <para>If you cannot find a ftp/http site that is well-connected
+ to the net, or can only find sites that have irritatingly
+ non-standard formats, you might want to put a copy on a
+ reliable ftp or http server that you control (e.g., your home
+ page). Make sure you set <makevar>MASTER_SITES</makevar> to
+ reflect your choice.</para>
+
+ <para>If you
+ cannot find somewhere convenient and reliable to put the distfile
+ (if you are a FreeBSD committer, you can just put it in your
+ <filename>public_html/</filename> directory on
+ <hostid>freefall</hostid>),
+ we can “house” it ourselves by putting
+ it on <filename>ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/LOCAL_PORTS/</filename> as the last resort. Please refer to this
+ location as <makevar>MASTER_SITE_LOCAL</makevar>. Send mail to
+ the &a.ports;if you are not sure what to do.</para>
+
+ <para>If your port's distfile changes all the time for no good
+ reason, consider putting the distfile in your home page and
+ listing it as the first <makevar>MASTER_SITES</makevar>. This
+ will prevent users from getting <errorname>checksum
+ mismatch</errorname> errors, and also reduce the workload of
+ maintainers of our ftp site. Also, if there isonly one master
+ site for the port, it is recommended that you house a backup at
+ your site and list it as the second
+ <makevar>MASTER_SITES</makevar>.</para>
+
+ <para>If your port requires some additional `patches' that are
+ available on the Internet, fetch them too and put them in
+ <makevar>DISTDIR</makevar>. Do not worry if
+ they come from site other than where you got the main source
+ tarball, we have a way to handle these situations (see the
+ description of <link
+ linkend="porting-patchfiles">PATCHFILES</link> below).</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Modifying the port</title>
+
+ <para>Unpack a copy of the tarball in a private directory and
+ make whatever changes are necessary to get the port to compile
+ properly under the current version of FreeBSD. Keep
+ <emphasis>careful track</emphasis> of everything you do, as
+ you will be automating the process shortly. Everything,
+ including the deletion, addition or modification of files
+ should be doable using an automated script or patch file when
+ your port is finished.</para>
+
+ <para>If your port requires significant user
+ interaction/customization to compile or install, you should
+ take a look at one of Larry Wall's classic <application>Configure</application> scripts
+ and perhaps do something similar yourself. The goal of the
+ new ports collection is to make each port as “plug-and-play”
+ as possible for the end-user while using a minimum of disk
+ space.</para>
+
+ <note>
+ <para>Unless explicitly stated, patch files, scripts, and
+ other files you have created and contributed to the FreeBSD
+ ports collection are assumed to be covered by the standard
+ BSD copyright conditions.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>Patching</title>
+
+ <para>In the preparation of the port, files that have been added
+ or changed can be picked up with a recursive diff for later
+ feeding to patch. Each set of patches you wish to apply
+ should be collected into a file named
+ <filename>patch-<replaceable>xx</replaceable></filename> where
+ <replaceable>xx</replaceable> denotes the sequence in which
+ the patches will be applied — these are done in
+ <emphasis>alphabetical order</emphasis>, thus
+ <literal>aa</literal> first, <literal>ab</literal> second and so on. These files
+ should be stored in <makevar>PATCHDIR</makevar>, from where they will be
+ automatically applied. All patches should be relative to
+ <makevar>WRKSRC</makevar> (generally the
+ directory your port's tarball unpacks itself into, that being
+ where the build is done). To make fixes and upgrades easier,
+ you should avoid having more than one patch fix the same file
+ (e.g., <filename>patch-aa</filename> and <filename>patch-ab</filename> both changing <filename><makevar>WRKSRC</makevar>/foobar.c</filename>).</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Configuring</title>
+
+ <para>Include any additional customization commands to your
+ <filename>configure</filename> script and save it in the
+ <filename>scripts</filename> subdirectory. As mentioned
+ above, you can also do this as <filename>Makefile</filename>
+ targets and/or scripts with the name
+ <filename>pre-configure</filename> or
+ <filename>post-configure</filename>.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Handling user input</title>
+
+ <para>If your port requires user input to build, configure or
+ install, then set <makevar>IS_INTERACTIVE</makevar> in your
+ Makefile. This will allow “overnight builds” to skip your port
+ if the user sets the variable <envar>BATCH</envar> in his
+ environment (and if the user sets the variable
+ <envar>INTERACTIVE</envar>, then <emphasis>only</emphasis>
+ those ports requiring interaction are built).</para>
+
+ <para>It is also recommended that if there are reasonable default
+ answers to the questions, you check the
+ <makevar>PACKAGE_BUILDING</makevar> variable and turn off the
+ interactive script when it is set. This will allow us to build
+ the packages for CD-ROMs and ftp.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Configuring the Makefile</title>
+
+ <para>Configuring the Makefile is pretty simple, and again we
+ suggest that you look at existing examples before starting.
+ Also, there is a <link linkend="porting-samplem">sample
+ Makefile</link> in this handbook, so take a look and please follow
+ the ordering of variables and sections in that template to make
+ your port easier for others to read.</para>
+
+ <para>Now, consider the following problems in sequence as you
+ design your new Makefile:</para>
+
+
+ <sect3>
+ <title>The original source</title>
+
+ <para>Does it live in <makevar>DISTDIR</makevar> as a standard gzip'd
+ tarball? If so, you can go on to the next step. If not, you
+ should look at overriding any of the <makevar>EXTRACT_CMD</makevar>, <makevar>EXTRACT_BEFORE_ARGS</makevar>, <makevar>EXTRACT_AFTER_ARGS</makevar>, <makevar>EXTRACT_SUFX</makevar>, or <makevar>DISTFILES</makevar> variables, depending on
+ how alien a format your port's distribution file is. (The
+ most common case is <literal>EXTRACT_SUFX=.tar.Z</literal>,
+ when the tarball is condensed by regular compress, not
+ gzip.)</para>
+
+ <para>In the worst case, you can simply create your own
+ <maketarget>do-extract</maketarget> target to override
+ the default, though this should be rarely, if ever,
+ necessary.</para>
+
+ </sect3>
+
+ <sect3>
+ <title><makevar>DISTNAME</makevar></title>
+
+ <para>You should set <makevar>DISTNAME</makevar> to be the base name of
+ your port. The default rules expect the distribution file
+ list (<makevar>DISTFILES</makevar>) to be
+ named <makevar>DISTNAME</makevar><makevar>EXTRACT_SUFX</makevar> which, if it is a normal tarball, is going to be
+ something like <literal>foozolix-1.0.tar.gz</literal> for a setting of <literal>DISTNAME=foozolix-1.0</literal>.</para>
+
+ <para>The default rules also expect the tarball(s) to extract
+ into a subdirectory called
+ <filename>work/<makevar>DISTNAME</makevar></filename>, e.g. <filename>work/foozolix-1.0/</filename>.</para>
+
+ <para>All this behavior can be overridden, of course; it simply
+ represents the most common time-saving defaults. For a port
+ requiring multiple distribution files, simply set <makevar>DISTFILES</makevar> explicitly. If only a
+ subset of <makevar>DISTFILES</makevar> are
+ actual extractable archives, then set them up in <makevar>EXTRACT_ONLY</makevar>, which will override
+ the <makevar>DISTFILES</makevar> list when
+ it comes to extraction, and the rest will be just left in
+ <makevar>DISTDIR</makevar> for later
+ use.</para>
+
+ </sect3>
+
+ <sect3>
+ <title><makevar>PKGNAME</makevar></title>
+
+ <para>If <makevar>DISTNAME</makevar> does not conform to our <link
+ linkend="porting-pkgname">guidelines for a good package
+ name</link>, you should set the <makevar>PKGNAME</makevar>
+ variable to something better. See the abovementioned guidelines
+ for more details.</para>
+ </sect3>
+
+ <sect3>
+ <title><makevar>CATEGORIES</makevar></title>
+
+ <para>When a package is created, it is put under
+ <filename>/usr/ports/packages/All</filename> and links are
+ made from one or more subdirectories of
+ <filename>/usr/ports/packages</filename>. The names of these
+ subdirectories are specified by the variable <makevar>CATEGORIES</makevar>. It is intended to
+ make life easier for the user when he is wading through the
+ pile of packages on the ftp site or the CD-ROM. Please take a
+ look at the existing <link
+ linkend="porting-categories">categories</link> and pick the
+ ones that are suitable for your port.</para>
+
+ <para>This list also determines where in the ports tree the port
+ is imported. If you put more than one category here, it is
+ assumed that the port files will be put in the subdirectory with
+ the name in the first category. See the <link
+ linkend="porting-categories">categories</link> section for
+ more discussion about how to pick the right categories.</para>
+
+ <para>If you port truly belongs to something that is different
+ from all the existing ones, you can even create a new category
+ name. In that case, please send mail to the &a.ports; to propose
+ a new category.</para>
+
+ <note>
+ <para>There is no error checking for category
+ names. <command>make package</command> will happily create a
+ new directory if you mustype the category name, so be
+ careful!</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><makevar>MASTER_SITES</makevar></title>
+
+ <para>Record the directory part of the ftp/http-URL pointing at
+ the original tarball in <makevar>MASTER_SITES</makevar>. Do not forget the
+ trailing slash (<filename>/</filename>)!</para>
+
+ <para>The <command>make</command> macros will try to use this specification for
+ grabbing the distribution file with <makevar>FETCH</makevar> if they cannot find it
+ already on the system.</para>
+
+ <para>It is recommended that you put multiple sites on this
+ list, preferably from different continents. This will
+ safeguard against wide-area network problems, and we are even
+ planning to add support for automatically determining the
+ closest master site and fetching from there!</para>
+
+ <para>If the original tarball is part of one of the following
+ popular archives: X-contrib, GNU, Perl CPAN, TeX CTAN, or
+ Linux Sunsite, you refer to those sites in an easy compact
+ form using <makevar>MASTER_SITE_XCONTRIB</makevar>, <makevar>MASTER_SITE_GNU</makevar>,
+ <makevar>MASTER_SITE_PERL_CPAN</makevar>, <makevar>MASTER_SITE_TEX_CTAN</makevar>, and
+ <makevar>MASTER_SITE_SUNSITE</makevar>. Simply set <makevar>MASTER_SITE_SUBDIR</makevar> to the
+ path with in the archive. Here is an example:</para>
+
+ <programlisting>
+MASTER_SITES= ${MASTER_SITE_XCONTRIB}
+MASTER_SITE_SUBDIR= applications</programlisting>
+
+ <para>The user can also set the <makevar>MASTER_SITE_*</makevar> variables in
+ <filename>/etc/make.conf</filename> to override our choices,
+ and use their favorite mirrors of these popular archives
+ instead.</para>
+
+ </sect3>
+
+ <sect3 id="porting-patchfiles">
+ <title><makevar>PATCHFILES</makevar></title>
+
+ <para>If your port requires some additional patches that are
+ available by ftp or http, set <makevar>PATCHFILES</makevar> to the names of the
+ files and <makevar>PATCH_SITES</makevar> to
+ the URL of the directory that contains them (the format is the
+ same as <makevar>MASTER_SITES</makevar>).</para>
+
+ <para>If the patch is not relative to the top of the source tree
+ (i.e., <makevar>WKRSRC</makevar>) because it
+ contains some extra pathnames, set <makevar>PATCH_DIST_STRIP</makevar> accordingly.
+ For instance, if all the pathnames in the patch has an extra
+ <literal>foozolix-1.0/</literal> in front of the
+ filenames, then set
+ <literal>PATCH_DIST_STRIP=-p1</literal>.</para>
+
+ <para>Do not worry if the patches are compressed, they will be
+ decompressed automatically if the filenames end with
+ <filename>.gz</filename> or
+ <filename>.Z</filename>.</para>
+
+ <para>If the patch is distributed with some other files, such as
+ documentation, in a gzip'd tarball, you can't just use
+ <makevar>PATCHFILES</makevar>. If that is
+ the case, add the name and the location of the patch tarball
+ to <makevar>DISTFILES</makevar> and
+ <makevar>MASTER_SITES</makevar>. Then, from
+ the <maketarget>pre-patch</maketarget> target, apply the
+ patch either by running the patch command from there, or
+ copying the patch file into the <makevar>PATCHDIR</makevar> directory and calling it
+ <filename>patch-<replaceable>xx</replaceable></filename>.</para>
+
+ <note>
+ <para>Note the tarball will have been extracted alongside the
+ regular source by then, so there is no need to explicitly
+ extract it if it is a regular gzip'd or compress'd tarball.
+ If you do the latter, take extra care not to overwrite
+ something that already exists in that directory. Also do
+ not forget to add a command to remove the copied patch in
+ the <maketarget>pre-clean</maketarget> target.</para>
+ </note>
+
+ </sect3>
+
+ <sect3>
+ <title><makevar>MAINTAINER</makevar></title>
+
+ <para>Set your mail-address here. Please. <!-- smiley --><emphasis>:)</emphasis></para>
+
+ <para>For detailed description of the responsibility of
+ maintainers, refer to <link
+ linkend="policies-maintainer">MAINTAINER
+ on Makefiles</link> section.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Dependencies</title>
+
+ <para>Many ports depend on other ports. There are five
+ variables that you can use to ensure that all the required
+ bits will be on the user's machine. There are also some
+ pre-supported dependency variables for common cases, plus a few
+ more to control the behaviour of dependencies.</para>
+
+
+ <sect4>
+ <title><makevar>LIB_DEPENDS</makevar></title>
+
+ <para>This variable specifies the shared libraries this port
+ depends on. It is a list of <replaceable>lib</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples where
+ <replaceable>lib</replaceable> is the name of the shared library,
+ and <replaceable>dir</replaceable> is the directory in which to
+ find it in case it is not available, and
+ <replaceable>target</replaceable> is the target to call in
+ that directory. For example,
+
+ <programlisting>
+LIB_DEPENDS= jpeg\\.9\\.:${PORTSDIR}/graphics/jpeg:install</programlisting>
+
+ will check for a shared jpeg library with
+ major version 9, and descend into the
+ <filename>graphics/jpeg</filename> subdirectory of your
+ ports tree to build and install it if it is not
+ found. The <replaceable>target</replaceable> part can be
+ omitted if it is equal to <makevar>DEPENDS_TARGET</makevar>
+ (which defaults to <literal>install</literal>).</para>
+
+ <note>
+ <para>The <replaceable>lib</replaceable> part is an argument
+ given to <command>ldconfig -r | grep -wF</command>. There
+ shall be no reqular expressions in this variable.</para>
+ </note>
+
+ <para>The dependency is checked twice, once from within the
+ <maketarget>extract</maketarget> target and then from within
+ the <maketarget>install</maketarget> target. Also, the name of the
+ dependency is put in to the package so that
+ <command>pkg_add</command> will automatically install it if it
+ is not on the user's system.</para>
+
+ </sect4>
+
+ <sect4>
+ <title><makevar>RUN_DEPENDS</makevar></title>
+
+ <para>This variable specifies executables or files this port
+ depends on during run-time. It is a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples where
+ <replaceable>path</replaceable> is the name of the executable or
+ file, and <replaceable>dir</replaceable> is the directory in which
+ to find it in case it is not available, and
+ <replaceable>target</replaceable> is the target to call in
+ that directory. If
+ <replaceable>path</replaceable> starts with a slash
+ (<literal>/</literal>), it is treated as a file and its
+ existence is tested with <command>test -e</command>;
+ otherwise, it is assumed to be an executable, and
+ <command>which -s</command> is used to determine if the
+ program exists in the user's search path.</para>
+
+ <para>For example,
+
+ <programlisting>
+RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \
+ wish8.0:${PORTSDIR}/x11-toolkits/tk80</programlisting>
+
+ will check if the file or directory
+ <filename>/usr/local/etc/innd</filename> exists, and build
+ and install it from the <filename>news/inn</filename>
+ subdirectory of the ports tree if it is not found. It will
+ also see if an executable called <command>wish8.0</command> is in your search path, and
+ descend into the <filename>x11-toolkits/tk80</filename> subdirectory of
+ your ports tree to build and install it if it is not
+ found.</para>
+
+ <note>
+ <para>In this case, <command>innd</command> is actually an
+ executable; if an executable is in a place that is not
+ expected to be in a normal user's search path, you should
+ use the full pathname.</para>
+ </note>
+
+ <para>The dependency is checked from within the <maketarget>install</maketarget> target. Also, the name of the
+ dependency is put in to the package so that
+ <command>pkg_add</command> will automatically install it if it
+ is not on the user's system. The
+ <replaceable>target</replaceable> part can be omitted if it is
+ the same <makevar>DEPENDS_TARGET</makevar>.</para>
+
+ </sect4>
+
+ <sect4>
+ <title><makevar>BUILD_DEPENDS</makevar></title>
+
+ <para>This variable specifies executables or files this port
+ requires to build. Like <makevar>RUN_DEPENDS</makevar>, it is
+ a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples.
+ For example,
+
+ <programlisting>
+BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>
+
+ will check for an executable called
+ <command>unzip</command>, and descend into the
+ <filename>archivers/unzip</filename> subdirectory of your
+ ports tree to build and install it if it is not
+ found.</para>
+
+ <note>
+ <para>“build” here means everything from extracting to
+ compilation. The dependency is checked from within the
+ <maketarget>extract</maketarget> target. The
+ <replaceable>target</replaceable> part can be omitted if it
+ is the same as <makevar>DEPENDS_TARGET</makevar></para>
+ </note>
+ </sect4>
+
+ <sect4>
+ <title><makevar>FETCH_DEPENDS</makevar></title>
+
+ <para>This variable specifies executables or files this port
+ requires to fetch. Like the previous two, it is a list of
+ <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples. For
+ example,
+
+ <programlisting>
+FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting>
+
+ will check for an executable called
+ <command>ncftp2</command>, and descend into the
+ <filename>net/ncftp2</filename> subdirectory of your ports
+ tree to build and install it if it is not found.</para>
+
+ <para>The dependency is checked from within the
+ <maketarget>fetch</maketarget> target. The
+ <replaceable>target</replaceable> part can be omitted if it is
+ the same as <makevar>DEPENDS_TARGET</makevar>.</para>
+
+ </sect4>
+
+ <sect4>
+ <title><makevar>DEPENDS</makevar></title>
+
+ <para>If there is a dependency that does not fall into either
+ of the above four categories, or your port requires to have
+ the source of the other port extracted in addition to having
+ them installed, then use this variable. This is a list of
+ <replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional>, as there is nothing to check, unlike the previous four. The <replaceable>target</replaceable> part can be omitted if it is the same as <makevar>DEPENDS_TARGET</makevar>.</para>
+ </sect4>
+
+ <sect4>
+ <title>Common dependency variables</title>
+
+ <para>Define <literal>USE_XLIB=yes</literal> if your port
+ requires the X Window System to be installed (it is implied by
+ <makevar>USE_IMAKE</makevar>). Define
+ <literal>USE_GMAKE=yes</literal> if your port requires GNU
+ <command>make</command> instead of BSD
+ <command>make</command>. Define
+ <literal>USE_AUTOCONF=yes</literal> if your port requires GNU
+ autoconf to be run. Define <literal>USE_QT=yes</literal> if
+ your port uses the latest qt toolkit. Use
+ <literal>USE_PERL5=yes</literal> if your port requires version
+ 5 of the perl language. (The last is especially important since
+ some versions of FreeBSD has perl5 as part of the base system
+ while others don't.)</para>
+ </sect4>
+
+ <sect4>
+ <title>Notes on dependencies</title>
+
+ <para>As mentioned above, the default target to call when a
+ dependency is required is
+ <maketarget>DEPENDS_TARGET</maketarget>. It defaults to
+ <literal>install</literal>. This is a user variable; is is
+ never defined in a port's <filename>Makefile</filename>. If
+ your port needs a special way to handle a dependency, use the
+ <literal>:target</literal> part of the
+ <makevar>*_DEPENDS</makevar> variables instead of redefining
+ <makevar>DEPENDS_TARGET</makevar>.</para>
+
+ <para>When you type <command>make clean</command>, its
+ dependencies are automatically cleaned too. If you do not wish
+ this to happen, define the variable
+ <makevar>NOCLEANDEPENDS</makevar> in your environment.</para>
+
+ <para>To depend on another port unconditionally, it is customary
+ to use the string <literal>nonexistent</literal> as the first
+ field of <makevar>BUILD_DEPENDS</makevar> or
+ <makevar>RUN_DEPENDS</makevar>. Use this only when you need to
+ the to get to the source of the other port. You can often save
+ compilation time by specifying the target too. For
+ instance
+
+ <programlisting>
+BUILD_DEPENDS= /nonexistent:${PORTSDIR}/graphics/jpeg:extract</programlisting>
+
+ will always descend to the JPEG port and extract it.</para>
+
+ <para>Do not use <makevar>DEPENDS</makevar> unless there is no
+ other way the behaviour you want can be accomplished. It will
+ cause the other port to be always build (and installed, by
+ default), and the dependency will go into the packages as
+ well. If this is really what you need, I recommend you to
+ write it as <literal>BUILD_DEPENDS</literal> and
+ <literal>RUN_DEPENDS</literal> instead—at least the
+ intention will be clear.</para>
+ </sect4>
+ </sect3>
+
+ <sect3>
+ <title>Building mechanisms</title>
+
+ <para>If your package uses GNU <command>make</command>, set
+ <literal>USE_GMAKE=yes</literal>. If your package uses
+ <command>configure</command>, set
+ <literal>HAS_CONFIGURE=yes</literal>. If your package uses GNU
+ <command>configure</command>, set
+ <literal>GNU_CONFIGURE=yes</literal> (this implies
+ <literal>HAS_CONFIGURE</literal>). If you want to give some
+ extra arguments to <command>configure</command> (the default
+ argument list <literal>--prefix=${PREFIX}</literal> for
+ GNU <command>configure</command> and empty for non-GNU
+ <command>configure</command>), set those extra arguments in
+ <makevar>CONFIGURE_ARGS</makevar>. If your package uses GNU
+ <command>autoconf</command>, set
+ <literal>USE_AUTOCONF=yes</literal>. This implies
+ <makevar>GNU_CONFIGURE</makevar>, and will cause
+ <command>autoconf</command> to be run before
+ <command>configure</command>.</para>
+
+ <para>If your package is an X application that creates
+ <filename>Makefile</filename>s from
+ <filename>Imakefile</filename>s using <command>imake</command>, then set
+ <literal>USE_IMAKE=yes</literal>. This will cause the
+ configure stage to automatically do an <command>xmkmf
+ -a</command>. If the <option>-a</option> flag is a
+ problem for your port, set
+ <literal>XMKMF=xmkmf</literal>.
+ If the port uses <command>imake</command> but does not understand the
+ <maketarget>install.man</maketarget> target,
+ <literal>NO_INSTALL_MANPAGES=yes</literal> should be set.
+ In addition, the author of the original port should be shot.
+ <!-- smiley --><emphasis>:></emphasis></para>
+
+ <para>If your port's source <filename>Makefile</filename> has
+ something else than <maketarget>all</maketarget> as the main
+ build target, set <makevar>ALL_TARGET</makevar>
+ accordingly. Same goes for <maketarget>install</maketarget> and
+ <makevar>INSTALL_TARGET</makevar>.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Special considerations</title>
+
+ <para>There are some more things you have to take into account when
+ you create a port. This section explains the most common of
+ those.</para>
+
+ <sect3>
+ <title><command>ldconfig</command></title>
+
+ <para>If your port installs a shared library, add a
+ <maketarget>post-install</maketarget> target to your
+ <filename>Makefile</filename> that runs
+ <literal>${LDCONFIG} -m</literal> on the directory where
+ the new library is installed (usually
+ <filename><makevar>PREFIX</makevar>/lib</filename>) to register
+ it into the shared library cache.</para>
+
+ <para>Also, add a matching <literal>@exec /sbin/ldconfig
+ -m</literal> and <literal>@unexec /sbin/ldconfig -R</literal>
+ pair to your <filename>pkg/PLIST</filename> file so that a user
+ who installed the package can start using teh shared libraru
+ immediately and deinstallation will not cause the system to
+ still believe the library is there. These lines should
+ immediately follow the line for the shared library itself, as
+ in:</para>
+
+ <programlisting>
+lib/libtvl80.so.1
+@exec /sbin/ldconfig -m %D/lib
+@unexec /sbin/ldconfig -R</programlisting>
+
+ <para>Never, ever, <emphasis>ever</emphasis> add a line that says
+ <literal>ldconfig</literal> without any arguments to your
+ <filename>Makefile</filename> or
+ <filename>pkg/PLIST</filename>. This will reset the shared
+ libraru cache to the contents of <filename>/usr/lib</filename>
+ only, and will royally screw up the user's machine ("Help, xinit
+ does not run anymore after I install this port!"). Anybody who
+ does this will be shot and cut in 65,536 pieces by a rusty knife
+ and have is liver chopped out by a bunch of crows and will
+ eternally rot to death in the deepest bowels of hell (not
+ necessarily in that order…)</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>ELF support</title>
+
+ <para>Since FreeBSD is moving to ELF from 3.0-release onwards,
+ 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 that there will
+ be one more release (2.2.8) from the 2.2 branch. 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 awhile for reference
+ in case you have come across some old port you wish to
+ upgrade.</para>
+
+ <sect3>
+ <title>Moving a.out libraries out of the way</title>
+
+ <para>A.out libraries should be moved out of
+ <filename>/usr/local/lib</filename> and similar to an
+ <filename>aout</filename> subdirectory. (If you don't move them
+ out of the way, ELF ports will happily overwrite a.out libraries.)
+ The <maketarget>move-aout-libs</maketarget> target in the -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>
+ </sect3>
+
+ <sect3>
+ <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>
+ </sect3>
+
+ <sect3>
+ <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's always going to be
+ <literal>aout</literal> in -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>
+ </sect3>
+
+ <sect3>
+ <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 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>PLIST</filename> too, and it won't 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>
+ </sect3>
+
+ <sect3>
+ <title><makevar>LIB_DEPENDS</makevar></title>
+
+ <para>All port Makefiles 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>
+ </sect3>
+
+ <sect3>
+ <title><filename>PLIST</filename></title>
+
+ <para><filename>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>PLIST</filename> mentioned in the previous
+ paragraph.</para>
+ </sect3>
+
+ <sect3>
+ <title><literal>ldconfig</literal></title>
+
+ <para>The <literal>ldconfig</literal> line in Makefiles should read:</para>
+
+ <programlisting>
+${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....</programlisting>
+
+ <para>In <filename>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>
+ </sect3>
+ </sect2>
+
+ <sect2 id="porting-masterdir">
+ <title><makevar>MASTERDIR</makevar></title>
+
+ <para>If your port needs to build slightly different versions of
+ packages by having a variable (for instance, resolution, or paper
+ size) take different values, create one subdirectory per package
+ to make it easier forusers to see what to do, but try to share as
+ many files as possible between ports. Typically you only need a
+ very short <filename>Makefile</filename> in all but one of the
+ directories if you use variables cleverly. In the sole
+ <filename>Makefiles</filename>, you can use
+ <makevar>MASTERDIR</makevar> to specify the directory where the
+ rest of the files are. Also, use a variable as part of
+ <link linkend="porting-pkgname"><makevar>PKGNAME</makevar></link>
+ so the packages will have different names.</para>
+
+ <para>This will be best demonstrated by an example. This is part of
+ <filename>japanese/xdvi300/Makefile</filename>;</para>
+
+ <programlisting>
+PKGNAME= ja-xdvi${RESOLUTION}-17
+ :
+# 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>japanese/xdvi300</filename> also has all the regular
+ patches, package files, etc. If you type <command>make</command>
+ there, it will take the default value for the resolution (300) and
+ build the port normally.</para>
+
+ <para>As for other resolutions, this is the
+ <emphasis>entire</emphasis>
+ <filename>xdvi118/Makefile</filename>;</para>
+
+ <programlisting>
+RESOLUTION= 118
+MASTERDIR= ${.CURDIR}/../xdvi300
+
+.include ${MASTERDIR}/Makefile</programlisting>
+
+ <para>(<filename>xdvi240/Makefile</filename> and
+ <filename>xdvi400/Makefile</filename> are similar). The
+ <makevar>MASTERDIR</makevar> definition tells
+ <filename>bsd.port.mk</filename> that the refulat set of
+ subdirectories like <makevar>PATCHDIR</makevar> and
+ <makevar>PKGDIR</makevar> are to be found under
+ <filename>xdvi300</filename>. The
+ <literal>RESOLUTION=118</literal> line will override the
+ <literal>RESOLUTION=300</literal> line in
+ <filename>xdvi300/Makefile</filename> and the port will be built
+ with resolution set to 118.</para>
+ </sect2>
+
+ <sect2>
+ <title>Shared library versions</title>
+
+ <para>First, please read our <link linkend="policies-shlib">policy
+ on shared library versioning</link> to understand
+ what to do with shared library versions in general. Do
+ not blindly assume software authors know what they are
+ doing; many of them do not. It is very important that
+ these details are carefully considered, as we have quite a
+ unique situation where we are trying to have dozens of
+ potentially incompatible software pairs co-exist.
+ Careless port imports have caused great trouble regarding
+ shared libraries in the past (ever wondered why the port
+ <filename>jpeg-6b</filename> has a shared library version of 9.0?).
+ If in doubt, send a message to the &a.ports;. Most of the
+ time, your job ends by determining the right shared
+ library version and making appropriate patches to
+ implement it.</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>
+ </sect2>
+
+ <sect2 id="porting-manpages">
+ <title>Manpages</title>
+
+ <para>The <makevar>MAN[1-9LN]</makevar> variables will automatically
+ add any manpages to <filename>pkg/PLIST</filename> (this means you
+ must <emphasis>not</emphasis> list manpages in the
+ <filename>PLIST</filename>—see <link
+ linkend="porting-plist">generating PLIST</link> for more). It
+ also makes the install stage automatically compress or uncompress
+ manpages depending on the setting of
+ <makevar>NOMANCOMPRESS</makevar> in
+ <filename>/etc/make.conf</filename>.</para>
+
+ <para>To specify whether the manpages are compressed upon
+ installation, use the <makevar>MANCOMPRESSED</makevar> variable.
+ This variable can take three values, <literal>yes</literal>,
+ <literal>no</literal> and <literal>maybe</literal>.
+ <literal>yes</literal> means manpages are already installed
+ compressed, <literal>no</literal> means they are not, and
+ <literal>maybe</literal> means the software already respects the
+ value of <makevar>NOMANCOMPRESS</makevar> so
+ <filename>bsd.port.mk</filename> does not have to do anything
+ special.</para>
+
+ <para><makevar>MANCOMPRESSED</makevar> is automatically set to
+ <literal>yes</literal> if <makevar>USE_IMAKE</makevar> is set and
+ <makevar>NO_INSTALL_MANPAGES</makevar> is not set, and to
+ <literal>no</literal> otherwise. You don't have to explicitly
+ define it unless the default is not suitable for your port.</para>
+
+ <para>If your port anchors its man tree somewhere other than
+ <makevar>PREFIX</makevar>, you can use the
+ <makevar>MANPREFIX</makevar> to set it. Also, if only manpages in
+ certain sections go in a non-standard place, such as some Perl
+ modules ports, you can set individual man paths using
+ <makevar>MAN<replaceable>sect</replaceable>PREFIX</makevar> (where
+ <replaceable>sect</replaceable> is one of <literal>1-9</literal>,
+ <literal>L</literal> or <literal>N</literal>).</para>
+
+ <para>If your manpages go to language-specific subdirectories, set
+ the name of the languages to <makevar>MANLANG</makevar>. The
+ value of this variable defaults to <literal>""</literal> (i.e.,
+ English only).</para>
+
+ <para>Here is an example that puts it all together.</para>
+
+ <programlisting>
+MAN1= foo.1
+MAN3= bar.3
+MAN4= baz.4
+MANLANG= "" ja
+MAN3PREFIX= ${PREFIX}/share/foobar
+MANCOMPRESSED= yes</programlisting>
+
+ <para>This states that six files are installed by this 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>
+ </sect2>
+
+ <sect2>
+ <title>Ports that require Motif</title>
+
+ <para>There are many programs that require a Motif library
+ (available from several commercial vendors, while there is
+ a free clone reported to be able to run many applications in
+ <filename>x11-toolkits/lesstif</filename>) to compile. Since
+ it is a popular toolkit and their licenses usually permit
+ redistribution of statically linked binaries, we have made
+ special provisions for handling ports that require Motif in a
+ way that we can easily compile binaries linked either
+ dynamically (for people who are compiling from the port) or
+ statically (for people who distribute packages).</para>
+
+ <sect3>
+ <title><makevar>REQUIRES_MOTIF</makevar></title>
+
+ <para>If your port requires Motif, define this variable in the
+ Makefile. This will prevent people who don't own a copy of
+ Motif from even attempting to build it.</para>
+ </sect3>
+
+ <sect3>
+ <title><makevar>MOTIFLIB</makevar></title>
+
+ <para>This variable will be set by
+ <filename>bsd.port.mk</filename> to be the appropriate reference
+ to the Motif library. Please patch the source to use this
+ wherever the Motif library is referenced in the
+ <filename>Makefile</filename> or
+ <filename>Imakefile</filename>.</para>
+
+ <para>There are two common cases:</para>
+
+ <itemizedlist>
+ <listitem><para>If the port refers to the Motif library as
+ <literal>-lXm</literal> in its <filename>Makefile</filename>
+ or <filename>Imakefile</filename>, simply substitute
+ <literal>${MOTIFLIB}</literal> for
+ it.</para></listitem>
+
+ <listitem><para>If the port uses <literal>XmClientLibs</literal>
+ in its <filename>Imakefile</filename>, change it to
+ <literal>${MOTIFLIB} ${XTOOLLIB}
+ ${XLIB}</literal>.</para></listitem>
+ </itemizedlist>
+
+ <para>Note that <makevar>MOTIFLIB</makevar> (usually) expands to
+ <literal>-L/usr/X11R6/lib -lXm</literal> or
+ <literal>/usr/X11R6/lib/libXm.a</literal>, so there is no need
+ to add <literal>-L</literal> or <literal>-l</literal> in
+ front.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>X11 fonts</title>
+
+ <para>If your port installs fonts for the X Window system, put them
+ in
+ <filename><makevar>X11BASE</makevar>/lib/X11/fonts/local</filename>.
+ This directory is new to XFree86 release 3.3.3. If it does not
+ exist, please create it, and print out a message urging the user
+ to update their XFree86 to 3.3.3 or newer, or at least add this
+ directory to the font path in
+ <filename>/etc/XF86Config</filename>.</para>
+ </sect2>
+
+ <sect2>
+ <title>Info files</title>
+
+ <para>The new version of texinfo (included in 2.2.2-RELEASE and
+ onwards) contains a utility called <command>install-info</command>
+ to add and delete entries to the <filename>dir</filename> file. If
+ your port installs any info documents, please follow this
+ instructions so your port/package will correctly update the user's
+ <filename><makevar>PREFIX</makevar>/info/dir</filename>
+ file. (Sorry for the length of this section, but is it imperative
+ to weave all the info files together. If done correctly, it will
+ produce a <emphasis>beautiful</emphasis> listing, so please bear
+ with me!</para>
+
+ <para>First, this is what you (as a porter) need to know</para>
+
+ <informalexample>
+ <screen>&prompt.user; <userinput>install-info --help</userinput>
+install-info [OPTION]... [INFO-FILE [DIR-FILE]]
+ Install INFO-FILE in the Info directory file DIR-FILE.
+
+Options:
+--delete Delete existing entries in INFO-FILE;
+ don't insert any new entries.
+ :
+--entry=TEXT Insert TEXT as an Info directory entry.
+ :
+--section=SEC Put this file's entries in section SEC of the directory. :</screen>
+ </informalexample>
+
+ <note>
+ <para>This program will not actually
+ <emphasis>install</emphasis> info files; it merely inserts or
+ deletes entries in the <filename>dir</filename> file.</para>
+ </note>
+
+ <para>Here's a seven-step procedure to convert ports to use
+ <command>install-info</command>. I will use
+ <filename>editors/emacs</filename> as an example.</para>
+
+ <procedure>
+ <step>
+ <para>Look at the texinfo sources and make a patch to insert
+ <literal>@dircategory</literal> and <literal>@direntry</literal>
+ statements to files that don't have them. This is part of
+ my patch:</para>
+
+ <programlisting>
+--- ./man/vip.texi.org Fri Jun 16 15:31:11 1995
++++ ./man/vip.texi Tue May 20 01:28:33 1997
+@@ -2,6 +2,10 @@
+
+ @setfilename ../info/vip
+ @settitle VIP
++@dircategory The Emacs editor and associated tools
++@direntry
++* VIP: (vip). A VI-emulation for Emacs.
++@end direntry
+
+ @iftex
+ @finalout
+ :</programlisting>
+
+ <para>The format should be self-explanatory. Many authors
+ leave a <filename>dir</filename> file in the source tree
+ that contains all the entries you need, so look around
+ before you try to write your own. Also, make sure you
+ look into related ports and make the section names and
+ entry indentations consistent (we recommend that all entry
+ text start at the 4th tab stop).</para>
+
+ <note>
+ <para>Note that you can put only one info entry per file
+ because of a bug in <command>install-info
+ --delete</command> that deletes only the first entry
+ if you specify multiple entries in the
+ <email>@direntry</email> section.</para>
+ </note>
+
+ <para>You can give the <literal>dir</literal>
+ entries to <command>install-info</command> as
+ arguments (<option>--section</option> and
+ <option>--entry</option>) instead of patching the texinfo
+ sources. I do not think this is a good idea for ports
+ because you need to duplicate the same information in
+ <emphasis>three</emphasis> places
+ (<filename>Makefile</filename> and
+ <literal>@exec</literal>/<literal>@unexec</literal> of
+ <filename>PLIST</filename>; see below). However, if you
+ have a Japanese (or other multibyte encoding) info files,
+ you will have to use the extra arguments to <command>install-info</command> because <command>makeinfo</command> can't handle those texinfo
+ sources. (See <filename>Makefile</filename> and
+ <filename>PLIST</filename> of
+ <filename>japanese/skk</filename> for examples on how to
+ do this).</para>
+ </step>
+
+ <step>
+ <para>Go back to the port directory and do a <command>make clean; make</command> and verify that
+ the info files are regenerated from the texinfo sources.
+ Since the texinfo sources are newer than the info files,
+ they should be rebuilt when you type <command>make</command>; but many
+ <filename>Makefile</filename>s don't include correct
+ dependencies for info files. In <command>emacs</command>' case, I had to
+ patch the main <filename>Makefile.in</filename> so it will
+ descend into the <filename>man</filename>
+ subdirectory to rebuild the info pages.</para>
+
+ <programlisting>
+--- ./Makefile.in.org Mon Aug 19 21:12:19 1996
++++ ./Makefile.in Tue Apr 15 00:15:28 1997
+@@ -184,7 +184,7 @@
+ # Subdirectories to make recursively. `lisp' is not included
+ # because the compiled lisp files are part of the distribution
+ # and you cannot remake them without installing Emacs first.
+-SUBDIR = lib-src src
++SUBDIR = lib-src src man
+
+ # The makefiles of the directories in $SUBDIR.
+ SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile lwlib/Makefile
+--- ./man/Makefile.in.org Thu Jun 27 15:27:19 1996
++++ ./man/Makefile.in Tue Apr 15 00:29:52 1997
+@@ -66,6 +66,7 @@
+ ${srcdir}/gnu1.texi \
+ ${srcdir}/glossary.texi
+
++all: info
+ info: $(INFO_TARGETS)
+
+ dvi: $(DVI_TARGETS)</programlisting>
+
+ <para>The second hunk was necessary because the default
+ target in the <filename>man</filename> subdir is called
+ <maketarget>info</maketarget>, while the main
+ <filename>Makefile</filename> wants to call <maketarget>all</maketarget>. I also deleted the installation
+ of the <filename>info</filename> info file
+ because we already have one with the same name in
+ <filename>/usr/share/info</filename> (that patch is not
+ shown here).</para>
+ </step>
+
+ <step>
+ <para>If there is a place in the
+ <filename>Makefile</filename> that is installing the
+ <filename>dir</filename> file, delete it. Your
+ port may not be doing it. Also, remove any commands that
+ are otherwise mucking around with the
+ <filename>dir</filename> file.</para>
+
+ <programlisting>
+--- ./Makefile.in.org Mon Aug 19 21:12:19 1996
++++ ./Makefile.in Mon Apr 14 23:38:07 1997
+@@ -368,14 +368,8 @@
+ if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \
+ then \
+ (cd ${infodir}; \
+- if [ -f dir ]; then \
+- if [ ! -f dir.old ]; then mv -f dir dir.old; \
+- else mv -f dir dir.bak; fi; \
+- fi; \
+ cd ${srcdir}/info ; \
+- (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir); \
+- (cd $${thisdir}; chmod a+r ${infodir}/dir); \
+ for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \
+ (cd $${thisdir}; \
+ ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \
+ chmod a+r ${infodir}/$$f); \</programlisting>
+ </step>
+
+ <step>
+ <para>(This step is only necessary if you are modifying an
+ existing port.) Take a look at
+ <filename>pkg/PLIST</filename> and delete anything that is
+ trying to patch up <filename>info/dir</filename>. They
+ may be in <filename>pkg/INSTALL</filename> or some other
+ file, so search extensively.</para>
+
+ <programlisting>
+Index: pkg/PLIST
+===================================================================
+RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v
+retrieving revision 1.15
+diff -u -r1.15 PLIST
+--- PLIST 1997/03/04 08:04:00 1.15
++++ PLIST 1997/04/15 06:32:12
+@@ -15,9 +15,6 @@
+ man/man1/emacs.1.gz
+ man/man1/etags.1.gz
+ man/man1/ctags.1.gz
+-@unexec cp %D/info/dir %D/info/dir.bak
+-info/dir
+-@unexec cp %D/info/dir.bak %D/info/dir
+ info/cl
+ info/cl-1
+ info/cl-2</programlisting>
+ </step>
+
+ <step>
+ <para>Add a <maketarget>post-install</maketarget>
+ target to the <filename>Makefile</filename> to create a
+ <filename>dir</filename> file if it is not there. Also,
+ call <maketarget>install-info</maketarget> with the
+ installed info files.</para>
+
+ <programlisting>
+Index: Makefile
+===================================================================
+RCS file: /usr/cvs/ports/editors/emacs/Makefile,v
+retrieving revision 1.26
+diff -u -r1.26 Makefile
+--- Makefile 1996/11/19 13:14:40 1.26
++++ Makefile 1997/05/20 10:25:09 1.28
+@@ -20,5 +20,11 @@
+ post-install:
+ .for file in emacs-19.34 emacsclient etags ctags b2m
+ strip ${PREFIX}/bin/${file}
+ .endfor
++ if [ ! -f ${PREFIX}/info/dir ]; then \
++ ${SED} -ne '1,/Menu:/p' /usr/share/info/dir > ${PREFIX}/info/dir; \
++ fi
++.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode
++ install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir
++.endfor
+
+ .include <bsd.port.mk></programlisting>
+
+ <para>Do not use anything other than
+ <filename>/usr/share/info/dir</filename> and the above
+ command to create a new info file. In fact, I'd add the
+ first three lines of the above patch to
+ <filename>bsd.port.mk</filename> if you (the porter)
+ wouldn't have to do it in <filename>PLIST</filename> by
+ yourself anyway.</para>
+ </step>
+
+ <step>
+ <para>Edit <filename>PLIST</filename> and add equivalent
+ <literal>@exec</literal> statements and also
+ <literal>@unexec</literal> for <command>pkg_delete</command>.
+ You do not need to delete <filename>info/dir</filename>
+ with <literal>@unexec</literal>.</para>
+
+ <programlisting>
+Index: pkg/PLIST
+===================================================================
+RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v
+retrieving revision 1.15
+diff -u -r1.15 PLIST
+--- PLIST 1997/03/04 08:04:00 1.15
++++ PLIST 1997/05/20 10:25:12 1.17
+@@ -16,7 +14,15 @@
+ man/man1/etags.1.gz
+ man/man1/ctags.1.gz
++@unexec install-info --delete %D/info/emacs %D/info/dir
+ :
++@unexec install-info --delete %D/info/ccmode %D/info/dir
+ info/cl
+ info/cl-1
+@@ -87,6 +94,18 @@
+ info/viper-3
+ info/viper-4
++@exec [ -f %D/info/dir ] || sed -ne '1,/Menu:/p' /usr/share/info/dir > %D/info/dir
++@exec install-info %D/info/emacs %D/info/dir
+ :
++@exec install-info %D/info/ccmode %D/info/dir
+ libexec/emacs/19.34/i386--freebsd/cvtmail
+ libexec/emacs/19.34/i386--freebsd/digest-doc</programlisting>
+
+ <note>
+ <para>The <literal>@unexec install-info
+ --delete</literal> commands have to be listed before
+ the info files themselves so they can read the files.
+ Also, the <literal>@exec install-info</literal> commands
+ have to be after the info files and the
+ <literal>@exec</literal> command that creates the the
+ <filename>dir</filename> file.</para>
+ </note>
+ </step>
+
+ <step>
+ <para><link linkend="porting-testing">Test</link> and admire your work. <!-- smiley --><emphasis>:)</emphasis>. Check the <filename>dir</filename> file before and after each
+ step.</para>
+ </step>
+ </procedure>
+
+ </sect2>
+
+ <sect2>
+ <title>The <filename>pkg/</filename> subdirectory</title>
+
+ <para>There are some tricks we haven't mentioned yet about the
+ <filename>pkg/</filename> subdirectory that come in handy
+ sometimes.</para>
+
+ <sect3 id="porting-message">
+ <title><filename>MESSAGE</filename></title>
+
+ <para>If you need to display a message to the installer, you may
+ place the message in <filename>pkg/MESSAGE</filename>. This
+ capability is often useful to display additional installation
+ steps to be taken after a <command>pkg_add</command> or to display
+ licensing information.</para>
+
+ <note>
+ <para>The <filename>pkg/MESSAGE</filename> file does not need to
+ be added to <filename>pkg/PLIST</filename>. Also, it will not get
+ automatically printed if the user is using the port, not the
+ package, so you should probably display it from the
+ <maketarget>post-install</maketarget> target yourself.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><filename>INSTALL</filename></title>
+
+ <para>If your port needs execute commands when the binary package is
+ installed with <command>pkg_add</command> you can do with via the
+ <filename>pkg/INSTALL</filename> script. This script will
+ automatically be added to the package, and will be run twice by
+ <command>pkg_add</command>. The first time will as
+ <literal>INSTALL ${PKGNAME} PRE-INSTALL</literal> and the
+ second time as <literal>INSTALL ${PKGNAME}
+ POST-INSTALL</literal>. <literal>$2</literal> can be
+ tested to determine which mode the script is being run in. The
+ <envar>PKG_PREFIX</envar> environmental variable will be set to
+ the package installation directory. See <citerefentry>
+ <refentrytitle>pkg_add</refentrytitle>
+ <manvolnum>1</manvolnum></citerefentry> for additional
+ information.</para>
+
+ <note>
+ <para>This script is not run automatically if you install the port
+ with <command>make install</command>. If you are depending on
+ it being run, you will have to explicitly call it on your port's
+ <filename>Makefile</filename>.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><filename>REQ</filename></title>
+
+ <para>If your port needs to determine if it should install or not,
+ you can create a <filename>pkg/REQ</filename>
+ “requirements” script. It will be invoked
+ automatically at installation/deinstallation time to determine
+ whether or not installation/deinstallation should proceed.</para>
+ </sect3>
+
+ <sect3 id="porting-plist">
+ <title>Changing <filename>PLIST</filename> based on make variables</title>
+
+ <para>Some ports, particularly the p5- ports, need to change their
+ <filename>PLIST</filename> depending on what options they are
+ configured with (or version of perl, in the case of p5- ports). To
+ make this easy, any instances in the <filename>PLIST</filename> of
+ <literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal>, and
+ <literal>%%PERL_VERSION%%</literal> will be substituted for
+ appropriately. The value of <literal>%%OSREL%%</literal> is the
+ numeric revision of the operating system (e.g.,
+ <literal>2.2.7</literal>). <literal>%%PERL_VERSION%%</literal> is
+ the full version number of perl (e.g., <literal>5.00502</literal>)
+ and <literal>%%PERL_VER%%</literal> is the perl version number
+ minus the patchlevel (e.g., <literal>5.005</literal>).</para>
+
+ <para>If you need to make other substitutions, you can set the
+ <makevar>PLIST_SUB</makevar> variable with a list of
+ <literal><replaceable>VAR</replaceable>=<replaceable>VALUE</replaceable></literal>
+ pairs and instances of
+ <literal>%%<replaceable>VAR</replaceable>%%</literal>' will be
+ substituted with <replaceable>VALUE</replaceable> in the
+ <filename>PLIST</filename>.</para>
+
+ <para>For instance, if you have a port that installs many files in
+ a version-specific subdirectory, you can put something
+ like
+
+ <programlisting>
+OCTAVE_VERSION= 2.0.13
+PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
+
+ in the <filename>Makefile</filename> and use
+ <literal>%%OCTAVE_VERSION%%</literal> wherever the version shows
+ up in <filename>PLIST</filename>. That way, when you upgrade the
+ port, you will not have to change dozens (or in some cases,
+ hundreds) of lines in the <filename>PLIST</filename>.</para>
+
+ <para>This substitution (as well as addition of any <link
+ linkend="porting-manpages">man pages</link>) will be done
+ between the <maketarget>do-install</maketarget> and
+ <maketarget>post-install</maketarget> targets, by reading from
+ <makevar>PLIST</makevar> and writing to
+ <makevar>TMPPLIST</makevar> (default:
+ <filename><makevar>WRKDIR</makevar>/.PLIST.mktmp</filename>). So
+ if your port builds <makevar>PLIST</makevar> on the fly, do so in
+ or before <maketarget>do-install</maketarget>. Also, if your port
+ needs to edit the resulting file, do so in
+ <maketarget>post-install</maketarget> to a file named
+ <makevar>TMPPLIST</makevar>.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Licensing Problems</title>
+
+ <para>Some software packages have restrictive licenses or can be
+ in violation to the law (PKP's patent on public key crypto, ITAR
+ (export of crypto software) to name just two of them). What we
+ can do with them vary a lot, depending on the exact wordings of
+ the respective licenses.</para>
+
+ <note>
+ <para>It is your responsibility as a porter to read the
+ licensing terms of the software and make sure that the FreeBSD
+ project will not be held accountable of violating them by
+ redistributing the source or compiled binaries either via ftp
+ or CD-ROM. If in doubt, please contact the &a.ports;.</para>
+ </note>
+
+ <para>There are two variables you can set in the Makefile to
+ handle the situations that arise frequently:</para>
+
+
+ <orderedlist>
+
+ <listitem>
+ <para>If the port has a “do not sell for profit” type of
+ license, set the variable <makevar>NO_CDROM</makevar> to a
+ string describing the reason why. We
+ will make sure such ports won't go into the CD-ROM come
+ release time. The distfile and package will still be
+ available via ftp.</para>
+ </listitem>
+
+ <listitem>
+ <para>If the resulting package needs to be built uniquely
+ for each site, or the resulting binary package can't be
+ distributed due to licensing; set the variable
+ <makevar>NO_PACKAGE</makevar> to a string describing the
+ reason why. We will make sure such
+ packages won't go on the ftp site, nor into the CD-ROM
+ come release time. The distfile will still be included on
+ both however.</para>
+ </listitem>
+
+ <listitem>
+ <para>If the port has legal restrictions on who can use it
+ (e.g., crypto stuff) or has a “no commercial use” license,
+ set the variable <makevar>RESTRICTED</makevar> to be the
+ string describing the reason why. For such ports, the
+ distfiles/packages will not be available even from our ftp
+ sites.</para>
+ </listitem>
+
+ </orderedlist>
+
+
+ <note>
+ <para>The GNU General Public License (GPL), both version 1
+ and 2, should not be a problem for ports.</para>
+ </note>
+
+ <note>
+ <para>If you are a committer, make sure you update the
+ <filename>ports/LEGAL</filename> file too.</para>
+ </note>
+ </sect2>
+
+ <sect2>
+ <title>Upgrading</title>
+
+ <para>When you notice that a port is out of date compared to the
+ latest version from the original authors, first make sure you
+ have the latest port. You can find them in the
+ <filename>ports-current</filename> directory of the ftp mirror
+ sites.</para>
+
+ <para>The next step is to send a mail to the maintainer, if one is
+ listed in the port's <filename>Makefile</filename>. That person may already be
+ working on an upgrade, or have a reason to not upgrade the port
+ right now (because of, for example, stability problems of the
+ new version).</para>
+
+ <para>If the maintainer asks you to do the upgrade or there isn't
+ any such person to begin with, please make the upgrade and send
+ the recursive diff (either unified or context diff is fine, but
+ port committers appear to prefer unified diff more) of the new
+ and old ports directories to us (e.g., if your modified port
+ directory is called <filename>superedit</filename>
+ and the original as in our tree is
+ <filename>superedit.bak</filename>, then send us the result of
+ <command>diff -ruN superedit.bak
+ superedit</command>). Please examine the output to make
+ sure all the changes make sense. The best way to send us the
+ diff is by including it to <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ (category <literal>ports</literal>). Please mention any added or deleted files
+ in the message, as they have to be explicitly specified to CVS
+ when doing a commit. If the diff is more than about 20KB, please
+ compress and uuencode it; otherwise, just include it in as is in
+ the PR.</para>
+
+ </sect2>
+
+ <sect2>
+ <title><anchor id="porting-dads">Do's and Dont's</title>
+
+ <para>Here is a list of common do's and dont's that you encounter
+ during the porting process.You should check your own port
+ against this list, but you can also check ports in the PR
+ database that others have submitted. Submit any comments on
+ ports you check as described in <link linkend="contrib-general">Bug
+ Reports and General Commentary</link>. Checking ports in
+ the PR database will both make it faster for us to commit them,
+ and prove that you know what you are doing.</para>
+
+ <sect3>
+ <title>Strip Binaries</title>
+
+ <para>Do strip binaries. If the original source already strips the
+ binaries, fine; otherwise you should add a
+ <literal>post-install</literal> rule to to it yourself. Here is an
+ example;</para>
+
+ <programlisting>
+post-install:
+ strip ${PREFIX}/bin/xdl</programlisting>
+
+ <para>Use the <citerefentry>
+ <refentrytitle>file</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry> command on the installed executable to check
+ whether the binary is stripped or not. If it does not say
+ <literal>not stripped</literal>, it is stripped.</para>
+ </sect3>
+
+ <sect3>
+ <title>INSTALL_* macros</title>
+
+ <para>Do use the macros provided in <filename>bsd.port.mk</filename>
+ to ensure correct modes and ownership of files in your own
+ <maketarget>*-install</maketarget> targets. They are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><makevar>INSTALL_PROGRAM</makevar> is a command to install
+ binary executables.</para>
+ </listitem>
+
+ <listitem>
+ <para><makevar>INSTALL_SCRIPT</makevar> is a command to install
+ executable scripts.</para>
+ </listitem>
+
+ <listitem>
+ <para><makevar>INSTALL_DATA</makevar> is a command to install
+ sharable data.</para>
+ </listitem>
+
+ <listitem>
+ <para><makevar>INSTALL_MAN</makevar> is a command to install
+ manpages and other documentation (it doesn't compress
+ anything).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>These are basically the <command>install</command> command
+ with all the appropriate flags. See below for an example on how
+ to use them.</para>
+ </sect3>
+
+ <sect3 id="porting-versions">
+ <title>Differentiating operating systems and OS versions</title>
+
+ <para>You may come across code that needs modifications or
+ conditional compilation based upon what version of UNIX it is
+ running under. If you need to make such changes to the code for
+ conditional compilation, make sure you make the changes as general
+ as possible so that we can back-port code to FreeBSD 1.x systems
+ and cross-port to other BSD systems such as 4.4BSD from CSRG,
+ BSD/386, 386BSD, NetBSD, and OpenBSD.</para>
+
+ <para>The preferred way to tell 4.3BSD/Reno (1990) and newer
+ versions of the BSD code apart is by using the
+ <literal>BSD</literal> macro defined in
+ <filename><sys/param.h></filename>. Hopefully that file is
+ already included; if not, add the code:</para>
+
+ <programlisting>
+#if (defined(__unix__) || defined(unix)) && !defined(USG)
+#include <sys/param.h>
+#endif</programlisting>
+
+ <para>to the proper place in the <filename>.c</filename> file. We
+ believe that every system that defines these to symbols has
+ <filename>sys/param.h</filename>. If you find a system that
+ doesn't, we would like to know. Please send mail to the
+ &a.ports;.</para>
+
+ <para>Another way is to use the GNU Autoconf style of doing
+ this:</para>
+
+ <programlisting>
+#ifdef HAVE_SYS_PARAM_H
+#include <sys/param.h>
+#endif</programlisting>
+
+ <para>Don't forget to add <literal>-DHAVE_SYS_PARAM_H</literal> to
+ the <makevar>CFLAGS</makevar> in the <filename>Makefile</filename>
+ for this method.</para>
+
+ <para>Once you have <filename>sys/param.h</filename>
+ included, you may use:</para>
+
+ <programlisting>
+#if (defined(BSD) && (BSD >= 199103))</programlisting>
+
+ <para>to detect if the code is being compiled on a 4.3 Net2 code
+ base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD,
+ BSD/386 1.1 and below).</para>
+
+ <para>Use:</para>
+
+ <programlisting>
+#if (defined(BSD) && (BSD >= 199306))</programlisting>
+
+ <para>to detect if the code is being compiled on a 4.4 code base
+ or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or
+ above).</para>
+
+ <para>The value of the <literal>BSD</literal> macro is
+ <literal>199506</literal> for the 4.4BSD-Lite2 code base. This is
+ stated for informational purposes only. It should not be used to
+ distinguish between version of FreeBSD based only on 4.4-Lite vs.
+ versions that have merged in changes from 4.4-Lite2. The
+ <literal>__FreeBSD__</literal> macro should be used
+ instead.</para>
+
+ <para>Use sparingly:</para>
+
+
+ <itemizedlist>
+
+ <listitem>
+ <para><literal>__FreeBSD__</literal> is defined in all
+ versions of FreeBSD. Use it if the change you are making
+ <emphasis>only</emphasis> affects FreeBSD. Porting gotchas like the use of
+ <literal>sys_errlist[]</literal> vs
+ <function>strerror()</function> are Berkeleyisms, not
+ FreeBSD changes.</para>
+ </listitem>
+
+ <listitem>
+ <para>In FreeBSD 2.x, <literal>__FreeBSD__</literal> is
+ defined to be <literal>2</literal>. In earlier
+ versions, it is <literal>1</literal>. Later
+ versions will bump it to match their major version number.</para>
+ </listitem>
+
+ <listitem>
+ <para>If you need to tell the difference between a FreeBSD
+ 1.x system and a FreeBSD 2.x or 3.x system, usually the
+ right answer is to use the <literal>BSD</literal> macros
+ described above. If there actually is a FreeBSD specific
+ change (such as special shared library options when using
+ <command>ld</command>) then it is OK to use
+ <literal>__FreeBSD__</literal> and <literal>#if
+ __FreeBSD__ > 1</literal> to detect a FreeBSD 2.x
+ and later system. If you need more granularity in
+ detecting FreeBSD systems since 2.0-RELEASE you can use
+ the following:</para>
+
+ <programlisting>
+#if __FreeBSD__ >= 2
+#include <osreldate.h>
+# if __FreeBSD_version >= 199504
+ /* 2.0.5+ release specific code here */
+# endif
+#endif</programlisting>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Release</entry>
+ <entry><literal>_FreeBSD_version</literal></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>2.0-RELEASE</entry>
+ <entry>119411</entry>
+ </row>
+
+ <row>
+ <entry>2.1-currents</entry>
+ <entry>199501, 199503</entry>
+ </row>
+
+ <row>
+ <entry>2.0.5-RELEASE</entry>
+ <entry>199504</entry>
+ </row>
+
+ <row>
+ <entry>2.2-current before 2.1</entry>
+ <entry>199508</entry>
+ </row>
+
+ <row>
+ <entry>2.1.0-RELEASE</entry>
+ <entry>199511</entry>
+ </row>
+
+ <row>
+ <entry>2.2-current before 2.1.5</entry>
+ <entry>199512</entry>
+ </row>
+
+ <row>
+ <entry>2.1.5-RELEASE</entry>
+ <entry>199607</entry>
+ </row>
+
+ <row>
+ <entry>2.2-current before 2.1.6</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 (no change)</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.1-RELEASE</entry>
+ <entry>220000 (no change)</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after texinfo-3.9</entry>
+ <entry>221001</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after top</entry>
+ <entry>221002</entry>
+ </row>
+
+ <row>
+ <entry>2.2.2-RELEASE</entry>
+ <entry>222000</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.2-RELEASE</entry>
+ <entry>222001</entry>
+ </row>
+
+ <row>
+ <entry>2.2.5-RELEASE</entry>
+ <entry>225000</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.5-RELEASE</entry>
+ <entry>225001</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after ldconfig -R merge</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-STABLE after 2.2.7-RELEASE</entry>
+ <entry>227001</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after semctl(2) change</entry>
+ <entry>227002</entry>
+ </row>
+
+ <row>
+ <entry>2.2.8-RELEASE</entry>
+ <entry>228000</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.8-RELEASE</entry>
+ <entry>228001</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current before mount(2) change</entry>
+ <entry>300000</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after mount(2) change</entry>
+ <entry>300001</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after semctl(2) change</entry>
+ <entry>300002</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after ioctl arg changes</entry>
+ <entry>300003</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after ELF conversion</entry>
+ <entry>300004</entry>
+ </row>
+
+ <row>
+ <entry>3.0-RELEASE</entry>
+ <entry>300005</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after 3.0-RELEASE</entry>
+ <entry>300006</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </listitem>
+ </itemizedlist>
+
+ <note>
+ <para>Note that 2.2-STABLE sometimes identifies itself as
+ “2.2.5-STABLE” after the 2.2.5-RELEASE. The pattern used to
+ be year followed by the month, but we decided to change it
+ to a more straightforward major/minor system starting from
+ 2.2. This is because the parallel development on several
+ branches made it infeasible to classify the releases simply
+ by their real release dates. If you are making a port now,
+ you don't have to worry about old -current's; they are
+ listed here just for your reference.</para>
+ </note>
+
+
+ <para>In the hundreds of ports that have been done, there have
+ only been one or two cases where <literal>__FreeBSD__</literal>
+ should have been used. Just because an earlier port screwed up
+ and used it in the wrong place does not mean you should do so
+ too.</para>
+ </sect3>
+
+ <sect3>
+ <title>Writing something after
+ <filename>bsd.port.mk</filename></title>
+
+ <para>Do not write anything after the <literal>.include
+ <bsd.port.mk></literal> line. it usually can be avoided by
+ including <filename>bsd.port.pre.mk</filename> somewhere in the
+ middle of your <filename>Makefile</filename> and
+ <filename>bsd.port.post.mk</filename> at the end.</para>
+
+ <note>
+ <para>You need to include either the
+ <filename>pre.mk</filename>/<filename>post.mk</filename> pair or
+ <filename>bsd.port.mk</filename> only; don't mix these
+ two.</para>
+ </note>
+
+ <para><filename>bsd.port.pre.mk</filename> only defines a few
+ variables, which can be used in tests in the
+ <filename>Makefile</filename>,
+ <filename>bsd.port.post.mk</filename> defines the rest.</para>
+
+ <para>Here are some important variables defined in
+ <filename>bsd.port.pre.mk</filename> (this is not the complete
+ list, please read <filename>bsd.port.mk</filename> for the
+ complete list).</para>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Variable</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><makevar>ARCH</makevar></entry>
+ <entry>The architecture as returned by <command>uname
+ -m</command> (e.g., <literal>i386</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>OPSYS</makevar></entry>
+ <entry>The operating system type, as returned by
+ <command>uname -s</command> (e.g.,
+ <literal>FreeBSD</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>OSREL</makevar></entry>
+ <entry>The release version of the operating system (e.g.,
+ <literal>2.1.5</literal> or
+ <literal>2.2.7</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>OSVERSION</makevar></entry>
+ <entry>The numeric version of the operating system, same as
+ <link
+ linkend="porting-versions"><literal>__FreeBSD_version</literal></link>.</entry>
+ </row>
+
+ <row>
+ <entry><makevar>PORTOBJFORMAT</makevar></entry>
+ <entry>The object format of the system
+ (<literal>aout</literal> or <literal>elf</literal></entry>
+ </row>
+
+ <row>
+ <entry><makevar>LOCALBASE</makevar></entry>
+ <entry>The base of the “local” tree (e.g.,
+ <literal>/usr/local/</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>X11BASE</makevar></entry>
+ <entry>The base of the “X11” tree (e.g.,
+ <literal>/usr/X11R6</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>PREFIX</makevar></entry>
+ <entry>Where the port installs itself (see <link
+ linkend="porting-prefix">more on
+ <makevar>PREFIX</makevar></link>).</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <note>
+ <para>If you have to define the variables
+ <makevar>USE_IMAKE</makevar>, <makevar>USE_X_PREFIX</makevar>,
+ or <makevar>MASTERDIR</makevar>, do so before including
+ <filename>bsd.port.pre.mk</filename>.</para>
+ </note>
+
+ <para>Here are some examples of things you can write after
+ <filename>bsd.port.pre.mk</filename>;</para>
+
+ <programlisting>
+# no need to compile lang/perl5 if perl5 is already in system
+.if ${OSVERSION} > 300003
+BROKEN= perl is in system
+.endif
+
+# only one shlib version number for ELF
+.if ${PORTOBJFORMAT} == "elf"
+TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}
+.else
+TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}.${SHLIB_MINOR}
+.endif
+
+# software already makes link for ELF, but not for a.out
+post-install:
+.if ${PORTOBJFORMAT} == "aout"
+ ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so
+.endif</programlisting>
+ </sect3>
+
+ <sect3>
+ <title>Install additional documentation</title>
+
+ <para>If your software has some documentation other than the
+ standard man and info pages that you think is useful for the
+ user, install it under
+ <filename><makevar>PREFIX</makevar>/share/doc</filename>. This can be
+ done, like the previous item, in the <maketarget>post-install</maketarget> target.</para>
+
+ <para>Create a new directory for your port. The directory name
+ should reflect what the port is. This usually means <makevar>PKGNAME</makevar> minus the version part.
+ However, if you think the user might want different versions
+ of the port to be installed at the same time, you can use the
+ whole <makevar>PKGNAME</makevar>.</para>
+
+ <para>Make the installation dependent to the variable
+ <makevar>NOPORTDOCS</makevar> so that users can disable it in
+ <filename>/etc/make.conf</filename>, like this:</para>
+
+ <programlisting>
+post-install:
+.if !defined(NOPORTDOCS)
+ ${MKDIR}${PREFIX}/share/doc/xv
+ ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
+.endif</programlisting>
+
+ <para>Do not forget to add them to
+ <filename>pkg/PLIST</filename> too! (Do not worry about
+ <makevar>NOPORTDOCS</makevar> here; there is currently no way
+ for the packages to read variables from
+ <filename>/etc/make.conf</filename>.)</para>
+
+ <para>Also you can use the <filename>pkg/MESSAGE</filename> file to
+ display messages upon installation. See the <link
+ linkend="porting-message">using
+ <filename>pkg/MESSAGE</filename></link> section for
+ details.</para>
+
+ <note>
+ <para><filename>MESSAGE</filename> does not need to be added
+ to <filename>pkg/PLIST</filename>).</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><makevar>DIST_SUBDIR</makevar></title>
+
+ <para>Do not let your port clutter
+ <filename>/usr/ports/distfiles</filename>. If your port
+ requires a lot of files to be fetched, or contains a file that
+ has a name that might conflict with other ports (e.g.,
+ <filename>Makefile</filename>), set <makevar>DIST_SUBDIR</makevar> to the name of the
+ port (<makevar>PKGNAME</makevar> without the
+ version part should work fine). This will change <makevar>DISTDIR</makevar> from the default
+ <filename>/usr/ports/distfiles</filename> to
+ <filename>/usr/ports/distfiles/<makevar>DIST_SUBDIR</makevar></filename>,
+ and in effect puts everything that is required for your port
+ into that subdirectory.</para>
+
+ <para>It will also look at the subdirectory with the same name
+ on the backup master site at
+ <filename>ftp.freebsd.org</filename>. (Setting <makevar>DISTDIR</makevar> explicitly in your
+ <makevar>Makefile</makevar> will not accomplish this, so please use <makevar>DIST_SUBDIR</makevar>.)</para>
+
+ <note>
+ <para>This does not affect the <makevar>MASTER_SITES</makevar> you define in your
+ Makefile.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>Package information</title>
+
+ <para>Do include package information, i.e.
+ <filename>COMMENT</filename>, <filename>DESCR</filename>, and
+ <filename>PLIST</filename>, in <filename>pkg</filename>.</para>
+
+ <note>
+ <para>Note that these files are not used only for packaging
+ anymore, and are <emphasis>mandatory</emphasis> now, even if
+ <makevar>NO_PACKAGE</makevar> is
+ set.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>RCS strings</title>
+
+ <para>Do not put RCS strings in patches. CVS will mangle them
+ when we put the files into the ports tree, and when we check
+ them out again, they will come out different and the patch
+ will fail. RCS strings are surrounded by dollar (<literal>$</literal>) signs, and typically start with
+ <literal>$Id</literal> or <literal>$RCS</literal>.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Recursive diff</title>
+
+ <para>Using the recurse (<option>-r</option>) option to
+ <command>diff</command> to generate patches is
+ fine, but please take a look at the resulting patches to make
+ sure you don't have any unnecessary junk in there. In
+ particular, diffs between two backup files, <filename>Makefiles</filename> when the
+ port uses <command>Imake</command> or GNU <command>configure</command>, etc., are unnecessary and
+ should be deleted. If you had to edit
+ <filename>configure.in</filename> and run
+ <command>autoconf</command> to regenerate
+ <command>configure</command>, do not take the diffs of
+ <command>configure</command> (it often grows to a few thousand
+ lines!); define <literal>USE_AUTOCONF=yes</literal> and take the
+ diffsof <filename>configure.in</filename>.</para>
+
+ <para>Also, if you had to delete a file, then you
+ can do it in the <maketarget>post-extract</maketarget>
+ target rather than as part of the patch. Once you are happy
+ with the resulting diff, please split it up into one source
+ file per patch file.</para>
+
+ </sect3>
+
+ <sect3 id="porting-prefix">
+ <title><makevar>PREFIX</makevar></title>
+
+ <para>Do try to make your port install relative to <makevar>PREFIX</makevar>. (The value of this
+ variable will be set to <makevar>LOCALBASE</makevar> (default
+ <filename>/usr/local</filename>), unless <makevar>USE_X_PREFIX</makevar> or <makevar>USE_IMAKE</makevar> is set, in which case it
+ will be <makevar>X11BASE</makevar> (default
+ <filename>/usr/X11R6</filename>).)</para>
+
+ <para>Not hard-coding <filename>/usr/local</filename> or
+ <filename>/usr/X11R6</filename> anywhere in the source will
+ make the port much more flexible and able to cater to the
+ needs of other sites. For X ports that use <command>imake</command>, this is
+ automatic; otherwise, this can often be done by simply
+ replacing the occurrences of <filename>/usr/local</filename>
+ (or <filename>/usr/X11R6</filename> for X ports that do not
+ use imake) in the various scripts/Makefiles in the port to
+ read <makevar>PREFIX</makevar>, as this
+ variable is automatically passed down to every stage of the
+ build and install processes.</para>
+
+ <para>Do not set <makevar>USE_X_PREFIX</makevar> unless your port
+ truly require it (i.e., it links against X libs or it needs to
+ reference files in <makevar>X11BASE</makevar>).</para>
+
+ <para>The variable <makevar>PREFIX</makevar>
+ can be reassigned in your <filename>Makefile</filename> or in the user's
+ environment. However, it is strongly discouraged for
+ individual ports to set this variable explicitly in the
+ <filename>Makefiles</filename>.</para>
+
+ <para>Also, refer to programs/files from other ports with the
+ variables mentioned above, not explicit pathnames. For
+ instance, if your port requires a macro
+ <literal>PAGER</literal> to be the full pathname of <command>less</command>, use the compiler flag:
+
+ <programlisting>
+-DPAGER=\"${PREFIX}/bin/less\"</programlisting>
+
+ or
+
+ <programlisting>
+-DPAGER=\"${LOCALBASE}/bin/less\"</programlisting>
+
+ if this is an X port, instead of <literal>-DPAGER=\"/usr/local/bin/less\".</literal> This way it will have a better chance of working if the system administrator has moved the whole `/usr/local' tree somewhere else.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Subdirectories</title>
+
+ <para>Try to let the port put things in the right subdirectories
+ of <makevar>PREFIX</makevar>. Some ports
+ lump everything and put it in the subdirectory with the port's
+ name, which is incorrect. Also, many ports put everything
+ except binaries, header files and manual pages in the a
+ subdirectory of <filename>lib</filename>, which does not
+ bode well with the BSD paradigm. Many of the files should be
+ moved to one of the following: <filename>etc</filename>
+ (setup/configuration files), <filename>libexec</filename>
+ (executables started internally), <filename>sbin</filename>
+ (executables for superusers/managers),
+ <filename>info</filename> (documentation for info browser)
+ or <filename>share</filename> (architecture independent
+ files). See man <citerefentry><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+ details, the rule governing <filename>/usr</filename> pretty
+ much applies to <filename>/usr/local</filename> too. The
+ exception are ports dealing with USENET “news”. They may use
+ <filename><makevar>PREFIX</makevar>/news</filename> as a destination for
+ their files.</para>
+
+ </sect3>
+
+ <sect3 id="porting-cleaning">
+ <title>Cleaning up empty directories</title>
+
+ <para>Do make your ports clean up after themselves when they are
+ deinstalled. This is usually accomplished by adding
+ <literal>@dirrm</literal> lines for all directories that are
+ specifically created by the port. You need to delete
+ subdirectories before you can delete parent directories.</para>
+
+ <programlisting>
+ :
+lib/X11/oneko/pixmaps/cat.xpm
+lib/X11/oneko/sounds/cat.au
+ :
+@dirrm lib/X11/oneko/pixmals
+@dirrm lib/X11/oneko/sounds
+@dirrm lib/X11/oneko</programlisting>
+
+ <para>However, sometimes <literal>@dirrm</literal> will give you
+ errors because other ports also share the same subdirectory. You
+ can call <command>rmdir</command> from <literal>@unexec</literal>
+ to remove only empty directories without warning.</para>
+
+ <programlisting>
+@unexec rmdir %D/share/doc/gimp 2>/dev/null || true</programlisting>
+
+ <para>This will neither print any error messages nor cause
+ <command>pkg_delete</command> to exit abnormally even if
+ <filename><makevar>PREFIX</makevar>/share/doc/gimp</filename> is
+ not empty due to other ports installing some files in there.</para>
+ </sect3>
+
+
+ <sect3>
+ <title>UIDs</title>
+
+ <para>If your port requires a certain user to be on the
+ installed system, let the <filename>pkg/INSTALL</filename>
+ script call <command>pw</command> to create it
+ automatically. Look at <filename>net/cvsup-mirror</filename>
+ for an example.</para>
+
+ <para>If your port must use the same user/group ID number when it is
+ installed a binarypackage as when it was compiled, then you mus
+ choose a free UID from 50 to 99 and register it below. Look at
+ <filename>japanese/Wnn</filename> for an example.</para>
+
+ <para>Make sure you don't use a UID already used by the system
+ or other ports. This is the current list of UIDs between 50
+ and 99.</para>
+
+ <programlisting>
+majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent
+cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent
+gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh
+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:/nonexistent
+wnn:*:69:7:Wnn:/nonexistent:/nonexistent
+ifmail:*:70:66:Ifmail user:/nonexistent:/nonexistent
+pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh
+ircd:*:72:72:IRCd hybrid:/nonexistent:/nonexistent
+alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent
+qmaill:*:83:81:QMail user:/var/qmail:/nonexistent
+qmaild:*:82:81:QMail user:/var/qmail:/nonexistent
+qmailq:*:85:82:QMail user:/var/qmail:/nonexistent
+qmails:*:87:82:QMail user:/var/qmail:/nonexistent
+qmailp:*:84:81:QMail user:/var/qmail:/nonexistent
+qmailr:*:86:82:QMail user:/var/qmail:/nonexistent
+msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh</programlisting>
+
+ <para>Please include a notice when you submit a port (or an
+ upgrade) that reserves a new UID or GID in this range. This allows
+ us to keep the list of reserved IDs up to date.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Do things rationally</title>
+
+ <para>The <filename>Makefile</filename> should do things simply and
+ reasonably. If you can make it a couple of lines shorter or more
+ readable, then do so. Examples include using a make
+ <literal>.if</literal> construct instead of a shell
+ <literal>if</literal> construct, not redefining
+ <maketarget>do-extract</maketarget> if you can redefine
+ <makevar>EXTRACT*</makevar> instead, and using
+ <makevar>GNU_CONFIGURE</makevar> instead of
+ <literal>CONFIGURE_ARGS +=
+ --prefix=${PREFIX}</literal>.</para>
+ </sect3>
+
+ <sect3>
+ <title>Respect <makevar>CFLAGS</makevar></title>
+
+ <para>The port should respect the <makevar>CFLAGS</makevar>
+ variable. If it doesn't, please add <literal>NO_PACKAGE=ignores
+ cflags</literal> to the <filename>Makefile</filename>.</para>
+ </sect3>
+
+ <sect3>
+ <title>Configuration files</title>
+
+ <para>If your port requires some configuration files in
+ <filename><makevar>PREFIX</makevar>/etc</filename>, do
+ <emphasis>not</emphasis> just install them and list them in
+ <filename>pkg/PLIST</filename>. That will cause
+ <command>pkg_delete</command> to delete files carefully edited by
+ the user and a new installation to wipe them out.</para>
+
+ <para>Instead, install sample files with a suffix
+ (<filename><replaceable>filename</replaceable>.sample</filename>
+ will work well) and print out a <link
+ linkend="porting-message">message</link> pointing out that the
+ user has to copy and edit the file before the software can be made
+ to work.</para>
+ </sect3>
+
+ <sect3>
+ <title>Portlint</title>
+
+ <para>Do check your work with <link
+ linkend="porting-portlint"><command>portlint</command></link>
+ before you submit or commit it.</para>
+ </sect3>
+
+ <sect3>
+ <title>Feedback</title>
+
+ <para>Do send applicable changes/patches to the original
+ author/maintainer for inclusion in next release of the code. This
+ will only make your job that much easier for the next
+ release.</para>
+ </sect3>
+
+ <sect3>
+ <title>Miscellanea</title>
+
+ <para>The files <filename>pkg/DESCR</filename>,
+ <filename>pkg/COMMENT</filename>, and
+ <filename>pkg/PLIST</filename> should each be double-checked. If
+ you are reviewing a port and feel they can be worded better, do
+ so.</para>
+
+ <para>Don't copy more copies of the GNU General Public License into
+ our system, please.</para>
+
+ <para>Please be careful to note any legal issues! Don't let us
+ illegally distribute software!</para>
+ </sect3>
+
+ <sect3>
+ <title>If you are stuck…</title>
+
+ <para>Do look at existing examples and the
+ <filename>bsd.port.mk</filename> file before asking us
+ questions! <!-- smiley --><emphasis>;)</emphasis></para>
+
+ <para>Do ask us questions if you have any trouble! Do not just
+ beat your head against a wall! <!-- smiley --><emphasis>:)</emphasis></para>
+
+ </sect3>
+ </sect2>
+
+ <sect2 id="porting-samplem">
+ <title>A Sample <filename>Makefile</filename></title>
+
+ <para>Here is a sample <filename>Makefile</filename> that you can
+ use to create a new port. Make sure you remove all the extra
+ comments (ones between brackets)!</para>
+
+ <para>It is recommended that you follow this format (ordering of
+ variables, empty lines between sections, etc.). This format is
+ designed so that the most important information is easy to
+ locate. We recommend that you use <link
+ linkend="porting-portlint">portlint</link> to check the <filename>Makefile</filename>.</para>
+
+ <programlisting>
+[the header...just to make it easier for us to identify the ports.]
+# New ports collection makefile for: xdvi
+[the version required header should updated when upgrading a port.]
+# Version required: pl18 [things like "1.5alpha" are fine here too]
+[this is the date when the first version of this Makefile was created.
+Never change this when doing an update of the port.]
+# Date created: 26 May 1995
+[this is the person who did the original port to FreeBSD, in particular, the
+person who wrote the first version of this Makefile. Remember, this should
+not be changed when upgrading the port later.]
+# Whom: Satoshi Asami <asami@FreeBSD.ORG>
+#
+# $Id$
+[ ^^^^ This will be automatically replaced with RCS ID string by CVS
+when it is committed to our repository.]
+#
+
+[section to describe the port itself and the master site - DISTNAME
+ is always first, followed by PKGNAME (if necessary), CATEGORIES,
+ and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR.
+ After those, one of EXTRACT_SUFX or DISTFILES can be specified too.]
+DISTNAME= xdvi
+PKGNAME= xdvi-pl18
+CATEGORIES= print
+[do not forget the trailing slash ("/")!
+ if you aren't using MASTER_SITE_* macros]
+MASTER_SITES= ${MASTER_SITE_XCONTRIB}
+MASTER_SITE_SUBDIR= applications
+[set this if the source is not in the standard ".tar.gz" form]
+EXTRACT_SUFX= .tar.Z
+
+[section for distributed patches -- can be empty]
+PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/
+PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz
+
+[maintainer; *mandatory*! This is the person (preferably with commit
+ privileges) who a user can contact for questions and bug reports - this
+ person should be the porter or someone who can forward questions to the
+ original porter reasonably promptly. If you really do not want to have
+ your address here, set it to "ports@FreeBSD.ORG".]
+MAINTAINER= asami@FreeBSD.ORG
+
+[dependencies -- can be empty]
+RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript
+LIB_DEPENDS= Xpm.5:${PORTSDIR}/graphics/xpm
+
+[this section is for other standard bsd.port.mk variables that do not
+ belong to any of the above]
+[If it asks questions during configure, build, install...]
+IS_INTERACTIVE= yes
+[If it extracts to a directory other than ${DISTNAME}...]
+WRKSRC= ${WRKDIR}/xdvi-new
+[If the distributed patches were not made relative to ${WRKSRC}, you
+ may need to tweak this]
+PATCH_DIST_STRIP= -p1
+[If it requires a "configure" script generated by GNU autoconf to be run]
+GNU_CONFIGURE= yes
+[If it requires GNU make, not /usr/bin/make, to build...]
+USE_GMAKE= yes
+[If it is an X application and requires "xmkmf -a" to be run...]
+USE_IMAKE= yes
+[et cetera.]
+
+[non-standard variables to be used in the rules below]
+MY_FAVORITE_RESPONSE= "yeah, right"
+
+[then the special rules, in the order they are called]
+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
+
+[and then the epilogue]
+.include <bsd.port.mk></programlisting>
+
+ </sect2>
+
+ <sect2 id="porting-pkgname">
+ <title>Package Names</title>
+
+ <para>The following are the conventions you should follow in
+ naming your packages. This is to have our package directory
+ easy to scan, as there are already lots and lots of packages and
+ users are going to turn away if they hurt their eyes!</para>
+
+ <para>The package name should look like <filename><replaceable>language-</replaceable>name<replaceable>-compiled.specifics</replaceable><replaceable>-version.numbers</replaceable></filename>.</para>
+
+ <para>If your <makevar>DISTNAME</makevar>
+ doesn't look like that, set <makevar>PKGNAME</makevar> to something in that
+ format.</para>
+
+
+ <orderedlist>
+
+ <listitem>
+ <para>FreeBSD strives to support the native language of its
+ users. The <replaceable>language-</replaceable> part should be a two letter
+ abbreviation of the natural language defined by ISO-639 if
+ the port is specific to a certain language. Examples are
+ <literal>ja</literal> for Japanese, <literal>ru</literal> for Russian, <literal>vi</literal> for Vietnamese,
+ <literal>zh</literal> for Chinese, <literal>ko</literal> for Korean and <literal>de</literal> for German.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <filename>name</filename> part
+ should be all lowercases, except for a really large
+ package (with lots of programs in it). Things like
+ XFree86 (yes there really is a port of it, check it
+ out) and ImageMagick fall into this category. Otherwise,
+ convert the name (or at least the first letter) to
+ lowercase. If the capital letters are
+ important to the name (for example, with one-letter names
+ like <literal>R</literal> or <literal>V</literal>) you may use capital letters at your discretion.
+ There is a tradition of naming Perl 5 modules by prepending
+ <literal>p5-</literal> and converting the double-colon separator to a hyphen;
+ for example, the <literal>Data::Dumper</literal> module becomes
+ <literal>p5-Data-Dumper</literal>. If the software in question has numbers,
+ hyphens, or underscores in its name, you may include them as
+ well (like <literal>kinput2</literal>).</para>
+ </listitem>
+
+ <listitem>
+ <para>If the port can be built with different <link linkend="porting-masterdir">hardcoded
+ defaults</link> (usually part of the directory name in a
+ family of ports), the
+ <replaceable>-compiled.specifics</replaceable> part should state the
+ compiled-in defaults (the hyphen is optional). Examples
+ are papersize and font units.</para>
+ </listitem>
+
+ <listitem>
+ <para>The version string should be a period-separated list
+ of integers and single lowercase alphabetics. The only
+ exception is the string <literal>pl</literal> (meaning `patchlevel'), which
+ can be used <emphasis>only</emphasis> when there are no
+ major and minor version numbers in the software.</para>
+ </listitem>
+
+ </orderedlist>
+
+
+ <para>Here are some (real) examples on how to convert a <makevar>DISTNAME</makevar> into a suitable <makevar>PKGNAME</makevar>:</para>
+
+ <informaltable frame="none">
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Distribution Name</entry>
+ <entry>Package Name</entry>
+ <entry>Reason</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>mule-2.2.2.</entry>
+ <entry>mule-2.2.2</entry>
+ <entry>No changes required</entry>
+ </row>
+
+ <row>
+ <entry>XFree86-3.1.2</entry>
+ <entry>XFree86-3.1.2</entry>
+ <entry>No changes required</entry>
+ </row>
+
+ <row>
+ <entry>EmiClock-1.0.2</entry>
+ <entry>emiclock-1.0.2</entry>
+ <entry>No uppercase names for single programs</entry>
+ </row>
+
+ <row>
+ <entry>gmod1.4</entry>
+ <entry>gmod-1.4</entry>
+ <entry>Need a hyphen before version numbers</entry>
+ </row>
+
+ <row>
+ <entry>xmris.4.0.2</entry>
+ <entry>xmris-4.0.2</entry>
+ <entry>Need a hyphen before version numbers</entry>
+ </row>
+
+ <row>
+ <entry>rdist-1.3alpha</entry>
+ <entry>rdist-1.3a</entry>
+ <entry>No strings like <literal>alpha</literal>
+ allowed</entry>
+ </row>
+
+ <row>
+ <entry>es-0.9-beta1</entry>
+ <entry>es-0.9b1</entry>
+ <entry>No strings like <literal>beta</literal>
+ allowed</entry>
+ </row>
+
+ <row>
+ <entry>v3.3beta021.src</entry>
+ <entry>tiff-3.3</entry>
+ <entry>What the heck was that anyway?</entry>
+ </row>
+
+ <row>
+ <entry>tvtwm</entry>
+ <entry>tvtwm-pl11</entry>
+ <entry>Version string always required</entry>
+ </row>
+
+ <row>
+ <entry>piewm</entry>
+ <entry>piewm-1.0</entry>
+ <entry>Version string always required</entry>
+ </row>
+
+ <row>
+ <entry>xvgr-2.10pl1</entry>
+ <entry>xvgr-2.10.1</entry>
+ <entry><literal>pl</literal> allowed only when no
+ major/minor version numbers</entry>
+ </row>
+
+ <row>
+ <entry>gawk-2.15.6</entry>
+ <entry>ja-gawk-2.15.6</entry>
+ <entry>Japanese language version</entry>
+ </row>
+
+ <row>
+ <entry>psutils-1.13</entry>
+ <entry>psutils-letter-1.13</entry>
+ <entry>Papersize hardcoded at package build time</entry>
+ </row>
+
+ <row>
+ <entry>pkfonts</entry>
+ <entry>pkfonts300-1.0</entry>
+ <entry>Package for 300dpi fonts</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>If there is absolutely no trace of version information in
+ the original source and it is unlikely that the original author
+ will ever release another version, just set the version string
+ to <literal>1.0</literal> (like the piewm example above). Otherwise, ask the
+ original author or use the date string (<literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>) as the
+ version.</para>
+
+ </sect2>
+
+ <sect2 id="porting-categories">
+ <title>Categories</title>
+
+ <para>As you already know, ports are classified in several
+ categories. But for this to wor, it is important that porters and
+ users understand what each category and how we deicde what to put in
+ each category.</para>
+
+ <sect3>
+ <title>Current list of categories</title>
+
+ <para>First, this is the current list of port categories. Those
+ marked with an asterisk (<literal>*</literal>) are
+ <emphasis>virtual</emphasis> categories—those that do not
+ have a corresponding subdirectory in the ports tree.</para>
+
+ <note>
+ <para>For non-virtual categories, you will find a one-line
+ description in the <filename>pkg/COMMENT</filename> file in that
+ subdirectory (e.g.,
+ <filename>archivers/pkg/COMMENT</filename>).</para>
+ </note>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Category</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><filename>archivers</filename></entry>
+ <entry>Archiving tools.</entry>
+ </row>
+
+ <row>
+ <entry><filename>astro</filename></entry>
+ <entry>Astronomical ports.</entry>
+ </row>
+
+ <row>
+ <entry><filename>audio</filename></entry>
+ <entry>Sound support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>benchmarks</filename></entry>
+ <entry>Benchmarking utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>biology</filename></entry>
+ <entry>Biology-related software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>cad</filename></entry>
+ <entry>Computer aided design tools.</entry>
+ </row>
+
+ <row>
+ <entry><filename>chinese</filename></entry>
+ <entry>Chinese language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>comms</filename></entry>
+ <entry>Communication software. Mostly software to talk to
+ your serial port.</entry>
+ </row>
+
+ <row>
+ <entry><filename>converters</filename></entry>
+ <entry>Character code converters.</entry>
+ </row>
+
+ <row>
+ <entry><filename>databases</filename></entry>
+ <entry>Databases.</entry>
+ </row>
+
+ <row>
+ <entry><filename>deskutils</filename></entry>
+ <entry>Things that used to be on the desktop before
+ computers were invented.</entry>
+ </row>
+
+ <row>
+ <entry><filename>devel</filename></entry>
+ <entry>Development utilities. Do not put libraries here just
+ because they are libraries—unless they truly don't
+ belong to anywhere else, they shouldn't be in this
+ category.</entry>
+ </row>
+
+ <row>
+ <entry><filename>editors</filename></entry>
+ <entry>General editors. Specialized editors go in the
+ section for those tools (e.g., a mathematical-formula
+ editor will go in <filename>math</filename>).</entry>
+ </row>
+
+ <row>
+ <entry><filename>elisp</filename></entry>
+ <entry>Emacs-lisp ports.</entry>
+ </row>
+
+ <row>
+ <entry><filename>emulators</filename></entry>
+ <entry>Emulators for other operating systems. Terminal
+ emulators do <emphasis>not</emphasis> belong
+ here—X-based ones should go to
+ <filename>x11</filename> and text-based ones to either
+ <filename>comms</filename> or <filename>misc</filename>,
+ depending on the exact functionality.</entry>
+ </row>
+
+ <row>
+ <entry><filename>games</filename></entry>
+ <entry>Games.</entry>
+ </row>
+
+ <row>
+ <entry><filename>german</filename></entry>
+ <entry>German language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>graphics</filename></entry>
+ <entry>Graphics utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>japanese</filename></entry>
+ <entry>Japanese language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>kde*</filename></entry>
+ <entry>Ports that form the K Desktop Environment
+ (kde).</entry>
+ </row>
+
+ <row>
+ <entry><filename>korean</filename></entry>
+ <entry>Korean language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>lang</filename></entry>
+ <entry>Programming languages.</entry>
+ </row>
+
+ <row>
+ <entry><filename>mail</filename></entry>
+ <entry>Mail software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>math</filename></entry>
+ <entry>Numerical computation software and other utilities
+ for mathematics.</entry>
+ </row>
+
+ <row>
+ <entry><filename>mbone</filename></entry>
+ <entry>MBone applications.</entry>
+ </row>
+
+ <row>
+ <entry><filename>misc</filename></entry>
+ <entry>Miscellaneous utilities—basically things that
+ doesn't belong to anywhere else. This is the only category
+ that should not appear with any other non-virtual
+ category. If you have <literal>misc</literal> with
+ something else in your <makevar>CATEGORIES</makevar> line,
+ that means you can safely delete <literal>misc</literal>
+ and just put the port in that other subdirectory!</entry>
+ </row>
+
+ <row>
+ <entry><filename>net</filename></entry>
+ <entry>Miscellaneous networking software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>news</filename></entry>
+ <entry>USENET news software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>offix*</filename></entry>
+ <entry>Ports from the OffiX suite.</entry>
+ </row>
+
+ <row>
+ <entry><filename>perl5*</filename></entry>
+ <entry>Ports that require perl version 5 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>pilot*</filename></entry>
+ <entry>Software to use with the 3Com PalmPilot.</entry>
+ </row>
+
+ <row>
+ <entry><filename>plan9</filename></entry>
+ <entry>Various programs from Plan9.</entry>
+ </row>
+
+ <row>
+ <entry><filename>print</filename></entry>
+ <entry>Printing software. Desktop publishing tools
+ (previewers, etc.) belong here too.</entry>
+ </row>
+
+ <row>
+ <entry><filename>python*</filename></entry>
+ <entry>Software written in python.</entry>
+ </row>
+
+ <row>
+ <entry><filename>russian</filename></entry>
+ <entry>Russian language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>security</filename></entry>
+ <entry>Security utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>shells</filename></entry>
+ <entry>Command line shells.</entry>
+ </row>
+
+ <row>
+ <entry><filename>sysutils</filename></entry>
+ <entry>System utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl75*</filename></entry>
+ <entry>Ports that use tcl version 7.5 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl76*</filename></entry>
+ <entry>Ports that use tcl version 7.6 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl80*</filename></entry>
+ <entry>Ports that use tcl version 8.0 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl81*</filename></entry>
+ <entry>Ports that use tcl version 8.1 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>textproc</filename></entry>
+ <entry>Text processing utilities. It does not include
+ desktop publishing tools, which go to print/.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk41*</filename></entry>
+ <entry>Ports that use tk version 4.1 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk42*</filename></entry>
+ <entry>Ports that use tk version 4.2 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk80*</filename></entry>
+ <entry>Ports that use tk version 8.0 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk81*</filename></entry>
+ <entry>Ports that use tk version 8.1 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>vietnamese</filename></entry>
+ <entry>Vietnamese language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>www</filename></entry>
+ <entry>Software related to the World Wide Web. HTML language
+ support belong here too.</entry>
+ </row>
+
+ <row>
+ <entry>x11</entry>
+ <entry>The X window system and friends. This category is
+ only for software that directly support the window system.
+ Do not put regular X applications here. If your port is
+ an X application, define <makevar>USE_XLIB</makevar>
+ (implied by <makevar>USE_IMAKE</makevar>) and put it in
+ appropriate categories. Also, many of them go into other
+ <filename>x11-*</filename> categories (see below).</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-clocks</filename></entry>
+ <entry>X11 clocks.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-fm</filename></entry>
+ <entry>X11 file managers.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-fonts</filename></entry>
+ <entry>X11 fonts and font utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-toolkits</filename></entry>
+ <entry>X11 toolkits.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-wm</filename></entry>
+ <entry>X11 window managers.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect3>
+
+ <sect3>
+ <title>Choosing the right category</title>
+
+ <para>As many of the categories overlap, you often have to choose
+ which of the categories should be the primary category of your
+ port. There are several rules that govern this usse. Here is the
+ list of priorities, in decreasing order of precedence.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Language specific categories alwasys come first. For
+ example, if your port installs Japanese X11 fonts, then your
+ <makevar>CATEGORIES</makevar> line would read
+ <literal>japanese x11</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Specific categories win over less-specific ones. For
+ instance, an HTML editor should be listed as <literal>www
+ editors</literal>, not the other way around. Also, you don't
+ need to list <literal>net</literal> when the port belongs to
+ either of <literal>mail</literal>, <literal>mbone</literal>,
+ <literal>news</literal>, <literal>security</literal>, or
+ <literal>www</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>x11</literal> is used as a secondary category
+ only when the primary category is a natural language. In
+ particular, you should not put <literal>x11</literal> in the
+ category line for X applications.</para>
+ </listitem>
+
+ <listitem>
+ <para>If your port truly does not belong anywhere else, put it
+ in <literal>misc</literal>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>If you are not sure about the category, please put a comment
+ to that effect in your <command>send-pr</command> submission so we
+ can discuss it before import it. (If you are a committer, send a
+ note &a.ports; so we can discuss it first—too often new
+ ports are imported to a wrong category only to be moved right
+ away.)</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Changes to this document and the ports system</title>
+
+ <para>If you maintain a lot of ports, you should consider following
+ the &a.ports;. Important changes to
+ the way ports work will be announced there. You can always
+ find more detailed information on the latest changes by
+ looking at <ulink
+ url="http://www.FreeBSD.ORG/cgi/cvsweb.cgi/src/share/mk/bsd.port.mk">
+ the bsd.port.mk CVS log</ulink>.</para>
+ </sect2>
+
+ <sect2>
+ <title>That is It, Folks!</title>
+
+ <para>Boy, this sure was a long tutorial, wasn't it? Thanks for
+ following us to here, really.</para>
+
+ <para>Well, now that you know how to do a port, let us go at it
+ and convert everything in the world into ports! That is the
+ easiest way to start contributing to the FreeBSD Project!
+ <!-- smiley --><emphasis>:)</emphasis></para>
+
+ </sect2>
+ </sect1>
+
</chapter>
@@ -1053,9 +4516,7 @@ grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arc
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/ppp-and-slip/chapter.sgml b/en_US.ISO_8859-1/books/handbook/ppp-and-slip/chapter.sgml
index b0d244ca37..a83def5913 100644
--- a/en_US.ISO_8859-1/books/handbook/ppp-and-slip/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/ppp-and-slip/chapter.sgml
@@ -2561,9 +2561,7 @@ import proto rip interface ed {
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/printing/chapter.sgml b/en_US.ISO_8859-1/books/handbook/printing/chapter.sgml
index f1937d3edf..6bbaf37a71 100644
--- a/en_US.ISO_8859-1/books/handbook/printing/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/printing/chapter.sgml
@@ -2839,13 +2839,13 @@ if [ "$first_two_chars" = "%!" ]; then
#
# PostScript job, print it.
#
- echo $first_line && cat && printf "\004" && exit 0
+ echo "$first_line" && cat && printf "\004" && exit 0
exit 2
else
#
# Plain text, convert it, then print it.
#
- ( echo $first_line; cat ) | /usr/local/bin/textps && printf "\004" && exit 0
+ ( echo "$first_line"; cat ) | /usr/local/bin/textps && printf "\004" && exit 0
exit 2
fi</programlisting>
@@ -2919,7 +2919,7 @@ else
# Plain text or HP/PCL, so just print it directly; print a form
# at the end to eject the last page.
#
- echo $first_line && cat && printf "\f" && exit 0
+ echo "$first_line" && cat && printf "\f" && exit 0
fi
exit 2</programlisting>
@@ -4912,9 +4912,7 @@ total 337.00 154 $ 6.74</screen>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/quotas/chapter.sgml b/en_US.ISO_8859-1/books/handbook/quotas/chapter.sgml
index 9052bb131b..8d9c3de622 100644
--- a/en_US.ISO_8859-1/books/handbook/quotas/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/quotas/chapter.sgml
@@ -239,9 +239,7 @@ Disk quotas for user test (uid 1002):
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/security/chapter.sgml b/en_US.ISO_8859-1/books/handbook/security/chapter.sgml
index b620aeb316..00fcb1dc43 100644
--- a/en_US.ISO_8859-1/books/handbook/security/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/security/chapter.sgml
@@ -1703,9 +1703,7 @@ FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/serialcomms/chapter.sgml b/en_US.ISO_8859-1/books/handbook/serialcomms/chapter.sgml
index 59b6b828f9..c6112d3bcf 100644
--- a/en_US.ISO_8859-1/books/handbook/serialcomms/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/serialcomms/chapter.sgml
@@ -2090,9 +2090,7 @@ raisechar=^^</programlisting>
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/staff/chapter.sgml b/en_US.ISO_8859-1/books/handbook/staff/chapter.sgml
index 350c823cb5..b34fa0411c 100644
--- a/en_US.ISO_8859-1/books/handbook/staff/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/staff/chapter.sgml
@@ -128,14 +128,6 @@
<para>&a.dburr;</para>
</listitem>
- <listitem>
- <para>&a.danny;</para>
- </listitem>
-
- <listitem>
- <para>&a.thepish;</para>
- </listitem>
-
<listitem>
<para>&a.charnier;</para>
</listitem>
@@ -155,7 +147,11 @@
<listitem>
<para>&a.gclarkii;</para>
</listitem>
-
+
+ <listitem>
+ <para>&a.archie</para>
+ </listitem>
+
<listitem>
<para>&a.cracauer;</para>
</listitem>
@@ -212,14 +208,18 @@
<para>&a.jfitz;</para>
</listitem>
- <listitem>
- <para>&a.lars;</para>
- </listitem>
-
<listitem>
<para>&a.scrappy;</para>
</listitem>
+ <listitem>
+ <para>&a.lars;</para>
+ </listitem>
+
+ <listitem>
+ <para>&a.billf;</para>
+ </listitem>
+
<listitem>
<para>&a.tg;</para>
</listitem>
@@ -247,23 +247,35 @@
<listitem>
<para>&a.hanai;</para>
</listitem>
-
+
+ <listitem>
+ <para>&a.thepish;</para>
+ </listitem>
+
<listitem>
<para>&a.jhay;</para>
</listitem>
+ <listitem>
+ <para>&a.helbig;</para>
+ </listitem>
+
<listitem>
<para>&a.ghelmer;</para>
</listitem>
- <listitem>
- <para>&a.helbig;</para>
- </listitem>
-
<listitem>
<para>&a.erich;</para>
</listitem>
+ <listitem>
+ <para>&a.nhibma;</para>
+ </listitem>
+
+ <listitem>
+ <para>&a.flathill;</para>
+ </listitem>
+
<listitem>
<para>&a.hosokawa;</para>
</listitem>
@@ -279,7 +291,11 @@
<listitem>
<para>&a.itojun;</para>
</listitem>
-
+
+ <listitem>
+ <para>&a.mjacob;</para>
+ </listitem>
+
<listitem>
<para>&a.gj;</para>
</listitem>
@@ -319,7 +335,11 @@
<listitem>
<para>&a.jlemon;</para>
</listitem>
-
+
+ <listitem>
+ <para>&a.truckman;</para>
+ </listitem>
+
<listitem>
<para>&a.imp;</para>
</listitem>
@@ -372,6 +392,10 @@
<para>&a.obrien;</para>
</listitem>
+ <listitem>
+ <para>&a.danny;</para>
+ </listitem>
+
<listitem>
<para>&a.ljo;</para>
</listitem>
@@ -391,7 +415,11 @@
<listitem>
<para>&a.jmacd;</para>
</listitem>
-
+
+ <listitem>
+ <para>&a.wes;</para>
+ </listitem>
+
<listitem>
<para>&a.steve;</para>
</listitem>
@@ -435,7 +463,11 @@
<listitem>
<para>&a.dima;</para>
</listitem>
-
+
+ <listitem>
+ <para>&a.sada;</para>
+ </listitem>
+
<listitem>
<para>&a.wosch;</para>
</listitem>
@@ -512,10 +544,6 @@
<para>&a.jmz;</para>
</listitem>
- <listitem>
- <para>&a.hosokawa;</para>
- </listitem>
-
<listitem>
<para>&a.archie;</para>
</listitem>
@@ -536,8 +564,9 @@
<variablelist>
<varlistentry><term>Documentation Project Manager</term>
- <listitem>
- <para><emphasis>currently vacant</emphasis></para>
+
+ <listitem>
+ <para>&a.nik;</para>
</listitem>
</varlistentry>
@@ -545,7 +574,7 @@
<varlistentry><term>Webmaster</term>
<listitem>
- <para>&a.wosch;;</para>
+ <para>&a.wosch;</para>
</listitem>
</varlistentry>
@@ -641,7 +670,7 @@
url="http://www.freebsd.org/docproj/docproj.html">Documentation Project Manager</ulink></term>
<listitem>
- <para><emphasis>currently vacant</emphasis></para>
+ <para>&a.nik;</para>
</listitem>
</varlistentry>
@@ -758,9 +787,7 @@
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/handbook/x11/chapter.sgml b/en_US.ISO_8859-1/books/handbook/x11/chapter.sgml
index 3d6c6c5c05..e8fb397095 100644
--- a/en_US.ISO_8859-1/books/handbook/x11/chapter.sgml
+++ b/en_US.ISO_8859-1/books/handbook/x11/chapter.sgml
@@ -13,9 +13,7 @@
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
diff --git a/en_US.ISO_8859-1/books/porters-handbook/book.sgml b/en_US.ISO_8859-1/books/porters-handbook/book.sgml
index aa5d962c4a..092d021ad9 100644
--- a/en_US.ISO_8859-1/books/porters-handbook/book.sgml
+++ b/en_US.ISO_8859-1/books/porters-handbook/book.sgml
@@ -88,7 +88,7 @@
<title>How Does the Ports Collection Work?</title>
<para>Programs are typically distributed on the Internet as a
- <xref linkend="ports-tarball" remap="tarball"> consisting of a
+ <link linkend="ports-tarball">tarball</link> consisting of a
Makefile and the source code for the program and usually some
instructions (which are unfortunately not always as instructive as
they could be), with perhaps a configuration script.</para>
@@ -100,18 +100,18 @@
from the source.</para>
<para>FreeBSD ports still use the tarball mechanism, but use a
- <xref linkend="ports-skeleton" remap="skeleton"> to hold the
+ <link linkend="ports-skeleton">skeleton</link> to hold the
"knowledge" of how to get the program working on FreeBSD,
rather than expecting the user to be able to work it out. They also
supply their own customised
- <xref linkend="ports-makefile" remap="Makefile">, so that almost
+ <link linkend="ports-makefile">Makefile</link>, so that almost
every port can be built in the same way.</para>
<para>If you look at a port skeleton (either on <ulink
URL="file://localhost/usr/ports/devel/ElectricFence">your FreeBSD
system</ulink> or <ulink
- URL="ftp://ftp.freebsd.org/pub/FreeBSD/ports/devel/ElectricFence">the FTP site</ulink>) and expect to find all sorts of pointy-headed rocket science lurking there, you may be disappointed by the one or two rather unexciting-looking files and directories you find there. (We will discuss in a minute how to go about <xref
- linkend="ports-getting" remap="Getting a port">).</para>
+ URL="ftp://ftp.freebsd.org/pub/FreeBSD/ports/devel/ElectricFence">the FTP site</ulink>) and expect to find all sorts of pointy-headed rocket science lurking there, you may be disappointed by the one or two rather unexciting-looking files and directories you find there. (We will discuss in a minute how to go about <link
+ linkend="ports-getting">Getting a port</link>).</para>
<para>“How on earth can this do anything?” I hear you cry. “There
is no source code there!”</para>
@@ -171,13 +171,12 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<procedure>
<step>
- <para>Locate the source code <xref linkend="ports-tarball"
- remap="tarball."> If it is not available locally, try to
+ <para>Locate the source code <link linkend="ports-tarball">tarball.</link> If it is not available locally, try to
grab it from an FTP site.</para>
</step>
<step>
- <para>Run a <xref linkend="ports-checksum" remap="checksum">
+ <para>Run a <link linkend="ports-checksum">checksum</link>
test on the tarball to make sure it has not been tampered
with, accidentally truncated, downloaded in ASCII mode, struck
by neutrinos while in transit, etc.</para>
@@ -188,7 +187,7 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
</step>
<step>
- <para>Apply any <xref linkend="ports-patch" remap="patches">
+ <para>Apply any <link linkend="ports-patch">patches</link>
needed to get the source to compile and run under FreeBSD.</para>
</step>
@@ -212,8 +211,8 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<step>
<para>Register the installation in a database. This means that,
- if you do not like the program, you can cleanly <xref
- linkend="ports-remove" remap="remove"> all traces of it from
+ if you do not like the program, you can cleanly <link
+ linkend="ports-remove">remove</link> all traces of it from
your system.</para>
</step>
@@ -230,85 +229,28 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<title>Getting a FreeBSD Port</title>
<para>There are two ways of getting hold of the FreeBSD port for a
- program. One requires a <xref linkend="ports-cd" remap="FreeBSD
- CDROM">, the other involves using an <xref linkend="ports-inet"
- remap="Internet Connection."></para>
+ program. One requires a <link linkend="ports-cd">FreeBSD
+ CDROM</link>, the other involves using an <link linkend="ports-inet">Internet Connection.</link></para>
<sect2 id="ports-cd">
<title>Compiling ports from CDROM</title>
-
- <para>If you answered yes to the question “Do you want to link the
- ports collection to your CDROM” during the FreeBSD installation,
- the initial setting up will already have been done for you.</para>
-
- <para>If not, make sure the <emphasis>FreeBSD</emphasis> CDROM is in
- the drive and mounted on, say, <filename>/cdrom</filename>. Then
- do</para>
-
- <informalexample>
- <screen>&prompt.root; <userinput>mkdir /usr/ports</userinput>
-&prompt.root; <userinput>cd /usr/ports</userinput>
-&prompt.root; <userinput>ln -s /cdrom/ports/distfiles distfiles</userinput></screen>
- </informalexample>
-
- <para>to enable the ports make mechanism to find the tarballs (it
- expects to find them in <filename>/usr/ports/distfiles</filename>,
- which is why we sym-linked the CDROM's tarball directory to that
- directory).</para>
-
- <para>Now, suppose you want to install the gnats program from the
- databases directory. Here is how to do it:-</para>
-
- <informalexample>
- <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
-&prompt.root; <userinput>mkdir databases</userinput>
-&prompt.root; <userinput>cp -R /cdrom/ports/databases/gnats databases</userinput>
-&prompt.root; <userinput>cd databases/gnats</userinput>
-&prompt.root; <userinput>make install</userinput></screen>
- </informalexample>
-
- <para>Or if you are a serious database user and you want to compare
- all the ones available in the Ports collection, do</para>
-
- <informalexample>
- <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
-&prompt.root; <userinput>cp -R /cdrom/ports/databases .</userinput>
-&prompt.root; <userinput>cd databases</userinput>
-&prompt.root; <userinput>make install</userinput></screen>
- </informalexample>
-
- <para>(yes, that really is a dot on its own after the <command>cp</command> command and
- not a mistake. It is Unix-ese for “the current
- directory”) and the ports make mechanism will automatically compile and
- install all the ports in the databases directory for you!</para>
-
- <para>If you do not like this method, here is a completely different
- way of doing it:-</para>
-
- <para>Create a “link tree” to it using the
- <citerefentry><refentrytitle>lndir</refentrytitle><manvolnum>1</manvolnum></citerefentry> command that comes with the
- <emphasis>XFree86</emphasis> distribution. Find a location with
- some free space, create a directory there and then cd to it. Then
- invoke the <citerefentry><refentrytitle>lndir</refentrytitle><manvolnum>1</manvolnum></citerefentry> command with the full
- pathname of the <filename>ports</filename> directory on the CDROM as the first
- argument and . (the current directory) as the second. This might
- be, for example, something like:</para>
- <informalexample>
- <screen>&prompt.root; <userinput>lndir /cdrom/ports .</userinput></screen>
- </informalexample>
-
- <para>Then you can build ports directly off the CDROM by building
- them in the link tree you have created.</para>
-
- <para>Note that there are some ports for which we cannot provide the
+ <para>Assuming that your FreeBSD CDROM is in the drive and mounted on
+ <filename>/cdrom</filename> (and the mount point
+ <emphasis>must</emphasis> be <filename>/cdrom</filename>), you should
+ then be able to build ports just as you normally do and the port
+ collection's built in search path should find the tarballs in
+ <filename>/cdrom/ports/distfiles/</filename> (if they exist there)
+ rather than downloading them over the net.</para>
+
+ <note>
+ <para>There are some ports for which we cannot provide the
original source in the CDROM due to licensing limitations. In
- that case, you will need to look at the section on <xref
- linkend="ports-inet"
- remap="Compiling ports using an Internet connection."></para>
-
- </sect2>
+ that case, you will need to look at the section on <link
+ linkend="ports-inet">Compiling ports using an Internet connection.</link></para>
+ </note>
+ </sect2>
<sect2 id="ports-inet">
<title>Compiling ports from the Internet</title>
@@ -316,13 +258,20 @@ install -c -o bin -g bin -m 444 /usr/ports/devel/ElectricFence/work/ElectricFenc
<para>If you do not have a CDROM, or you want to make sure you get
the very latest version of the port you want, you will need to
download the
- <xref linkend="ports-skeleton" remap="skeleton"> for the port. Now
+ <link linkend="ports-skeleton">skeleton</link> for the port. Now
this might sound like rather a fiddly job full of pitfalls, but
it is actually very easy.</para>
-
- <para>The key to it is that the FreeBSD FTP server can create
+
+ <para>First, if you are running a release version of FreeBSD, make
+ sure you get the appropriate “upgradekiet” for your
+ replease from the <ulink url="http://www.freebsd.org/ports/">ports
+ web page</ulink>. These packages include files that have been
+ updated since the release that you may need to compile new
+ ports.</para>
+
+ <para>The key to the skeletons is that the FreeBSD FTP server can create
on-the-fly
- <xref linkend="ports-tarball" remap="tarballs"> for you. Here is
+ <link linkend="ports-tarball">tarballs</link> for you. Here is
how it works, with the gnats program in the databases directory as
an example (the bits in square brackets are comments. Do not type
them in if you are trying this yourself!):-</para>
@@ -347,14 +296,12 @@ password. Remember to use binary (also known as image) mode!]
<para>What happened here? We connected to the FTP server in the
usual way and went to its <filename>databases</filename> sub-directory. When we gave it
- the command <command>get gnats.tar</command>, the FTP server <xref
- linkend="ports-tarball"
- remap="tarred"> up the gnats directory for us.</para>
+ the command <command>get gnats.tar</command>, the FTP server <link
+ linkend="ports-tarball">tarred</link> up the gnats directory for us.</para>
<para>We then extracted the gnats skeleton and went into the gnats
- directory to build the port. As we explained <xref
- linkend="ports-fetch"
- remap="earlier">, the make process noticed we did not have a
+ directory to build the port. As we explained <link
+ linkend="ports-fetch">earlier</link>, the make process noticed we did not have a
copy of the source locally, so it fetched one before extracting,
patching and building it.</para>
@@ -436,16 +383,17 @@ do-install:
the benefit of human readers (as in most Unix script
files).</para>
- <para><literal>DISTNAME</literal> specifies the name of the <xref
- linkend="ports-tarball" remap="tarball">, but without the
+ <para><literal>DISTNAME</literal> specifies the name of the <link
+ linkend="ports-tarball">tarball</link>, but without the
extension.</para>
<para><literal>CATEGORIES</literal> states what kind of program this is. In
- this case, a utility for developers.</para>
+ this case, a utility for developers. See the <link
+ linkend="porting-categories">categories</link> section of this
+ handbook for a complete list.</para>
<para><literal>MASTER_SITES</literal> is the URL(s) of the master FTP site,
- which is used to retrieve the <xref linkend="ports-tarball"
- remap="tarball"> if it is not available on the local system.
+ which is used to retrieve the <link linkend="ports-tarball">tarball</link> if it is not available on the local system.
This is a site which is regarded as reputable, and is normally the
one from which the program is officially distributed (in so far
as any software is "officially" distributed on the
@@ -477,8 +425,7 @@ do-install:
<sect2>
<title>The <filename>files</filename> directory</title>
- <para>The file containing the <xref linkend="ports-checksum"
- remap="checksum"> for the port is called
+ <para>The file containing the <link linkend="ports-checksum">checksum</link> for the port is called
<filename>md5</filename>, after the MD5 algorithm used for ports
checksums. It lives in a directory with the slightly confusing
name of <filename>files</filename>.</para>
@@ -491,8 +438,7 @@ do-install:
<sect2>
<title>The <filename>patches</filename> directory</title>
- <para>This directory contains the <xref linkend="ports-patch"
- remap="patches"> needed to make everything work properly under
+ <para>This directory contains the <link linkend="ports-patch">patches</link> needed to make everything work properly under
FreeBSD.</para>
</sect2>
@@ -536,7 +482,7 @@ do-install:
<listitem>
<para>Fix it yourself. Technical details on how ports work can
be found in
- <xref linkend="porting" remap="Porting applications."></para>
+ <link linkend="porting">Porting applications.</link></para>
</listitem>
<listitem>
@@ -568,15 +514,6 @@ do-install:
</sect1>
- <sect1>
- <title>I Want to Make a Port!</title>
-
- <para>Great! Please see the <xref linkend="porting"
- remap="guidelines"> for detailed instructions on how to do
- this.</para>
-
- </sect1>
-
<sect1>
<title>Some Questions and Answers</title>
@@ -707,8 +644,7 @@ do-install:
</listitem>
<listitem>
- <para>Q. I did what you said for <xref linkend="ports-cd"
- remap="compiling ports from a CDROM"> and it worked great
+ <para>Q. I did what you said for <link linkend="ports-cd">compiling ports from a CDROM</link> and it worked great
until I tried to install the kermit port:-</para>
<informalexample>
@@ -884,7 +820,16 @@ do-install:
<para>Q. There are so many ports it is hard to find the one I
want. Is there a list anywhere of what ports are available?</para>
- <para>A. Look in the <filename>INDEX</filename> file in <filename>/usr/ports</filename>.</para>
+ <para>A. Look in the <filename>INDEX</filename> file in
+ <filename>/usr/ports</filename>. If you would like to search the
+ ports collection for a keyword, you can do that too. For example,
+ you can find ports relevant to the LISP programming language
+ using:</para>
+
+ <informalexample>
+ <screen>&prompt.user; <userinput>cd /usr/ports</userinput>
+&prompt.user; <userinput>make search key=lisp</userinput></screen>
+ </informalexample>
</listitem>
<listitem>
@@ -1044,6 +989,3524 @@ grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arc
</sect1>
+
+ <sect1 id="porting">
+ <title>Making a port yourself</title>
+
+ <para><emphasis>Contributed by &a.jkh;, &a.gpalmer;, &a.asami;
+ &a.obrien; and &a.hoek;. 28 August 1996.</emphasis></para>
+
+ <para>So, now you are interested in making your own port?
+ Great!</para>
+
+ <para>What follows are some guidelines for creating a new port for
+ FreeBSD. The bulk of the work is done by
+ <filename>/usr/share/mk/bsd.port.mk</filename>, which all port
+ Makefiles include. Please refer to that file for more details on
+ the inner workings of the ports collection. Even if you don't
+ hack Makefiles daily, it is well commented, and you will still
+ gain much knowledge from it.</para>
+
+ <note>
+ <para>Only a fraction of the overridable variables
+ (<makevar><replaceable>VAR</replaceable></makevar>) are mentioned
+ in this document. Most (if not all) are documented at the start of
+ <filename>bsd.port.mk</filename>. This file users a non-standard
+ tab setting. <application>Emacs</application> and
+ <application>Vim</application> should recognise the setting on
+ loading the file. <command>vi</command> or <command>ex</command>
+ can be set to use the correct value by typing <command>:set
+ tabstop=4</command> once the file has been loaded.</para>
+ </note>
+
+ <sect2>
+ <title>Quick Porting</title>
+
+ <para>This section tells you how to do a quick port. In many
+ cases, it is not enough, but we will see.</para>
+
+ <para>First, get the original tarball and put it into <makevar>DISTDIR</makevar>, which defaults to
+ <filename>/usr/ports/distfiles</filename>.</para>
+
+ <note>
+ <para>The following assumes that the software compiled
+ out-of-the-box, i.e., there was absolutely no change required
+ for the port to work on your FreeBSD box. If you needed to
+ change something, you will have to refer to the next section
+ too.</para>
+ </note>
+
+ <sect3>
+ <title>Writing the <filename>Makefile</filename></title>
+
+ <para>The minimal <filename>Makefile</filename> would
+ look something like this:</para>
+
+ <programlisting>
+# New ports collection makefile for: oneko
+# Version required: 1.1b
+# Date created: 5 December 1994
+# Whom: asami
+#
+# $Id$
+#
+
+DISTNAME= oneko-1.1b
+CATEGORIES= games
+MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
+
+MAINTAINER= asami@FreeBSD.ORG
+
+MAN1= oneko.1
+MANCOMPRESSED= yes
+USE_IMAKE= yes
+
+.include <bsd.port.mk></programlisting>
+
+ <para>See if you can figure it out. Do not worry about the
+ contents of the <literal>$Id$</literal>
+ line, it will be filled in automatically by CVS when the port
+ is imported to our main ports tree. You can find a more
+ detailed example in the <link
+ linkend="porting-samplem">sample Makefile</link>
+ section.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Writing the description files</title>
+
+ <para>There are three description files that are
+ required for any port, whether they actually package or not.
+ They are <filename>COMMENT</filename>,
+ <filename>DESCR</filename>, and <filename>PLIST</filename>,
+ and reside in the <filename>pkg</filename>
+ subdirectory.</para>
+
+
+ <sect4>
+ <title><filename>COMMENT</filename></title>
+
+ <para>This is the one-line description of the port.
+ <emphasis>Please</emphasis> do not include the package name (or version
+ number of the software) in the comment. Here is
+ an example:</para>
+
+ <programlisting>
+A cat chasing a mouse all over the screen.</programlisting>
+
+ </sect4>
+
+ <sect4>
+ <title><filename>DESCR</filename></title>
+
+ <para>This is a longer description of the port. One to a few
+ paragraphs concisely explaining what the port does is
+ sufficient.</para>
+
+ <note>
+ <para>This is <emphasis>not</emphasis> a manual or an
+ in-depth description on how to use or compile the port!
+ <emphasis>Please be careful if you are copying from the
+ <filename>README</filename> or manpage</emphasis>; too often
+ they are not a concise description of the port or are in an
+ awkward format (e.g., manpages have justified spacing). If the
+ ported software has an official WWW homepage, you should list
+ it here.</para>
+ </note>
+
+ <para>It is recommended that you sign the name at the end of
+ this file, as in:</para>
+
+ <programlisting>
+This is a port of oneko, in which a cat chases a poor mouse all over
+the screen.
+ :
+(etc.)
+
+http://www.oneko.org/
+
+- Satoshi
+asami@cs.berkeley.edu</programlisting>
+
+ </sect4>
+
+ <sect4>
+ <title><filename>PLIST</filename></title>
+
+ <para>This file lists all the files installed by the port. It
+ is also called the “packing list” because the package is
+ generated by packing the files listed here. The pathnames
+ are relative to the installation prefix (usually
+ <filename>/usr/local</filename> or
+ <filename>/usr/X11R6</filename>). If you are using the
+ <makevar>MAN<replaceable>n</replaceable></makevar> variables (as
+ you should be), do not list any manpages here.</para>
+
+ <para>Here is a small example:</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>Refer to the <citerefentry><refentrytitle>pkg_create</refentrytitle><manvolnum>1</manvolnum></citerefentry> man page
+ for details on the packing list.</para>
+
+ <note>
+ <para>You should list all the files, but not the name
+ directories, in the list. Also, if the port creates
+ directories for itself during installtion, make sure to add
+ <literal>@dirrm</literal> lines as necessary to remove them
+ when the port is deleted.</para>
+
+ <para>It is recommended that you keep all the filenames in
+ this file sorted alphabetically. It will make verifying the
+ changes when you upgrade the port much easier.</para>
+ </note>
+ </sect4>
+ </sect3>
+
+ <sect3>
+ <title>Creating the checksum file</title>
+
+ <para>Just type <command>make makesum</command>.
+ The ports make rules will automatically generate the file
+ <filename>files/md5</filename>.</para>
+
+ </sect3>
+
+ <sect3 id="porting-testing">
+ <title>Testing the port</title>
+
+ <para>You should make sure that the port rules do exactly what
+ you want it to do, including packaging up the port. These are
+ the important points you need to verify.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename>PLIST</filename> does not contain anything not
+ installed by your port</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>PLIST</filename> contains everything that is
+ installed by your port</para>
+ </listitem>
+
+ <listitem>
+ <para>Your port can be installed multiple times using the
+ <maketarget>reinstall</maketarget> target</para>
+ </listitem>
+
+ <listitem>
+ <para>Your port <link linkend="porting-cleaning">cleans
+ up</link> after itself upon deinstall</para>
+ </listitem>
+ </itemizedlist>
+
+ <procedure>
+ <title>Recommended test ordering</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 `make package-name`</command></para>
+ </step>
+
+ <step>
+ <para><command>make deinstall</command></para>
+ </step>
+
+ <step>
+ <para><command>make reinstall</command></para>
+ </step>
+
+ <step>
+ <para><command>make package</command></para>
+ </step>
+ </procedure>
+
+ <para>Make sure that there aren't any warnings issued in any of
+ the <maketarget>package</maketarget> and
+ <maketarget>deinstall</maketarget> stages, After step 3, check
+ to see if all the new directories are correctly deleted. Also,
+ try using the software after step 4, to ensure that is works
+ correctly when installed from a package.</para>
+ </sect3>
+
+ <sect3 id="porting-portlint">
+ <title>Checking your port with <command>portlint</command></title>
+
+ <para>Please use <command>portlint</command> to see if your port
+ conforms to our guidelines. The <command>portlint</command>
+ program is part of the ports collection. In particular, your may
+ want to check if the <link
+ linkend="porting-samplem">Makefile</link> is in the right
+ shape and the <link linkend="porting-pkgname">package</link> is
+ named appropriately.</para>
+ </sect3>
+
+ <sect3 id="porting-submitting">
+ <title>Submitting the port</title>
+
+ <para>First, make sure you have read the <link
+ linkend="porting-dads">Do's and Dont's</link> section.</para>
+
+ <para>Now that you are happy with your port, the only thing
+ remaining is to put it in the main FreeBSD ports tree and make
+ everybody else happy about it too. We do not need your
+ <filename>work</filename> directory or the
+ <filename>pkgname.tgz</filename> package, so delete them
+ now. Next, simply include the output of <command>shar `find
+ port_dir`</command> in a bug report and send it with the
+ <citerefentry>
+ <refentrytitle>send-pr</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry> program (see <link linkend="contrib-general">Bug
+ Reports and General Commentary</link> for more information
+ about <citerefentry>
+ <refentrytitle>send-pr</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>. If the uncompressed port is larger than
+ 20KB, you should compress it into a tarfile and use <citerefentry>
+ <refentrytitle>uuencode</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry> before including it in the bug report (uuencoded
+ tarfiles are acceptable even if the bug report is smaller than
+ 20KB but are not preferred). Be sure to classify the bug report as
+ category <literal>ports</literal> and class
+ <literal>change-request</literal>. (Do not mark the report
+ <literal>confidential</literal>!)</para>
+
+ <para>One more time, <emphasis>do not include the original source
+ distfile, the <filename>work</filename> directory, or the
+ package you built with <command>make
+ package</command></emphasis>.</para>
+
+ <note>
+ <para>In the past, we asked you to upload new port submissions
+ in our ftp site (<hostid
+ role="fqdn">ftp.freebsd.org</hostid>). This is no longer
+ recommended as read access is turned off on that
+ <filename>incoming/</filename> directory of that site due to
+ the large amount of pirated software showing up there.</para>
+ </note>
+
+ <para>We will look at your port,
+ get back to you if necessary, and put it in the
+ tree. Your name will also appear in the list of “Additional
+ FreeBSD contributors” on the FreeBSD Handbook and other files.
+ Isn't that great?!? <!-- smiley -->:)</para>
+
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Slow Porting</title>
+
+ <para>Ok, so it was not that simple, and the port required some
+ modifications to get it to work. In this section, we will
+ explain, step by step, how to modify it to get it to work with
+ the ports paradigm.</para>
+
+
+ <sect3>
+ <title>How things work</title>
+
+ <para>First, this is the sequence of events which occurs when
+ the user first types <command>make</command> in
+ your port's directory, and you may find that having
+ <filename>bsd.port.mk</filename> in another window while you
+ read this really helps to understand it.</para>
+
+ <para>But do not worry if you do not really understand what
+ <filename>bsd.port.mk</filename> is doing, not many people
+ do... <!-- smiley --><emphasis>:></emphasis></para>
+
+
+ <procedure>
+
+ <step>
+ <para>The <maketarget>fetch</maketarget> target is run. The <maketarget>fetch</maketarget> target is
+ responsible for making sure that the tarball exists
+ locally in <makevar>DISTDIR</makevar>.
+ If <maketarget>fetch</maketarget> cannot find the required files in <makevar>DISTDIR</makevar> it will look up the
+ URL <makevar>MASTER_SITES</makevar>,
+ which is set in the Makefile, as well as our main ftp
+ site at <ulink
+ URL="ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/">ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/,</ulink> where we put sanctioned distfiles as backup. It will then attempt to fetch the named distribution file with <makevar>FETCH</makevar>, assuming that the requesting site has direct access to the Internet. If that succeeds, it will save the file in <makevar>DISTDIR</makevar> for future use and proceed.</para>
+ </step>
+
+ <step>
+ <para>The <maketarget>extract</maketarget> target is run. It looks for your port's
+ distribution file (typically a gzip'd tarball) in <makevar>DISTDIR</makevar> and unpacks it into a temporary subdirectory
+ specified by <makevar>WRKDIR</makevar>
+ (defaults to <filename>work</filename>).</para>
+ </step>
+
+ <step>
+ <para>The <maketarget>patch</maketarget> target is run. First, any patches defined
+ in <makevar>PATCHFILES</makevar> are
+ applied. Second, if any patches are found in <makevar>PATCHDIR</makevar> (defaults to the
+ <filename>patches</filename> subdirectory), they are
+ applied at this time in alphabetical order.</para>
+ </step>
+
+ <step>
+ <para>The <maketarget>configure</maketarget> target is run. This can do any one of
+ many different things.</para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>If it exists,
+ <filename>scripts/configure</filename> is run.</para>
+ </listitem>
+
+ <listitem>
+ <para>If <makevar>HAS_CONFIGURE</makevar> or
+ <makevar>GNU_CONFIGURE</makevar>
+ is set,
+ <filename><makevar>WRKSRC</makevar>/configure</filename> is
+ run.</para>
+ </listitem>
+
+ <listitem>
+ <para>If <makevar>USE_IMAKE</makevar> is set,
+ <makevar>XMKMF</makevar>
+ (default: <command>xmkmf
+ -a</command>) is run.</para>
+ </listitem>
+
+ </orderedlist>
+
+ </step>
+
+ <step>
+ <para>The <maketarget>build</maketarget> target is run. This is responsible for
+ descending into the ports' private working directory
+ (<makevar>WRKSRC</makevar>) and
+ building it. If <makevar>USE_GMAKE</makevar> is set, GNU
+ <command>make</command> will be used,
+ otherwise the system <command>make</command>
+ will be used.</para>
+ </step>
+
+ </procedure>
+
+
+ <para>The above are the default actions. In addition, you can
+ define targets <maketarget>pre-<replaceable>something</replaceable></maketarget> or <maketarget>post-<replaceable>something</replaceable></maketarget>, or put scripts
+ with those names, in the <filename>scripts</filename>
+ subdirectory, and they will be run before or after the default
+ actions are done.</para>
+
+ <para>For example, if you have a <maketarget>post-extract</maketarget> target defined in your
+ Makefile, and a file <filename>pre-build</filename> in the
+ <filename>scripts</filename> subdirectory, the
+ <maketarget>post-extract</maketarget> target will be
+ called after the regular extraction actions, and the
+ <filename>pre-build</filename> script will be executed before
+ the default build rules are done. It is recommended that you
+ use <filename>Makefile</filename> targets if the actions are
+ simple enough, because it will be easier for someone to figure
+ out what kind of non-default action the port requires.</para>
+
+ <para>The default actions are done by the
+ <filename>bsd.port.mk</filename> targets <maketarget>do-<replaceable>something</replaceable></maketarget>. For example, the
+ commands to extract a port are in the target <maketarget>do-extract</maketarget>. If you are not happy with
+ the default target, you can fix it by redefining the
+ <maketarget>do-<replaceable>something</replaceable></maketarget> target in
+ your <filename>Makefile</filename>.</para>
+
+ <note>
+ <para>The “main” targets (e.g., <maketarget>extract</maketarget>, <maketarget>configure</maketarget>, etc.) do nothing more than
+ make sure all the stages up to that one is completed and
+ call the real targets or scripts, and they are not intended
+ to be changed. If you want to fix the extraction, fix
+ <maketarget>do-extract</maketarget>, but never ever
+ touch <maketarget>extract</maketarget>!</para>
+ </note>
+
+ <para>Now that you understand what goes on when the user types
+ <command>make</command>, let us go through the
+ recommended steps to create the perfect port.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Getting the original sources</title>
+
+ <para>Get the original sources (normally) as a compressed
+ tarball (<filename><replaceable>foo</replaceable>.tar.gz</filename> or
+ <filename><replaceable>foo</replaceable>.tar.Z</filename>) and copy it into
+ <makevar>DISTDIR</makevar>. Always use
+ <emphasis>mainstream</emphasis> sources when and where you
+ can.</para>
+
+ <para>If you cannot find a ftp/http site that is well-connected
+ to the net, or can only find sites that have irritatingly
+ non-standard formats, you might want to put a copy on a
+ reliable ftp or http server that you control (e.g., your home
+ page). Make sure you set <makevar>MASTER_SITES</makevar> to
+ reflect your choice.</para>
+
+ <para>If you
+ cannot find somewhere convenient and reliable to put the distfile
+ (if you are a FreeBSD committer, you can just put it in your
+ <filename>public_html/</filename> directory on
+ <hostid>freefall</hostid>),
+ we can “house” it ourselves by putting
+ it on <filename>ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/LOCAL_PORTS/</filename> as the last resort. Please refer to this
+ location as <makevar>MASTER_SITE_LOCAL</makevar>. Send mail to
+ the &a.ports;if you are not sure what to do.</para>
+
+ <para>If your port's distfile changes all the time for no good
+ reason, consider putting the distfile in your home page and
+ listing it as the first <makevar>MASTER_SITES</makevar>. This
+ will prevent users from getting <errorname>checksum
+ mismatch</errorname> errors, and also reduce the workload of
+ maintainers of our ftp site. Also, if there isonly one master
+ site for the port, it is recommended that you house a backup at
+ your site and list it as the second
+ <makevar>MASTER_SITES</makevar>.</para>
+
+ <para>If your port requires some additional `patches' that are
+ available on the Internet, fetch them too and put them in
+ <makevar>DISTDIR</makevar>. Do not worry if
+ they come from site other than where you got the main source
+ tarball, we have a way to handle these situations (see the
+ description of <link
+ linkend="porting-patchfiles">PATCHFILES</link> below).</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Modifying the port</title>
+
+ <para>Unpack a copy of the tarball in a private directory and
+ make whatever changes are necessary to get the port to compile
+ properly under the current version of FreeBSD. Keep
+ <emphasis>careful track</emphasis> of everything you do, as
+ you will be automating the process shortly. Everything,
+ including the deletion, addition or modification of files
+ should be doable using an automated script or patch file when
+ your port is finished.</para>
+
+ <para>If your port requires significant user
+ interaction/customization to compile or install, you should
+ take a look at one of Larry Wall's classic <application>Configure</application> scripts
+ and perhaps do something similar yourself. The goal of the
+ new ports collection is to make each port as “plug-and-play”
+ as possible for the end-user while using a minimum of disk
+ space.</para>
+
+ <note>
+ <para>Unless explicitly stated, patch files, scripts, and
+ other files you have created and contributed to the FreeBSD
+ ports collection are assumed to be covered by the standard
+ BSD copyright conditions.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>Patching</title>
+
+ <para>In the preparation of the port, files that have been added
+ or changed can be picked up with a recursive diff for later
+ feeding to patch. Each set of patches you wish to apply
+ should be collected into a file named
+ <filename>patch-<replaceable>xx</replaceable></filename> where
+ <replaceable>xx</replaceable> denotes the sequence in which
+ the patches will be applied — these are done in
+ <emphasis>alphabetical order</emphasis>, thus
+ <literal>aa</literal> first, <literal>ab</literal> second and so on. These files
+ should be stored in <makevar>PATCHDIR</makevar>, from where they will be
+ automatically applied. All patches should be relative to
+ <makevar>WRKSRC</makevar> (generally the
+ directory your port's tarball unpacks itself into, that being
+ where the build is done). To make fixes and upgrades easier,
+ you should avoid having more than one patch fix the same file
+ (e.g., <filename>patch-aa</filename> and <filename>patch-ab</filename> both changing <filename><makevar>WRKSRC</makevar>/foobar.c</filename>).</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Configuring</title>
+
+ <para>Include any additional customization commands to your
+ <filename>configure</filename> script and save it in the
+ <filename>scripts</filename> subdirectory. As mentioned
+ above, you can also do this as <filename>Makefile</filename>
+ targets and/or scripts with the name
+ <filename>pre-configure</filename> or
+ <filename>post-configure</filename>.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Handling user input</title>
+
+ <para>If your port requires user input to build, configure or
+ install, then set <makevar>IS_INTERACTIVE</makevar> in your
+ Makefile. This will allow “overnight builds” to skip your port
+ if the user sets the variable <envar>BATCH</envar> in his
+ environment (and if the user sets the variable
+ <envar>INTERACTIVE</envar>, then <emphasis>only</emphasis>
+ those ports requiring interaction are built).</para>
+
+ <para>It is also recommended that if there are reasonable default
+ answers to the questions, you check the
+ <makevar>PACKAGE_BUILDING</makevar> variable and turn off the
+ interactive script when it is set. This will allow us to build
+ the packages for CD-ROMs and ftp.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Configuring the Makefile</title>
+
+ <para>Configuring the Makefile is pretty simple, and again we
+ suggest that you look at existing examples before starting.
+ Also, there is a <link linkend="porting-samplem">sample
+ Makefile</link> in this handbook, so take a look and please follow
+ the ordering of variables and sections in that template to make
+ your port easier for others to read.</para>
+
+ <para>Now, consider the following problems in sequence as you
+ design your new Makefile:</para>
+
+
+ <sect3>
+ <title>The original source</title>
+
+ <para>Does it live in <makevar>DISTDIR</makevar> as a standard gzip'd
+ tarball? If so, you can go on to the next step. If not, you
+ should look at overriding any of the <makevar>EXTRACT_CMD</makevar>, <makevar>EXTRACT_BEFORE_ARGS</makevar>, <makevar>EXTRACT_AFTER_ARGS</makevar>, <makevar>EXTRACT_SUFX</makevar>, or <makevar>DISTFILES</makevar> variables, depending on
+ how alien a format your port's distribution file is. (The
+ most common case is <literal>EXTRACT_SUFX=.tar.Z</literal>,
+ when the tarball is condensed by regular compress, not
+ gzip.)</para>
+
+ <para>In the worst case, you can simply create your own
+ <maketarget>do-extract</maketarget> target to override
+ the default, though this should be rarely, if ever,
+ necessary.</para>
+
+ </sect3>
+
+ <sect3>
+ <title><makevar>DISTNAME</makevar></title>
+
+ <para>You should set <makevar>DISTNAME</makevar> to be the base name of
+ your port. The default rules expect the distribution file
+ list (<makevar>DISTFILES</makevar>) to be
+ named <makevar>DISTNAME</makevar><makevar>EXTRACT_SUFX</makevar> which, if it is a normal tarball, is going to be
+ something like <literal>foozolix-1.0.tar.gz</literal> for a setting of <literal>DISTNAME=foozolix-1.0</literal>.</para>
+
+ <para>The default rules also expect the tarball(s) to extract
+ into a subdirectory called
+ <filename>work/<makevar>DISTNAME</makevar></filename>, e.g. <filename>work/foozolix-1.0/</filename>.</para>
+
+ <para>All this behavior can be overridden, of course; it simply
+ represents the most common time-saving defaults. For a port
+ requiring multiple distribution files, simply set <makevar>DISTFILES</makevar> explicitly. If only a
+ subset of <makevar>DISTFILES</makevar> are
+ actual extractable archives, then set them up in <makevar>EXTRACT_ONLY</makevar>, which will override
+ the <makevar>DISTFILES</makevar> list when
+ it comes to extraction, and the rest will be just left in
+ <makevar>DISTDIR</makevar> for later
+ use.</para>
+
+ </sect3>
+
+ <sect3>
+ <title><makevar>PKGNAME</makevar></title>
+
+ <para>If <makevar>DISTNAME</makevar> does not conform to our <link
+ linkend="porting-pkgname">guidelines for a good package
+ name</link>, you should set the <makevar>PKGNAME</makevar>
+ variable to something better. See the abovementioned guidelines
+ for more details.</para>
+ </sect3>
+
+ <sect3>
+ <title><makevar>CATEGORIES</makevar></title>
+
+ <para>When a package is created, it is put under
+ <filename>/usr/ports/packages/All</filename> and links are
+ made from one or more subdirectories of
+ <filename>/usr/ports/packages</filename>. The names of these
+ subdirectories are specified by the variable <makevar>CATEGORIES</makevar>. It is intended to
+ make life easier for the user when he is wading through the
+ pile of packages on the ftp site or the CD-ROM. Please take a
+ look at the existing <link
+ linkend="porting-categories">categories</link> and pick the
+ ones that are suitable for your port.</para>
+
+ <para>This list also determines where in the ports tree the port
+ is imported. If you put more than one category here, it is
+ assumed that the port files will be put in the subdirectory with
+ the name in the first category. See the <link
+ linkend="porting-categories">categories</link> section for
+ more discussion about how to pick the right categories.</para>
+
+ <para>If you port truly belongs to something that is different
+ from all the existing ones, you can even create a new category
+ name. In that case, please send mail to the &a.ports; to propose
+ a new category.</para>
+
+ <note>
+ <para>There is no error checking for category
+ names. <command>make package</command> will happily create a
+ new directory if you mustype the category name, so be
+ careful!</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><makevar>MASTER_SITES</makevar></title>
+
+ <para>Record the directory part of the ftp/http-URL pointing at
+ the original tarball in <makevar>MASTER_SITES</makevar>. Do not forget the
+ trailing slash (<filename>/</filename>)!</para>
+
+ <para>The <command>make</command> macros will try to use this specification for
+ grabbing the distribution file with <makevar>FETCH</makevar> if they cannot find it
+ already on the system.</para>
+
+ <para>It is recommended that you put multiple sites on this
+ list, preferably from different continents. This will
+ safeguard against wide-area network problems, and we are even
+ planning to add support for automatically determining the
+ closest master site and fetching from there!</para>
+
+ <para>If the original tarball is part of one of the following
+ popular archives: X-contrib, GNU, Perl CPAN, TeX CTAN, or
+ Linux Sunsite, you refer to those sites in an easy compact
+ form using <makevar>MASTER_SITE_XCONTRIB</makevar>, <makevar>MASTER_SITE_GNU</makevar>,
+ <makevar>MASTER_SITE_PERL_CPAN</makevar>, <makevar>MASTER_SITE_TEX_CTAN</makevar>, and
+ <makevar>MASTER_SITE_SUNSITE</makevar>. Simply set <makevar>MASTER_SITE_SUBDIR</makevar> to the
+ path with in the archive. Here is an example:</para>
+
+ <programlisting>
+MASTER_SITES= ${MASTER_SITE_XCONTRIB}
+MASTER_SITE_SUBDIR= applications</programlisting>
+
+ <para>The user can also set the <makevar>MASTER_SITE_*</makevar> variables in
+ <filename>/etc/make.conf</filename> to override our choices,
+ and use their favorite mirrors of these popular archives
+ instead.</para>
+
+ </sect3>
+
+ <sect3 id="porting-patchfiles">
+ <title><makevar>PATCHFILES</makevar></title>
+
+ <para>If your port requires some additional patches that are
+ available by ftp or http, set <makevar>PATCHFILES</makevar> to the names of the
+ files and <makevar>PATCH_SITES</makevar> to
+ the URL of the directory that contains them (the format is the
+ same as <makevar>MASTER_SITES</makevar>).</para>
+
+ <para>If the patch is not relative to the top of the source tree
+ (i.e., <makevar>WKRSRC</makevar>) because it
+ contains some extra pathnames, set <makevar>PATCH_DIST_STRIP</makevar> accordingly.
+ For instance, if all the pathnames in the patch has an extra
+ <literal>foozolix-1.0/</literal> in front of the
+ filenames, then set
+ <literal>PATCH_DIST_STRIP=-p1</literal>.</para>
+
+ <para>Do not worry if the patches are compressed, they will be
+ decompressed automatically if the filenames end with
+ <filename>.gz</filename> or
+ <filename>.Z</filename>.</para>
+
+ <para>If the patch is distributed with some other files, such as
+ documentation, in a gzip'd tarball, you can't just use
+ <makevar>PATCHFILES</makevar>. If that is
+ the case, add the name and the location of the patch tarball
+ to <makevar>DISTFILES</makevar> and
+ <makevar>MASTER_SITES</makevar>. Then, from
+ the <maketarget>pre-patch</maketarget> target, apply the
+ patch either by running the patch command from there, or
+ copying the patch file into the <makevar>PATCHDIR</makevar> directory and calling it
+ <filename>patch-<replaceable>xx</replaceable></filename>.</para>
+
+ <note>
+ <para>Note the tarball will have been extracted alongside the
+ regular source by then, so there is no need to explicitly
+ extract it if it is a regular gzip'd or compress'd tarball.
+ If you do the latter, take extra care not to overwrite
+ something that already exists in that directory. Also do
+ not forget to add a command to remove the copied patch in
+ the <maketarget>pre-clean</maketarget> target.</para>
+ </note>
+
+ </sect3>
+
+ <sect3>
+ <title><makevar>MAINTAINER</makevar></title>
+
+ <para>Set your mail-address here. Please. <!-- smiley --><emphasis>:)</emphasis></para>
+
+ <para>For detailed description of the responsibility of
+ maintainers, refer to <link
+ linkend="policies-maintainer">MAINTAINER
+ on Makefiles</link> section.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Dependencies</title>
+
+ <para>Many ports depend on other ports. There are five
+ variables that you can use to ensure that all the required
+ bits will be on the user's machine. There are also some
+ pre-supported dependency variables for common cases, plus a few
+ more to control the behaviour of dependencies.</para>
+
+
+ <sect4>
+ <title><makevar>LIB_DEPENDS</makevar></title>
+
+ <para>This variable specifies the shared libraries this port
+ depends on. It is a list of <replaceable>lib</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples where
+ <replaceable>lib</replaceable> is the name of the shared library,
+ and <replaceable>dir</replaceable> is the directory in which to
+ find it in case it is not available, and
+ <replaceable>target</replaceable> is the target to call in
+ that directory. For example,
+
+ <programlisting>
+LIB_DEPENDS= jpeg\\.9\\.:${PORTSDIR}/graphics/jpeg:install</programlisting>
+
+ will check for a shared jpeg library with
+ major version 9, and descend into the
+ <filename>graphics/jpeg</filename> subdirectory of your
+ ports tree to build and install it if it is not
+ found. The <replaceable>target</replaceable> part can be
+ omitted if it is equal to <makevar>DEPENDS_TARGET</makevar>
+ (which defaults to <literal>install</literal>).</para>
+
+ <note>
+ <para>The <replaceable>lib</replaceable> part is an argument
+ given to <command>ldconfig -r | grep -wF</command>. There
+ shall be no reqular expressions in this variable.</para>
+ </note>
+
+ <para>The dependency is checked twice, once from within the
+ <maketarget>extract</maketarget> target and then from within
+ the <maketarget>install</maketarget> target. Also, the name of the
+ dependency is put in to the package so that
+ <command>pkg_add</command> will automatically install it if it
+ is not on the user's system.</para>
+
+ </sect4>
+
+ <sect4>
+ <title><makevar>RUN_DEPENDS</makevar></title>
+
+ <para>This variable specifies executables or files this port
+ depends on during run-time. It is a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples where
+ <replaceable>path</replaceable> is the name of the executable or
+ file, and <replaceable>dir</replaceable> is the directory in which
+ to find it in case it is not available, and
+ <replaceable>target</replaceable> is the target to call in
+ that directory. If
+ <replaceable>path</replaceable> starts with a slash
+ (<literal>/</literal>), it is treated as a file and its
+ existence is tested with <command>test -e</command>;
+ otherwise, it is assumed to be an executable, and
+ <command>which -s</command> is used to determine if the
+ program exists in the user's search path.</para>
+
+ <para>For example,
+
+ <programlisting>
+RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \
+ wish8.0:${PORTSDIR}/x11-toolkits/tk80</programlisting>
+
+ will check if the file or directory
+ <filename>/usr/local/etc/innd</filename> exists, and build
+ and install it from the <filename>news/inn</filename>
+ subdirectory of the ports tree if it is not found. It will
+ also see if an executable called <command>wish8.0</command> is in your search path, and
+ descend into the <filename>x11-toolkits/tk80</filename> subdirectory of
+ your ports tree to build and install it if it is not
+ found.</para>
+
+ <note>
+ <para>In this case, <command>innd</command> is actually an
+ executable; if an executable is in a place that is not
+ expected to be in a normal user's search path, you should
+ use the full pathname.</para>
+ </note>
+
+ <para>The dependency is checked from within the <maketarget>install</maketarget> target. Also, the name of the
+ dependency is put in to the package so that
+ <command>pkg_add</command> will automatically install it if it
+ is not on the user's system. The
+ <replaceable>target</replaceable> part can be omitted if it is
+ the same <makevar>DEPENDS_TARGET</makevar>.</para>
+
+ </sect4>
+
+ <sect4>
+ <title><makevar>BUILD_DEPENDS</makevar></title>
+
+ <para>This variable specifies executables or files this port
+ requires to build. Like <makevar>RUN_DEPENDS</makevar>, it is
+ a list of <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples.
+ For example,
+
+ <programlisting>
+BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting>
+
+ will check for an executable called
+ <command>unzip</command>, and descend into the
+ <filename>archivers/unzip</filename> subdirectory of your
+ ports tree to build and install it if it is not
+ found.</para>
+
+ <note>
+ <para>“build” here means everything from extracting to
+ compilation. The dependency is checked from within the
+ <maketarget>extract</maketarget> target. The
+ <replaceable>target</replaceable> part can be omitted if it
+ is the same as <makevar>DEPENDS_TARGET</makevar></para>
+ </note>
+ </sect4>
+
+ <sect4>
+ <title><makevar>FETCH_DEPENDS</makevar></title>
+
+ <para>This variable specifies executables or files this port
+ requires to fetch. Like the previous two, it is a list of
+ <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> tuples. For
+ example,
+
+ <programlisting>
+FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting>
+
+ will check for an executable called
+ <command>ncftp2</command>, and descend into the
+ <filename>net/ncftp2</filename> subdirectory of your ports
+ tree to build and install it if it is not found.</para>
+
+ <para>The dependency is checked from within the
+ <maketarget>fetch</maketarget> target. The
+ <replaceable>target</replaceable> part can be omitted if it is
+ the same as <makevar>DEPENDS_TARGET</makevar>.</para>
+
+ </sect4>
+
+ <sect4>
+ <title><makevar>DEPENDS</makevar></title>
+
+ <para>If there is a dependency that does not fall into either
+ of the above four categories, or your port requires to have
+ the source of the other port extracted in addition to having
+ them installed, then use this variable. This is a list of
+ <replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional>, as there is nothing to check, unlike the previous four. The <replaceable>target</replaceable> part can be omitted if it is the same as <makevar>DEPENDS_TARGET</makevar>.</para>
+ </sect4>
+
+ <sect4>
+ <title>Common dependency variables</title>
+
+ <para>Define <literal>USE_XLIB=yes</literal> if your port
+ requires the X Window System to be installed (it is implied by
+ <makevar>USE_IMAKE</makevar>). Define
+ <literal>USE_GMAKE=yes</literal> if your port requires GNU
+ <command>make</command> instead of BSD
+ <command>make</command>. Define
+ <literal>USE_AUTOCONF=yes</literal> if your port requires GNU
+ autoconf to be run. Define <literal>USE_QT=yes</literal> if
+ your port uses the latest qt toolkit. Use
+ <literal>USE_PERL5=yes</literal> if your port requires version
+ 5 of the perl language. (The last is especially important since
+ some versions of FreeBSD has perl5 as part of the base system
+ while others don't.)</para>
+ </sect4>
+
+ <sect4>
+ <title>Notes on dependencies</title>
+
+ <para>As mentioned above, the default target to call when a
+ dependency is required is
+ <maketarget>DEPENDS_TARGET</maketarget>. It defaults to
+ <literal>install</literal>. This is a user variable; is is
+ never defined in a port's <filename>Makefile</filename>. If
+ your port needs a special way to handle a dependency, use the
+ <literal>:target</literal> part of the
+ <makevar>*_DEPENDS</makevar> variables instead of redefining
+ <makevar>DEPENDS_TARGET</makevar>.</para>
+
+ <para>When you type <command>make clean</command>, its
+ dependencies are automatically cleaned too. If you do not wish
+ this to happen, define the variable
+ <makevar>NOCLEANDEPENDS</makevar> in your environment.</para>
+
+ <para>To depend on another port unconditionally, it is customary
+ to use the string <literal>nonexistent</literal> as the first
+ field of <makevar>BUILD_DEPENDS</makevar> or
+ <makevar>RUN_DEPENDS</makevar>. Use this only when you need to
+ the to get to the source of the other port. You can often save
+ compilation time by specifying the target too. For
+ instance
+
+ <programlisting>
+BUILD_DEPENDS= /nonexistent:${PORTSDIR}/graphics/jpeg:extract</programlisting>
+
+ will always descend to the JPEG port and extract it.</para>
+
+ <para>Do not use <makevar>DEPENDS</makevar> unless there is no
+ other way the behaviour you want can be accomplished. It will
+ cause the other port to be always build (and installed, by
+ default), and the dependency will go into the packages as
+ well. If this is really what you need, I recommend you to
+ write it as <literal>BUILD_DEPENDS</literal> and
+ <literal>RUN_DEPENDS</literal> instead—at least the
+ intention will be clear.</para>
+ </sect4>
+ </sect3>
+
+ <sect3>
+ <title>Building mechanisms</title>
+
+ <para>If your package uses GNU <command>make</command>, set
+ <literal>USE_GMAKE=yes</literal>. If your package uses
+ <command>configure</command>, set
+ <literal>HAS_CONFIGURE=yes</literal>. If your package uses GNU
+ <command>configure</command>, set
+ <literal>GNU_CONFIGURE=yes</literal> (this implies
+ <literal>HAS_CONFIGURE</literal>). If you want to give some
+ extra arguments to <command>configure</command> (the default
+ argument list <literal>--prefix=${PREFIX}</literal> for
+ GNU <command>configure</command> and empty for non-GNU
+ <command>configure</command>), set those extra arguments in
+ <makevar>CONFIGURE_ARGS</makevar>. If your package uses GNU
+ <command>autoconf</command>, set
+ <literal>USE_AUTOCONF=yes</literal>. This implies
+ <makevar>GNU_CONFIGURE</makevar>, and will cause
+ <command>autoconf</command> to be run before
+ <command>configure</command>.</para>
+
+ <para>If your package is an X application that creates
+ <filename>Makefile</filename>s from
+ <filename>Imakefile</filename>s using <command>imake</command>, then set
+ <literal>USE_IMAKE=yes</literal>. This will cause the
+ configure stage to automatically do an <command>xmkmf
+ -a</command>. If the <option>-a</option> flag is a
+ problem for your port, set
+ <literal>XMKMF=xmkmf</literal>.
+ If the port uses <command>imake</command> but does not understand the
+ <maketarget>install.man</maketarget> target,
+ <literal>NO_INSTALL_MANPAGES=yes</literal> should be set.
+ In addition, the author of the original port should be shot.
+ <!-- smiley --><emphasis>:></emphasis></para>
+
+ <para>If your port's source <filename>Makefile</filename> has
+ something else than <maketarget>all</maketarget> as the main
+ build target, set <makevar>ALL_TARGET</makevar>
+ accordingly. Same goes for <maketarget>install</maketarget> and
+ <makevar>INSTALL_TARGET</makevar>.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Special considerations</title>
+
+ <para>There are some more things you have to take into account when
+ you create a port. This section explains the most common of
+ those.</para>
+
+ <sect3>
+ <title><command>ldconfig</command></title>
+
+ <para>If your port installs a shared library, add a
+ <maketarget>post-install</maketarget> target to your
+ <filename>Makefile</filename> that runs
+ <literal>${LDCONFIG} -m</literal> on the directory where
+ the new library is installed (usually
+ <filename><makevar>PREFIX</makevar>/lib</filename>) to register
+ it into the shared library cache.</para>
+
+ <para>Also, add a matching <literal>@exec /sbin/ldconfig
+ -m</literal> and <literal>@unexec /sbin/ldconfig -R</literal>
+ pair to your <filename>pkg/PLIST</filename> file so that a user
+ who installed the package can start using teh shared libraru
+ immediately and deinstallation will not cause the system to
+ still believe the library is there. These lines should
+ immediately follow the line for the shared library itself, as
+ in:</para>
+
+ <programlisting>
+lib/libtvl80.so.1
+@exec /sbin/ldconfig -m %D/lib
+@unexec /sbin/ldconfig -R</programlisting>
+
+ <para>Never, ever, <emphasis>ever</emphasis> add a line that says
+ <literal>ldconfig</literal> without any arguments to your
+ <filename>Makefile</filename> or
+ <filename>pkg/PLIST</filename>. This will reset the shared
+ libraru cache to the contents of <filename>/usr/lib</filename>
+ only, and will royally screw up the user's machine ("Help, xinit
+ does not run anymore after I install this port!"). Anybody who
+ does this will be shot and cut in 65,536 pieces by a rusty knife
+ and have is liver chopped out by a bunch of crows and will
+ eternally rot to death in the deepest bowels of hell (not
+ necessarily in that order…)</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>ELF support</title>
+
+ <para>Since FreeBSD is moving to ELF from 3.0-release onwards,
+ 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 that there will
+ be one more release (2.2.8) from the 2.2 branch. 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 awhile for reference
+ in case you have come across some old port you wish to
+ upgrade.</para>
+
+ <sect3>
+ <title>Moving a.out libraries out of the way</title>
+
+ <para>A.out libraries should be moved out of
+ <filename>/usr/local/lib</filename> and similar to an
+ <filename>aout</filename> subdirectory. (If you don't move them
+ out of the way, ELF ports will happily overwrite a.out libraries.)
+ The <maketarget>move-aout-libs</maketarget> target in the -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>
+ </sect3>
+
+ <sect3>
+ <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>
+ </sect3>
+
+ <sect3>
+ <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's always going to be
+ <literal>aout</literal> in -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>
+ </sect3>
+
+ <sect3>
+ <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 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>PLIST</filename> too, and it won't 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>
+ </sect3>
+
+ <sect3>
+ <title><makevar>LIB_DEPENDS</makevar></title>
+
+ <para>All port Makefiles 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>
+ </sect3>
+
+ <sect3>
+ <title><filename>PLIST</filename></title>
+
+ <para><filename>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>PLIST</filename> mentioned in the previous
+ paragraph.</para>
+ </sect3>
+
+ <sect3>
+ <title><literal>ldconfig</literal></title>
+
+ <para>The <literal>ldconfig</literal> line in Makefiles should read:</para>
+
+ <programlisting>
+${SETENV} OBJFORMAT=${PORTOBJFORMAT} ${LDCONFIG} -m ....</programlisting>
+
+ <para>In <filename>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>
+ </sect3>
+ </sect2>
+
+ <sect2 id="porting-masterdir">
+ <title><makevar>MASTERDIR</makevar></title>
+
+ <para>If your port needs to build slightly different versions of
+ packages by having a variable (for instance, resolution, or paper
+ size) take different values, create one subdirectory per package
+ to make it easier forusers to see what to do, but try to share as
+ many files as possible between ports. Typically you only need a
+ very short <filename>Makefile</filename> in all but one of the
+ directories if you use variables cleverly. In the sole
+ <filename>Makefiles</filename>, you can use
+ <makevar>MASTERDIR</makevar> to specify the directory where the
+ rest of the files are. Also, use a variable as part of
+ <link linkend="porting-pkgname"><makevar>PKGNAME</makevar></link>
+ so the packages will have different names.</para>
+
+ <para>This will be best demonstrated by an example. This is part of
+ <filename>japanese/xdvi300/Makefile</filename>;</para>
+
+ <programlisting>
+PKGNAME= ja-xdvi${RESOLUTION}-17
+ :
+# 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>japanese/xdvi300</filename> also has all the regular
+ patches, package files, etc. If you type <command>make</command>
+ there, it will take the default value for the resolution (300) and
+ build the port normally.</para>
+
+ <para>As for other resolutions, this is the
+ <emphasis>entire</emphasis>
+ <filename>xdvi118/Makefile</filename>;</para>
+
+ <programlisting>
+RESOLUTION= 118
+MASTERDIR= ${.CURDIR}/../xdvi300
+
+.include ${MASTERDIR}/Makefile</programlisting>
+
+ <para>(<filename>xdvi240/Makefile</filename> and
+ <filename>xdvi400/Makefile</filename> are similar). The
+ <makevar>MASTERDIR</makevar> definition tells
+ <filename>bsd.port.mk</filename> that the refulat set of
+ subdirectories like <makevar>PATCHDIR</makevar> and
+ <makevar>PKGDIR</makevar> are to be found under
+ <filename>xdvi300</filename>. The
+ <literal>RESOLUTION=118</literal> line will override the
+ <literal>RESOLUTION=300</literal> line in
+ <filename>xdvi300/Makefile</filename> and the port will be built
+ with resolution set to 118.</para>
+ </sect2>
+
+ <sect2>
+ <title>Shared library versions</title>
+
+ <para>First, please read our <link linkend="policies-shlib">policy
+ on shared library versioning</link> to understand
+ what to do with shared library versions in general. Do
+ not blindly assume software authors know what they are
+ doing; many of them do not. It is very important that
+ these details are carefully considered, as we have quite a
+ unique situation where we are trying to have dozens of
+ potentially incompatible software pairs co-exist.
+ Careless port imports have caused great trouble regarding
+ shared libraries in the past (ever wondered why the port
+ <filename>jpeg-6b</filename> has a shared library version of 9.0?).
+ If in doubt, send a message to the &a.ports;. Most of the
+ time, your job ends by determining the right shared
+ library version and making appropriate patches to
+ implement it.</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>
+ </sect2>
+
+ <sect2 id="porting-manpages">
+ <title>Manpages</title>
+
+ <para>The <makevar>MAN[1-9LN]</makevar> variables will automatically
+ add any manpages to <filename>pkg/PLIST</filename> (this means you
+ must <emphasis>not</emphasis> list manpages in the
+ <filename>PLIST</filename>—see <link
+ linkend="porting-plist">generating PLIST</link> for more). It
+ also makes the install stage automatically compress or uncompress
+ manpages depending on the setting of
+ <makevar>NOMANCOMPRESS</makevar> in
+ <filename>/etc/make.conf</filename>.</para>
+
+ <para>To specify whether the manpages are compressed upon
+ installation, use the <makevar>MANCOMPRESSED</makevar> variable.
+ This variable can take three values, <literal>yes</literal>,
+ <literal>no</literal> and <literal>maybe</literal>.
+ <literal>yes</literal> means manpages are already installed
+ compressed, <literal>no</literal> means they are not, and
+ <literal>maybe</literal> means the software already respects the
+ value of <makevar>NOMANCOMPRESS</makevar> so
+ <filename>bsd.port.mk</filename> does not have to do anything
+ special.</para>
+
+ <para><makevar>MANCOMPRESSED</makevar> is automatically set to
+ <literal>yes</literal> if <makevar>USE_IMAKE</makevar> is set and
+ <makevar>NO_INSTALL_MANPAGES</makevar> is not set, and to
+ <literal>no</literal> otherwise. You don't have to explicitly
+ define it unless the default is not suitable for your port.</para>
+
+ <para>If your port anchors its man tree somewhere other than
+ <makevar>PREFIX</makevar>, you can use the
+ <makevar>MANPREFIX</makevar> to set it. Also, if only manpages in
+ certain sections go in a non-standard place, such as some Perl
+ modules ports, you can set individual man paths using
+ <makevar>MAN<replaceable>sect</replaceable>PREFIX</makevar> (where
+ <replaceable>sect</replaceable> is one of <literal>1-9</literal>,
+ <literal>L</literal> or <literal>N</literal>).</para>
+
+ <para>If your manpages go to language-specific subdirectories, set
+ the name of the languages to <makevar>MANLANG</makevar>. The
+ value of this variable defaults to <literal>""</literal> (i.e.,
+ English only).</para>
+
+ <para>Here is an example that puts it all together.</para>
+
+ <programlisting>
+MAN1= foo.1
+MAN3= bar.3
+MAN4= baz.4
+MANLANG= "" ja
+MAN3PREFIX= ${PREFIX}/share/foobar
+MANCOMPRESSED= yes</programlisting>
+
+ <para>This states that six files are installed by this 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>
+ </sect2>
+
+ <sect2>
+ <title>Ports that require Motif</title>
+
+ <para>There are many programs that require a Motif library
+ (available from several commercial vendors, while there is
+ a free clone reported to be able to run many applications in
+ <filename>x11-toolkits/lesstif</filename>) to compile. Since
+ it is a popular toolkit and their licenses usually permit
+ redistribution of statically linked binaries, we have made
+ special provisions for handling ports that require Motif in a
+ way that we can easily compile binaries linked either
+ dynamically (for people who are compiling from the port) or
+ statically (for people who distribute packages).</para>
+
+ <sect3>
+ <title><makevar>REQUIRES_MOTIF</makevar></title>
+
+ <para>If your port requires Motif, define this variable in the
+ Makefile. This will prevent people who don't own a copy of
+ Motif from even attempting to build it.</para>
+ </sect3>
+
+ <sect3>
+ <title><makevar>MOTIFLIB</makevar></title>
+
+ <para>This variable will be set by
+ <filename>bsd.port.mk</filename> to be the appropriate reference
+ to the Motif library. Please patch the source to use this
+ wherever the Motif library is referenced in the
+ <filename>Makefile</filename> or
+ <filename>Imakefile</filename>.</para>
+
+ <para>There are two common cases:</para>
+
+ <itemizedlist>
+ <listitem><para>If the port refers to the Motif library as
+ <literal>-lXm</literal> in its <filename>Makefile</filename>
+ or <filename>Imakefile</filename>, simply substitute
+ <literal>${MOTIFLIB}</literal> for
+ it.</para></listitem>
+
+ <listitem><para>If the port uses <literal>XmClientLibs</literal>
+ in its <filename>Imakefile</filename>, change it to
+ <literal>${MOTIFLIB} ${XTOOLLIB}
+ ${XLIB}</literal>.</para></listitem>
+ </itemizedlist>
+
+ <para>Note that <makevar>MOTIFLIB</makevar> (usually) expands to
+ <literal>-L/usr/X11R6/lib -lXm</literal> or
+ <literal>/usr/X11R6/lib/libXm.a</literal>, so there is no need
+ to add <literal>-L</literal> or <literal>-l</literal> in
+ front.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>X11 fonts</title>
+
+ <para>If your port installs fonts for the X Window system, put them
+ in
+ <filename><makevar>X11BASE</makevar>/lib/X11/fonts/local</filename>.
+ This directory is new to XFree86 release 3.3.3. If it does not
+ exist, please create it, and print out a message urging the user
+ to update their XFree86 to 3.3.3 or newer, or at least add this
+ directory to the font path in
+ <filename>/etc/XF86Config</filename>.</para>
+ </sect2>
+
+ <sect2>
+ <title>Info files</title>
+
+ <para>The new version of texinfo (included in 2.2.2-RELEASE and
+ onwards) contains a utility called <command>install-info</command>
+ to add and delete entries to the <filename>dir</filename> file. If
+ your port installs any info documents, please follow this
+ instructions so your port/package will correctly update the user's
+ <filename><makevar>PREFIX</makevar>/info/dir</filename>
+ file. (Sorry for the length of this section, but is it imperative
+ to weave all the info files together. If done correctly, it will
+ produce a <emphasis>beautiful</emphasis> listing, so please bear
+ with me!</para>
+
+ <para>First, this is what you (as a porter) need to know</para>
+
+ <informalexample>
+ <screen>&prompt.user; <userinput>install-info --help</userinput>
+install-info [OPTION]... [INFO-FILE [DIR-FILE]]
+ Install INFO-FILE in the Info directory file DIR-FILE.
+
+Options:
+--delete Delete existing entries in INFO-FILE;
+ don't insert any new entries.
+ :
+--entry=TEXT Insert TEXT as an Info directory entry.
+ :
+--section=SEC Put this file's entries in section SEC of the directory. :</screen>
+ </informalexample>
+
+ <note>
+ <para>This program will not actually
+ <emphasis>install</emphasis> info files; it merely inserts or
+ deletes entries in the <filename>dir</filename> file.</para>
+ </note>
+
+ <para>Here's a seven-step procedure to convert ports to use
+ <command>install-info</command>. I will use
+ <filename>editors/emacs</filename> as an example.</para>
+
+ <procedure>
+ <step>
+ <para>Look at the texinfo sources and make a patch to insert
+ <literal>@dircategory</literal> and <literal>@direntry</literal>
+ statements to files that don't have them. This is part of
+ my patch:</para>
+
+ <programlisting>
+--- ./man/vip.texi.org Fri Jun 16 15:31:11 1995
++++ ./man/vip.texi Tue May 20 01:28:33 1997
+@@ -2,6 +2,10 @@
+
+ @setfilename ../info/vip
+ @settitle VIP
++@dircategory The Emacs editor and associated tools
++@direntry
++* VIP: (vip). A VI-emulation for Emacs.
++@end direntry
+
+ @iftex
+ @finalout
+ :</programlisting>
+
+ <para>The format should be self-explanatory. Many authors
+ leave a <filename>dir</filename> file in the source tree
+ that contains all the entries you need, so look around
+ before you try to write your own. Also, make sure you
+ look into related ports and make the section names and
+ entry indentations consistent (we recommend that all entry
+ text start at the 4th tab stop).</para>
+
+ <note>
+ <para>Note that you can put only one info entry per file
+ because of a bug in <command>install-info
+ --delete</command> that deletes only the first entry
+ if you specify multiple entries in the
+ <email>@direntry</email> section.</para>
+ </note>
+
+ <para>You can give the <literal>dir</literal>
+ entries to <command>install-info</command> as
+ arguments (<option>--section</option> and
+ <option>--entry</option>) instead of patching the texinfo
+ sources. I do not think this is a good idea for ports
+ because you need to duplicate the same information in
+ <emphasis>three</emphasis> places
+ (<filename>Makefile</filename> and
+ <literal>@exec</literal>/<literal>@unexec</literal> of
+ <filename>PLIST</filename>; see below). However, if you
+ have a Japanese (or other multibyte encoding) info files,
+ you will have to use the extra arguments to <command>install-info</command> because <command>makeinfo</command> can't handle those texinfo
+ sources. (See <filename>Makefile</filename> and
+ <filename>PLIST</filename> of
+ <filename>japanese/skk</filename> for examples on how to
+ do this).</para>
+ </step>
+
+ <step>
+ <para>Go back to the port directory and do a <command>make clean; make</command> and verify that
+ the info files are regenerated from the texinfo sources.
+ Since the texinfo sources are newer than the info files,
+ they should be rebuilt when you type <command>make</command>; but many
+ <filename>Makefile</filename>s don't include correct
+ dependencies for info files. In <command>emacs</command>' case, I had to
+ patch the main <filename>Makefile.in</filename> so it will
+ descend into the <filename>man</filename>
+ subdirectory to rebuild the info pages.</para>
+
+ <programlisting>
+--- ./Makefile.in.org Mon Aug 19 21:12:19 1996
++++ ./Makefile.in Tue Apr 15 00:15:28 1997
+@@ -184,7 +184,7 @@
+ # Subdirectories to make recursively. `lisp' is not included
+ # because the compiled lisp files are part of the distribution
+ # and you cannot remake them without installing Emacs first.
+-SUBDIR = lib-src src
++SUBDIR = lib-src src man
+
+ # The makefiles of the directories in $SUBDIR.
+ SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile lwlib/Makefile
+--- ./man/Makefile.in.org Thu Jun 27 15:27:19 1996
++++ ./man/Makefile.in Tue Apr 15 00:29:52 1997
+@@ -66,6 +66,7 @@
+ ${srcdir}/gnu1.texi \
+ ${srcdir}/glossary.texi
+
++all: info
+ info: $(INFO_TARGETS)
+
+ dvi: $(DVI_TARGETS)</programlisting>
+
+ <para>The second hunk was necessary because the default
+ target in the <filename>man</filename> subdir is called
+ <maketarget>info</maketarget>, while the main
+ <filename>Makefile</filename> wants to call <maketarget>all</maketarget>. I also deleted the installation
+ of the <filename>info</filename> info file
+ because we already have one with the same name in
+ <filename>/usr/share/info</filename> (that patch is not
+ shown here).</para>
+ </step>
+
+ <step>
+ <para>If there is a place in the
+ <filename>Makefile</filename> that is installing the
+ <filename>dir</filename> file, delete it. Your
+ port may not be doing it. Also, remove any commands that
+ are otherwise mucking around with the
+ <filename>dir</filename> file.</para>
+
+ <programlisting>
+--- ./Makefile.in.org Mon Aug 19 21:12:19 1996
++++ ./Makefile.in Mon Apr 14 23:38:07 1997
+@@ -368,14 +368,8 @@
+ if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \
+ then \
+ (cd ${infodir}; \
+- if [ -f dir ]; then \
+- if [ ! -f dir.old ]; then mv -f dir dir.old; \
+- else mv -f dir dir.bak; fi; \
+- fi; \
+ cd ${srcdir}/info ; \
+- (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir); \
+- (cd $${thisdir}; chmod a+r ${infodir}/dir); \
+ for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \
+ (cd $${thisdir}; \
+ ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \
+ chmod a+r ${infodir}/$$f); \</programlisting>
+ </step>
+
+ <step>
+ <para>(This step is only necessary if you are modifying an
+ existing port.) Take a look at
+ <filename>pkg/PLIST</filename> and delete anything that is
+ trying to patch up <filename>info/dir</filename>. They
+ may be in <filename>pkg/INSTALL</filename> or some other
+ file, so search extensively.</para>
+
+ <programlisting>
+Index: pkg/PLIST
+===================================================================
+RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v
+retrieving revision 1.15
+diff -u -r1.15 PLIST
+--- PLIST 1997/03/04 08:04:00 1.15
++++ PLIST 1997/04/15 06:32:12
+@@ -15,9 +15,6 @@
+ man/man1/emacs.1.gz
+ man/man1/etags.1.gz
+ man/man1/ctags.1.gz
+-@unexec cp %D/info/dir %D/info/dir.bak
+-info/dir
+-@unexec cp %D/info/dir.bak %D/info/dir
+ info/cl
+ info/cl-1
+ info/cl-2</programlisting>
+ </step>
+
+ <step>
+ <para>Add a <maketarget>post-install</maketarget>
+ target to the <filename>Makefile</filename> to create a
+ <filename>dir</filename> file if it is not there. Also,
+ call <maketarget>install-info</maketarget> with the
+ installed info files.</para>
+
+ <programlisting>
+Index: Makefile
+===================================================================
+RCS file: /usr/cvs/ports/editors/emacs/Makefile,v
+retrieving revision 1.26
+diff -u -r1.26 Makefile
+--- Makefile 1996/11/19 13:14:40 1.26
++++ Makefile 1997/05/20 10:25:09 1.28
+@@ -20,5 +20,11 @@
+ post-install:
+ .for file in emacs-19.34 emacsclient etags ctags b2m
+ strip ${PREFIX}/bin/${file}
+ .endfor
++ if [ ! -f ${PREFIX}/info/dir ]; then \
++ ${SED} -ne '1,/Menu:/p' /usr/share/info/dir > ${PREFIX}/info/dir; \
++ fi
++.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode
++ install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir
++.endfor
+
+ .include <bsd.port.mk></programlisting>
+
+ <para>Do not use anything other than
+ <filename>/usr/share/info/dir</filename> and the above
+ command to create a new info file. In fact, I'd add the
+ first three lines of the above patch to
+ <filename>bsd.port.mk</filename> if you (the porter)
+ wouldn't have to do it in <filename>PLIST</filename> by
+ yourself anyway.</para>
+ </step>
+
+ <step>
+ <para>Edit <filename>PLIST</filename> and add equivalent
+ <literal>@exec</literal> statements and also
+ <literal>@unexec</literal> for <command>pkg_delete</command>.
+ You do not need to delete <filename>info/dir</filename>
+ with <literal>@unexec</literal>.</para>
+
+ <programlisting>
+Index: pkg/PLIST
+===================================================================
+RCS file: /usr/cvs/ports/editors/emacs/pkg/PLIST,v
+retrieving revision 1.15
+diff -u -r1.15 PLIST
+--- PLIST 1997/03/04 08:04:00 1.15
++++ PLIST 1997/05/20 10:25:12 1.17
+@@ -16,7 +14,15 @@
+ man/man1/etags.1.gz
+ man/man1/ctags.1.gz
++@unexec install-info --delete %D/info/emacs %D/info/dir
+ :
++@unexec install-info --delete %D/info/ccmode %D/info/dir
+ info/cl
+ info/cl-1
+@@ -87,6 +94,18 @@
+ info/viper-3
+ info/viper-4
++@exec [ -f %D/info/dir ] || sed -ne '1,/Menu:/p' /usr/share/info/dir > %D/info/dir
++@exec install-info %D/info/emacs %D/info/dir
+ :
++@exec install-info %D/info/ccmode %D/info/dir
+ libexec/emacs/19.34/i386--freebsd/cvtmail
+ libexec/emacs/19.34/i386--freebsd/digest-doc</programlisting>
+
+ <note>
+ <para>The <literal>@unexec install-info
+ --delete</literal> commands have to be listed before
+ the info files themselves so they can read the files.
+ Also, the <literal>@exec install-info</literal> commands
+ have to be after the info files and the
+ <literal>@exec</literal> command that creates the the
+ <filename>dir</filename> file.</para>
+ </note>
+ </step>
+
+ <step>
+ <para><link linkend="porting-testing">Test</link> and admire your work. <!-- smiley --><emphasis>:)</emphasis>. Check the <filename>dir</filename> file before and after each
+ step.</para>
+ </step>
+ </procedure>
+
+ </sect2>
+
+ <sect2>
+ <title>The <filename>pkg/</filename> subdirectory</title>
+
+ <para>There are some tricks we haven't mentioned yet about the
+ <filename>pkg/</filename> subdirectory that come in handy
+ sometimes.</para>
+
+ <sect3 id="porting-message">
+ <title><filename>MESSAGE</filename></title>
+
+ <para>If you need to display a message to the installer, you may
+ place the message in <filename>pkg/MESSAGE</filename>. This
+ capability is often useful to display additional installation
+ steps to be taken after a <command>pkg_add</command> or to display
+ licensing information.</para>
+
+ <note>
+ <para>The <filename>pkg/MESSAGE</filename> file does not need to
+ be added to <filename>pkg/PLIST</filename>. Also, it will not get
+ automatically printed if the user is using the port, not the
+ package, so you should probably display it from the
+ <maketarget>post-install</maketarget> target yourself.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><filename>INSTALL</filename></title>
+
+ <para>If your port needs execute commands when the binary package is
+ installed with <command>pkg_add</command> you can do with via the
+ <filename>pkg/INSTALL</filename> script. This script will
+ automatically be added to the package, and will be run twice by
+ <command>pkg_add</command>. The first time will as
+ <literal>INSTALL ${PKGNAME} PRE-INSTALL</literal> and the
+ second time as <literal>INSTALL ${PKGNAME}
+ POST-INSTALL</literal>. <literal>$2</literal> can be
+ tested to determine which mode the script is being run in. The
+ <envar>PKG_PREFIX</envar> environmental variable will be set to
+ the package installation directory. See <citerefentry>
+ <refentrytitle>pkg_add</refentrytitle>
+ <manvolnum>1</manvolnum></citerefentry> for additional
+ information.</para>
+
+ <note>
+ <para>This script is not run automatically if you install the port
+ with <command>make install</command>. If you are depending on
+ it being run, you will have to explicitly call it on your port's
+ <filename>Makefile</filename>.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><filename>REQ</filename></title>
+
+ <para>If your port needs to determine if it should install or not,
+ you can create a <filename>pkg/REQ</filename>
+ “requirements” script. It will be invoked
+ automatically at installation/deinstallation time to determine
+ whether or not installation/deinstallation should proceed.</para>
+ </sect3>
+
+ <sect3 id="porting-plist">
+ <title>Changing <filename>PLIST</filename> based on make variables</title>
+
+ <para>Some ports, particularly the p5- ports, need to change their
+ <filename>PLIST</filename> depending on what options they are
+ configured with (or version of perl, in the case of p5- ports). To
+ make this easy, any instances in the <filename>PLIST</filename> of
+ <literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal>, and
+ <literal>%%PERL_VERSION%%</literal> will be substituted for
+ appropriately. The value of <literal>%%OSREL%%</literal> is the
+ numeric revision of the operating system (e.g.,
+ <literal>2.2.7</literal>). <literal>%%PERL_VERSION%%</literal> is
+ the full version number of perl (e.g., <literal>5.00502</literal>)
+ and <literal>%%PERL_VER%%</literal> is the perl version number
+ minus the patchlevel (e.g., <literal>5.005</literal>).</para>
+
+ <para>If you need to make other substitutions, you can set the
+ <makevar>PLIST_SUB</makevar> variable with a list of
+ <literal><replaceable>VAR</replaceable>=<replaceable>VALUE</replaceable></literal>
+ pairs and instances of
+ <literal>%%<replaceable>VAR</replaceable>%%</literal>' will be
+ substituted with <replaceable>VALUE</replaceable> in the
+ <filename>PLIST</filename>.</para>
+
+ <para>For instance, if you have a port that installs many files in
+ a version-specific subdirectory, you can put something
+ like
+
+ <programlisting>
+OCTAVE_VERSION= 2.0.13
+PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
+
+ in the <filename>Makefile</filename> and use
+ <literal>%%OCTAVE_VERSION%%</literal> wherever the version shows
+ up in <filename>PLIST</filename>. That way, when you upgrade the
+ port, you will not have to change dozens (or in some cases,
+ hundreds) of lines in the <filename>PLIST</filename>.</para>
+
+ <para>This substitution (as well as addition of any <link
+ linkend="porting-manpages">man pages</link>) will be done
+ between the <maketarget>do-install</maketarget> and
+ <maketarget>post-install</maketarget> targets, by reading from
+ <makevar>PLIST</makevar> and writing to
+ <makevar>TMPPLIST</makevar> (default:
+ <filename><makevar>WRKDIR</makevar>/.PLIST.mktmp</filename>). So
+ if your port builds <makevar>PLIST</makevar> on the fly, do so in
+ or before <maketarget>do-install</maketarget>. Also, if your port
+ needs to edit the resulting file, do so in
+ <maketarget>post-install</maketarget> to a file named
+ <makevar>TMPPLIST</makevar>.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Licensing Problems</title>
+
+ <para>Some software packages have restrictive licenses or can be
+ in violation to the law (PKP's patent on public key crypto, ITAR
+ (export of crypto software) to name just two of them). What we
+ can do with them vary a lot, depending on the exact wordings of
+ the respective licenses.</para>
+
+ <note>
+ <para>It is your responsibility as a porter to read the
+ licensing terms of the software and make sure that the FreeBSD
+ project will not be held accountable of violating them by
+ redistributing the source or compiled binaries either via ftp
+ or CD-ROM. If in doubt, please contact the &a.ports;.</para>
+ </note>
+
+ <para>There are two variables you can set in the Makefile to
+ handle the situations that arise frequently:</para>
+
+
+ <orderedlist>
+
+ <listitem>
+ <para>If the port has a “do not sell for profit” type of
+ license, set the variable <makevar>NO_CDROM</makevar> to a
+ string describing the reason why. We
+ will make sure such ports won't go into the CD-ROM come
+ release time. The distfile and package will still be
+ available via ftp.</para>
+ </listitem>
+
+ <listitem>
+ <para>If the resulting package needs to be built uniquely
+ for each site, or the resulting binary package can't be
+ distributed due to licensing; set the variable
+ <makevar>NO_PACKAGE</makevar> to a string describing the
+ reason why. We will make sure such
+ packages won't go on the ftp site, nor into the CD-ROM
+ come release time. The distfile will still be included on
+ both however.</para>
+ </listitem>
+
+ <listitem>
+ <para>If the port has legal restrictions on who can use it
+ (e.g., crypto stuff) or has a “no commercial use” license,
+ set the variable <makevar>RESTRICTED</makevar> to be the
+ string describing the reason why. For such ports, the
+ distfiles/packages will not be available even from our ftp
+ sites.</para>
+ </listitem>
+
+ </orderedlist>
+
+
+ <note>
+ <para>The GNU General Public License (GPL), both version 1
+ and 2, should not be a problem for ports.</para>
+ </note>
+
+ <note>
+ <para>If you are a committer, make sure you update the
+ <filename>ports/LEGAL</filename> file too.</para>
+ </note>
+ </sect2>
+
+ <sect2>
+ <title>Upgrading</title>
+
+ <para>When you notice that a port is out of date compared to the
+ latest version from the original authors, first make sure you
+ have the latest port. You can find them in the
+ <filename>ports-current</filename> directory of the ftp mirror
+ sites.</para>
+
+ <para>The next step is to send a mail to the maintainer, if one is
+ listed in the port's <filename>Makefile</filename>. That person may already be
+ working on an upgrade, or have a reason to not upgrade the port
+ right now (because of, for example, stability problems of the
+ new version).</para>
+
+ <para>If the maintainer asks you to do the upgrade or there isn't
+ any such person to begin with, please make the upgrade and send
+ the recursive diff (either unified or context diff is fine, but
+ port committers appear to prefer unified diff more) of the new
+ and old ports directories to us (e.g., if your modified port
+ directory is called <filename>superedit</filename>
+ and the original as in our tree is
+ <filename>superedit.bak</filename>, then send us the result of
+ <command>diff -ruN superedit.bak
+ superedit</command>). Please examine the output to make
+ sure all the changes make sense. The best way to send us the
+ diff is by including it to <citerefentry><refentrytitle>send-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ (category <literal>ports</literal>). Please mention any added or deleted files
+ in the message, as they have to be explicitly specified to CVS
+ when doing a commit. If the diff is more than about 20KB, please
+ compress and uuencode it; otherwise, just include it in as is in
+ the PR.</para>
+
+ </sect2>
+
+ <sect2>
+ <title><anchor id="porting-dads">Do's and Dont's</title>
+
+ <para>Here is a list of common do's and dont's that you encounter
+ during the porting process.You should check your own port
+ against this list, but you can also check ports in the PR
+ database that others have submitted. Submit any comments on
+ ports you check as described in <link linkend="contrib-general">Bug
+ Reports and General Commentary</link>. Checking ports in
+ the PR database will both make it faster for us to commit them,
+ and prove that you know what you are doing.</para>
+
+ <sect3>
+ <title>Strip Binaries</title>
+
+ <para>Do strip binaries. If the original source already strips the
+ binaries, fine; otherwise you should add a
+ <literal>post-install</literal> rule to to it yourself. Here is an
+ example;</para>
+
+ <programlisting>
+post-install:
+ strip ${PREFIX}/bin/xdl</programlisting>
+
+ <para>Use the <citerefentry>
+ <refentrytitle>file</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry> command on the installed executable to check
+ whether the binary is stripped or not. If it does not say
+ <literal>not stripped</literal>, it is stripped.</para>
+ </sect3>
+
+ <sect3>
+ <title>INSTALL_* macros</title>
+
+ <para>Do use the macros provided in <filename>bsd.port.mk</filename>
+ to ensure correct modes and ownership of files in your own
+ <maketarget>*-install</maketarget> targets. They are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><makevar>INSTALL_PROGRAM</makevar> is a command to install
+ binary executables.</para>
+ </listitem>
+
+ <listitem>
+ <para><makevar>INSTALL_SCRIPT</makevar> is a command to install
+ executable scripts.</para>
+ </listitem>
+
+ <listitem>
+ <para><makevar>INSTALL_DATA</makevar> is a command to install
+ sharable data.</para>
+ </listitem>
+
+ <listitem>
+ <para><makevar>INSTALL_MAN</makevar> is a command to install
+ manpages and other documentation (it doesn't compress
+ anything).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>These are basically the <command>install</command> command
+ with all the appropriate flags. See below for an example on how
+ to use them.</para>
+ </sect3>
+
+ <sect3 id="porting-versions">
+ <title>Differentiating operating systems and OS versions</title>
+
+ <para>You may come across code that needs modifications or
+ conditional compilation based upon what version of UNIX it is
+ running under. If you need to make such changes to the code for
+ conditional compilation, make sure you make the changes as general
+ as possible so that we can back-port code to FreeBSD 1.x systems
+ and cross-port to other BSD systems such as 4.4BSD from CSRG,
+ BSD/386, 386BSD, NetBSD, and OpenBSD.</para>
+
+ <para>The preferred way to tell 4.3BSD/Reno (1990) and newer
+ versions of the BSD code apart is by using the
+ <literal>BSD</literal> macro defined in
+ <filename><sys/param.h></filename>. Hopefully that file is
+ already included; if not, add the code:</para>
+
+ <programlisting>
+#if (defined(__unix__) || defined(unix)) && !defined(USG)
+#include <sys/param.h>
+#endif</programlisting>
+
+ <para>to the proper place in the <filename>.c</filename> file. We
+ believe that every system that defines these to symbols has
+ <filename>sys/param.h</filename>. If you find a system that
+ doesn't, we would like to know. Please send mail to the
+ &a.ports;.</para>
+
+ <para>Another way is to use the GNU Autoconf style of doing
+ this:</para>
+
+ <programlisting>
+#ifdef HAVE_SYS_PARAM_H
+#include <sys/param.h>
+#endif</programlisting>
+
+ <para>Don't forget to add <literal>-DHAVE_SYS_PARAM_H</literal> to
+ the <makevar>CFLAGS</makevar> in the <filename>Makefile</filename>
+ for this method.</para>
+
+ <para>Once you have <filename>sys/param.h</filename>
+ included, you may use:</para>
+
+ <programlisting>
+#if (defined(BSD) && (BSD >= 199103))</programlisting>
+
+ <para>to detect if the code is being compiled on a 4.3 Net2 code
+ base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD,
+ BSD/386 1.1 and below).</para>
+
+ <para>Use:</para>
+
+ <programlisting>
+#if (defined(BSD) && (BSD >= 199306))</programlisting>
+
+ <para>to detect if the code is being compiled on a 4.4 code base
+ or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or
+ above).</para>
+
+ <para>The value of the <literal>BSD</literal> macro is
+ <literal>199506</literal> for the 4.4BSD-Lite2 code base. This is
+ stated for informational purposes only. It should not be used to
+ distinguish between version of FreeBSD based only on 4.4-Lite vs.
+ versions that have merged in changes from 4.4-Lite2. The
+ <literal>__FreeBSD__</literal> macro should be used
+ instead.</para>
+
+ <para>Use sparingly:</para>
+
+
+ <itemizedlist>
+
+ <listitem>
+ <para><literal>__FreeBSD__</literal> is defined in all
+ versions of FreeBSD. Use it if the change you are making
+ <emphasis>only</emphasis> affects FreeBSD. Porting gotchas like the use of
+ <literal>sys_errlist[]</literal> vs
+ <function>strerror()</function> are Berkeleyisms, not
+ FreeBSD changes.</para>
+ </listitem>
+
+ <listitem>
+ <para>In FreeBSD 2.x, <literal>__FreeBSD__</literal> is
+ defined to be <literal>2</literal>. In earlier
+ versions, it is <literal>1</literal>. Later
+ versions will bump it to match their major version number.</para>
+ </listitem>
+
+ <listitem>
+ <para>If you need to tell the difference between a FreeBSD
+ 1.x system and a FreeBSD 2.x or 3.x system, usually the
+ right answer is to use the <literal>BSD</literal> macros
+ described above. If there actually is a FreeBSD specific
+ change (such as special shared library options when using
+ <command>ld</command>) then it is OK to use
+ <literal>__FreeBSD__</literal> and <literal>#if
+ __FreeBSD__ > 1</literal> to detect a FreeBSD 2.x
+ and later system. If you need more granularity in
+ detecting FreeBSD systems since 2.0-RELEASE you can use
+ the following:</para>
+
+ <programlisting>
+#if __FreeBSD__ >= 2
+#include <osreldate.h>
+# if __FreeBSD_version >= 199504
+ /* 2.0.5+ release specific code here */
+# endif
+#endif</programlisting>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Release</entry>
+ <entry><literal>_FreeBSD_version</literal></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>2.0-RELEASE</entry>
+ <entry>119411</entry>
+ </row>
+
+ <row>
+ <entry>2.1-currents</entry>
+ <entry>199501, 199503</entry>
+ </row>
+
+ <row>
+ <entry>2.0.5-RELEASE</entry>
+ <entry>199504</entry>
+ </row>
+
+ <row>
+ <entry>2.2-current before 2.1</entry>
+ <entry>199508</entry>
+ </row>
+
+ <row>
+ <entry>2.1.0-RELEASE</entry>
+ <entry>199511</entry>
+ </row>
+
+ <row>
+ <entry>2.2-current before 2.1.5</entry>
+ <entry>199512</entry>
+ </row>
+
+ <row>
+ <entry>2.1.5-RELEASE</entry>
+ <entry>199607</entry>
+ </row>
+
+ <row>
+ <entry>2.2-current before 2.1.6</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 (no change)</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.1-RELEASE</entry>
+ <entry>220000 (no change)</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after texinfo-3.9</entry>
+ <entry>221001</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after top</entry>
+ <entry>221002</entry>
+ </row>
+
+ <row>
+ <entry>2.2.2-RELEASE</entry>
+ <entry>222000</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.2-RELEASE</entry>
+ <entry>222001</entry>
+ </row>
+
+ <row>
+ <entry>2.2.5-RELEASE</entry>
+ <entry>225000</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.5-RELEASE</entry>
+ <entry>225001</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after ldconfig -R merge</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-STABLE after 2.2.7-RELEASE</entry>
+ <entry>227001</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after semctl(2) change</entry>
+ <entry>227002</entry>
+ </row>
+
+ <row>
+ <entry>2.2.8-RELEASE</entry>
+ <entry>228000</entry>
+ </row>
+
+ <row>
+ <entry>2.2-STABLE after 2.2.8-RELEASE</entry>
+ <entry>228001</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current before mount(2) change</entry>
+ <entry>300000</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after mount(2) change</entry>
+ <entry>300001</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after semctl(2) change</entry>
+ <entry>300002</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after ioctl arg changes</entry>
+ <entry>300003</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after ELF conversion</entry>
+ <entry>300004</entry>
+ </row>
+
+ <row>
+ <entry>3.0-RELEASE</entry>
+ <entry>300005</entry>
+ </row>
+
+ <row>
+ <entry>3.0-current after 3.0-RELEASE</entry>
+ <entry>300006</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </listitem>
+ </itemizedlist>
+
+ <note>
+ <para>Note that 2.2-STABLE sometimes identifies itself as
+ “2.2.5-STABLE” after the 2.2.5-RELEASE. The pattern used to
+ be year followed by the month, but we decided to change it
+ to a more straightforward major/minor system starting from
+ 2.2. This is because the parallel development on several
+ branches made it infeasible to classify the releases simply
+ by their real release dates. If you are making a port now,
+ you don't have to worry about old -current's; they are
+ listed here just for your reference.</para>
+ </note>
+
+
+ <para>In the hundreds of ports that have been done, there have
+ only been one or two cases where <literal>__FreeBSD__</literal>
+ should have been used. Just because an earlier port screwed up
+ and used it in the wrong place does not mean you should do so
+ too.</para>
+ </sect3>
+
+ <sect3>
+ <title>Writing something after
+ <filename>bsd.port.mk</filename></title>
+
+ <para>Do not write anything after the <literal>.include
+ <bsd.port.mk></literal> line. it usually can be avoided by
+ including <filename>bsd.port.pre.mk</filename> somewhere in the
+ middle of your <filename>Makefile</filename> and
+ <filename>bsd.port.post.mk</filename> at the end.</para>
+
+ <note>
+ <para>You need to include either the
+ <filename>pre.mk</filename>/<filename>post.mk</filename> pair or
+ <filename>bsd.port.mk</filename> only; don't mix these
+ two.</para>
+ </note>
+
+ <para><filename>bsd.port.pre.mk</filename> only defines a few
+ variables, which can be used in tests in the
+ <filename>Makefile</filename>,
+ <filename>bsd.port.post.mk</filename> defines the rest.</para>
+
+ <para>Here are some important variables defined in
+ <filename>bsd.port.pre.mk</filename> (this is not the complete
+ list, please read <filename>bsd.port.mk</filename> for the
+ complete list).</para>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Variable</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><makevar>ARCH</makevar></entry>
+ <entry>The architecture as returned by <command>uname
+ -m</command> (e.g., <literal>i386</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>OPSYS</makevar></entry>
+ <entry>The operating system type, as returned by
+ <command>uname -s</command> (e.g.,
+ <literal>FreeBSD</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>OSREL</makevar></entry>
+ <entry>The release version of the operating system (e.g.,
+ <literal>2.1.5</literal> or
+ <literal>2.2.7</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>OSVERSION</makevar></entry>
+ <entry>The numeric version of the operating system, same as
+ <link
+ linkend="porting-versions"><literal>__FreeBSD_version</literal></link>.</entry>
+ </row>
+
+ <row>
+ <entry><makevar>PORTOBJFORMAT</makevar></entry>
+ <entry>The object format of the system
+ (<literal>aout</literal> or <literal>elf</literal></entry>
+ </row>
+
+ <row>
+ <entry><makevar>LOCALBASE</makevar></entry>
+ <entry>The base of the “local” tree (e.g.,
+ <literal>/usr/local/</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>X11BASE</makevar></entry>
+ <entry>The base of the “X11” tree (e.g.,
+ <literal>/usr/X11R6</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>PREFIX</makevar></entry>
+ <entry>Where the port installs itself (see <link
+ linkend="porting-prefix">more on
+ <makevar>PREFIX</makevar></link>).</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <note>
+ <para>If you have to define the variables
+ <makevar>USE_IMAKE</makevar>, <makevar>USE_X_PREFIX</makevar>,
+ or <makevar>MASTERDIR</makevar>, do so before including
+ <filename>bsd.port.pre.mk</filename>.</para>
+ </note>
+
+ <para>Here are some examples of things you can write after
+ <filename>bsd.port.pre.mk</filename>;</para>
+
+ <programlisting>
+# no need to compile lang/perl5 if perl5 is already in system
+.if ${OSVERSION} > 300003
+BROKEN= perl is in system
+.endif
+
+# only one shlib version number for ELF
+.if ${PORTOBJFORMAT} == "elf"
+TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}
+.else
+TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}.${SHLIB_MINOR}
+.endif
+
+# software already makes link for ELF, but not for a.out
+post-install:
+.if ${PORTOBJFORMAT} == "aout"
+ ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so
+.endif</programlisting>
+ </sect3>
+
+ <sect3>
+ <title>Install additional documentation</title>
+
+ <para>If your software has some documentation other than the
+ standard man and info pages that you think is useful for the
+ user, install it under
+ <filename><makevar>PREFIX</makevar>/share/doc</filename>. This can be
+ done, like the previous item, in the <maketarget>post-install</maketarget> target.</para>
+
+ <para>Create a new directory for your port. The directory name
+ should reflect what the port is. This usually means <makevar>PKGNAME</makevar> minus the version part.
+ However, if you think the user might want different versions
+ of the port to be installed at the same time, you can use the
+ whole <makevar>PKGNAME</makevar>.</para>
+
+ <para>Make the installation dependent to the variable
+ <makevar>NOPORTDOCS</makevar> so that users can disable it in
+ <filename>/etc/make.conf</filename>, like this:</para>
+
+ <programlisting>
+post-install:
+.if !defined(NOPORTDOCS)
+ ${MKDIR}${PREFIX}/share/doc/xv
+ ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
+.endif</programlisting>
+
+ <para>Do not forget to add them to
+ <filename>pkg/PLIST</filename> too! (Do not worry about
+ <makevar>NOPORTDOCS</makevar> here; there is currently no way
+ for the packages to read variables from
+ <filename>/etc/make.conf</filename>.)</para>
+
+ <para>Also you can use the <filename>pkg/MESSAGE</filename> file to
+ display messages upon installation. See the <link
+ linkend="porting-message">using
+ <filename>pkg/MESSAGE</filename></link> section for
+ details.</para>
+
+ <note>
+ <para><filename>MESSAGE</filename> does not need to be added
+ to <filename>pkg/PLIST</filename>).</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title><makevar>DIST_SUBDIR</makevar></title>
+
+ <para>Do not let your port clutter
+ <filename>/usr/ports/distfiles</filename>. If your port
+ requires a lot of files to be fetched, or contains a file that
+ has a name that might conflict with other ports (e.g.,
+ <filename>Makefile</filename>), set <makevar>DIST_SUBDIR</makevar> to the name of the
+ port (<makevar>PKGNAME</makevar> without the
+ version part should work fine). This will change <makevar>DISTDIR</makevar> from the default
+ <filename>/usr/ports/distfiles</filename> to
+ <filename>/usr/ports/distfiles/<makevar>DIST_SUBDIR</makevar></filename>,
+ and in effect puts everything that is required for your port
+ into that subdirectory.</para>
+
+ <para>It will also look at the subdirectory with the same name
+ on the backup master site at
+ <filename>ftp.freebsd.org</filename>. (Setting <makevar>DISTDIR</makevar> explicitly in your
+ <makevar>Makefile</makevar> will not accomplish this, so please use <makevar>DIST_SUBDIR</makevar>.)</para>
+
+ <note>
+ <para>This does not affect the <makevar>MASTER_SITES</makevar> you define in your
+ Makefile.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>Package information</title>
+
+ <para>Do include package information, i.e.
+ <filename>COMMENT</filename>, <filename>DESCR</filename>, and
+ <filename>PLIST</filename>, in <filename>pkg</filename>.</para>
+
+ <note>
+ <para>Note that these files are not used only for packaging
+ anymore, and are <emphasis>mandatory</emphasis> now, even if
+ <makevar>NO_PACKAGE</makevar> is
+ set.</para>
+ </note>
+ </sect3>
+
+ <sect3>
+ <title>RCS strings</title>
+
+ <para>Do not put RCS strings in patches. CVS will mangle them
+ when we put the files into the ports tree, and when we check
+ them out again, they will come out different and the patch
+ will fail. RCS strings are surrounded by dollar (<literal>$</literal>) signs, and typically start with
+ <literal>$Id</literal> or <literal>$RCS</literal>.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Recursive diff</title>
+
+ <para>Using the recurse (<option>-r</option>) option to
+ <command>diff</command> to generate patches is
+ fine, but please take a look at the resulting patches to make
+ sure you don't have any unnecessary junk in there. In
+ particular, diffs between two backup files, <filename>Makefiles</filename> when the
+ port uses <command>Imake</command> or GNU <command>configure</command>, etc., are unnecessary and
+ should be deleted. If you had to edit
+ <filename>configure.in</filename> and run
+ <command>autoconf</command> to regenerate
+ <command>configure</command>, do not take the diffs of
+ <command>configure</command> (it often grows to a few thousand
+ lines!); define <literal>USE_AUTOCONF=yes</literal> and take the
+ diffsof <filename>configure.in</filename>.</para>
+
+ <para>Also, if you had to delete a file, then you
+ can do it in the <maketarget>post-extract</maketarget>
+ target rather than as part of the patch. Once you are happy
+ with the resulting diff, please split it up into one source
+ file per patch file.</para>
+
+ </sect3>
+
+ <sect3 id="porting-prefix">
+ <title><makevar>PREFIX</makevar></title>
+
+ <para>Do try to make your port install relative to <makevar>PREFIX</makevar>. (The value of this
+ variable will be set to <makevar>LOCALBASE</makevar> (default
+ <filename>/usr/local</filename>), unless <makevar>USE_X_PREFIX</makevar> or <makevar>USE_IMAKE</makevar> is set, in which case it
+ will be <makevar>X11BASE</makevar> (default
+ <filename>/usr/X11R6</filename>).)</para>
+
+ <para>Not hard-coding <filename>/usr/local</filename> or
+ <filename>/usr/X11R6</filename> anywhere in the source will
+ make the port much more flexible and able to cater to the
+ needs of other sites. For X ports that use <command>imake</command>, this is
+ automatic; otherwise, this can often be done by simply
+ replacing the occurrences of <filename>/usr/local</filename>
+ (or <filename>/usr/X11R6</filename> for X ports that do not
+ use imake) in the various scripts/Makefiles in the port to
+ read <makevar>PREFIX</makevar>, as this
+ variable is automatically passed down to every stage of the
+ build and install processes.</para>
+
+ <para>Do not set <makevar>USE_X_PREFIX</makevar> unless your port
+ truly require it (i.e., it links against X libs or it needs to
+ reference files in <makevar>X11BASE</makevar>).</para>
+
+ <para>The variable <makevar>PREFIX</makevar>
+ can be reassigned in your <filename>Makefile</filename> or in the user's
+ environment. However, it is strongly discouraged for
+ individual ports to set this variable explicitly in the
+ <filename>Makefiles</filename>.</para>
+
+ <para>Also, refer to programs/files from other ports with the
+ variables mentioned above, not explicit pathnames. For
+ instance, if your port requires a macro
+ <literal>PAGER</literal> to be the full pathname of <command>less</command>, use the compiler flag:
+
+ <programlisting>
+-DPAGER=\"${PREFIX}/bin/less\"</programlisting>
+
+ or
+
+ <programlisting>
+-DPAGER=\"${LOCALBASE}/bin/less\"</programlisting>
+
+ if this is an X port, instead of <literal>-DPAGER=\"/usr/local/bin/less\".</literal> This way it will have a better chance of working if the system administrator has moved the whole `/usr/local' tree somewhere else.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Subdirectories</title>
+
+ <para>Try to let the port put things in the right subdirectories
+ of <makevar>PREFIX</makevar>. Some ports
+ lump everything and put it in the subdirectory with the port's
+ name, which is incorrect. Also, many ports put everything
+ except binaries, header files and manual pages in the a
+ subdirectory of <filename>lib</filename>, which does not
+ bode well with the BSD paradigm. Many of the files should be
+ moved to one of the following: <filename>etc</filename>
+ (setup/configuration files), <filename>libexec</filename>
+ (executables started internally), <filename>sbin</filename>
+ (executables for superusers/managers),
+ <filename>info</filename> (documentation for info browser)
+ or <filename>share</filename> (architecture independent
+ files). See man <citerefentry><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+ details, the rule governing <filename>/usr</filename> pretty
+ much applies to <filename>/usr/local</filename> too. The
+ exception are ports dealing with USENET “news”. They may use
+ <filename><makevar>PREFIX</makevar>/news</filename> as a destination for
+ their files.</para>
+
+ </sect3>
+
+ <sect3 id="porting-cleaning">
+ <title>Cleaning up empty directories</title>
+
+ <para>Do make your ports clean up after themselves when they are
+ deinstalled. This is usually accomplished by adding
+ <literal>@dirrm</literal> lines for all directories that are
+ specifically created by the port. You need to delete
+ subdirectories before you can delete parent directories.</para>
+
+ <programlisting>
+ :
+lib/X11/oneko/pixmaps/cat.xpm
+lib/X11/oneko/sounds/cat.au
+ :
+@dirrm lib/X11/oneko/pixmals
+@dirrm lib/X11/oneko/sounds
+@dirrm lib/X11/oneko</programlisting>
+
+ <para>However, sometimes <literal>@dirrm</literal> will give you
+ errors because other ports also share the same subdirectory. You
+ can call <command>rmdir</command> from <literal>@unexec</literal>
+ to remove only empty directories without warning.</para>
+
+ <programlisting>
+@unexec rmdir %D/share/doc/gimp 2>/dev/null || true</programlisting>
+
+ <para>This will neither print any error messages nor cause
+ <command>pkg_delete</command> to exit abnormally even if
+ <filename><makevar>PREFIX</makevar>/share/doc/gimp</filename> is
+ not empty due to other ports installing some files in there.</para>
+ </sect3>
+
+
+ <sect3>
+ <title>UIDs</title>
+
+ <para>If your port requires a certain user to be on the
+ installed system, let the <filename>pkg/INSTALL</filename>
+ script call <command>pw</command> to create it
+ automatically. Look at <filename>net/cvsup-mirror</filename>
+ for an example.</para>
+
+ <para>If your port must use the same user/group ID number when it is
+ installed a binarypackage as when it was compiled, then you mus
+ choose a free UID from 50 to 99 and register it below. Look at
+ <filename>japanese/Wnn</filename> for an example.</para>
+
+ <para>Make sure you don't use a UID already used by the system
+ or other ports. This is the current list of UIDs between 50
+ and 99.</para>
+
+ <programlisting>
+majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent
+cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent
+gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh
+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:/nonexistent
+wnn:*:69:7:Wnn:/nonexistent:/nonexistent
+ifmail:*:70:66:Ifmail user:/nonexistent:/nonexistent
+pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh
+ircd:*:72:72:IRCd hybrid:/nonexistent:/nonexistent
+alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent
+qmaill:*:83:81:QMail user:/var/qmail:/nonexistent
+qmaild:*:82:81:QMail user:/var/qmail:/nonexistent
+qmailq:*:85:82:QMail user:/var/qmail:/nonexistent
+qmails:*:87:82:QMail user:/var/qmail:/nonexistent
+qmailp:*:84:81:QMail user:/var/qmail:/nonexistent
+qmailr:*:86:82:QMail user:/var/qmail:/nonexistent
+msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh</programlisting>
+
+ <para>Please include a notice when you submit a port (or an
+ upgrade) that reserves a new UID or GID in this range. This allows
+ us to keep the list of reserved IDs up to date.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Do things rationally</title>
+
+ <para>The <filename>Makefile</filename> should do things simply and
+ reasonably. If you can make it a couple of lines shorter or more
+ readable, then do so. Examples include using a make
+ <literal>.if</literal> construct instead of a shell
+ <literal>if</literal> construct, not redefining
+ <maketarget>do-extract</maketarget> if you can redefine
+ <makevar>EXTRACT*</makevar> instead, and using
+ <makevar>GNU_CONFIGURE</makevar> instead of
+ <literal>CONFIGURE_ARGS +=
+ --prefix=${PREFIX}</literal>.</para>
+ </sect3>
+
+ <sect3>
+ <title>Respect <makevar>CFLAGS</makevar></title>
+
+ <para>The port should respect the <makevar>CFLAGS</makevar>
+ variable. If it doesn't, please add <literal>NO_PACKAGE=ignores
+ cflags</literal> to the <filename>Makefile</filename>.</para>
+ </sect3>
+
+ <sect3>
+ <title>Configuration files</title>
+
+ <para>If your port requires some configuration files in
+ <filename><makevar>PREFIX</makevar>/etc</filename>, do
+ <emphasis>not</emphasis> just install them and list them in
+ <filename>pkg/PLIST</filename>. That will cause
+ <command>pkg_delete</command> to delete files carefully edited by
+ the user and a new installation to wipe them out.</para>
+
+ <para>Instead, install sample files with a suffix
+ (<filename><replaceable>filename</replaceable>.sample</filename>
+ will work well) and print out a <link
+ linkend="porting-message">message</link> pointing out that the
+ user has to copy and edit the file before the software can be made
+ to work.</para>
+ </sect3>
+
+ <sect3>
+ <title>Portlint</title>
+
+ <para>Do check your work with <link
+ linkend="porting-portlint"><command>portlint</command></link>
+ before you submit or commit it.</para>
+ </sect3>
+
+ <sect3>
+ <title>Feedback</title>
+
+ <para>Do send applicable changes/patches to the original
+ author/maintainer for inclusion in next release of the code. This
+ will only make your job that much easier for the next
+ release.</para>
+ </sect3>
+
+ <sect3>
+ <title>Miscellanea</title>
+
+ <para>The files <filename>pkg/DESCR</filename>,
+ <filename>pkg/COMMENT</filename>, and
+ <filename>pkg/PLIST</filename> should each be double-checked. If
+ you are reviewing a port and feel they can be worded better, do
+ so.</para>
+
+ <para>Don't copy more copies of the GNU General Public License into
+ our system, please.</para>
+
+ <para>Please be careful to note any legal issues! Don't let us
+ illegally distribute software!</para>
+ </sect3>
+
+ <sect3>
+ <title>If you are stuck…</title>
+
+ <para>Do look at existing examples and the
+ <filename>bsd.port.mk</filename> file before asking us
+ questions! <!-- smiley --><emphasis>;)</emphasis></para>
+
+ <para>Do ask us questions if you have any trouble! Do not just
+ beat your head against a wall! <!-- smiley --><emphasis>:)</emphasis></para>
+
+ </sect3>
+ </sect2>
+
+ <sect2 id="porting-samplem">
+ <title>A Sample <filename>Makefile</filename></title>
+
+ <para>Here is a sample <filename>Makefile</filename> that you can
+ use to create a new port. Make sure you remove all the extra
+ comments (ones between brackets)!</para>
+
+ <para>It is recommended that you follow this format (ordering of
+ variables, empty lines between sections, etc.). This format is
+ designed so that the most important information is easy to
+ locate. We recommend that you use <link
+ linkend="porting-portlint">portlint</link> to check the <filename>Makefile</filename>.</para>
+
+ <programlisting>
+[the header...just to make it easier for us to identify the ports.]
+# New ports collection makefile for: xdvi
+[the version required header should updated when upgrading a port.]
+# Version required: pl18 [things like "1.5alpha" are fine here too]
+[this is the date when the first version of this Makefile was created.
+Never change this when doing an update of the port.]
+# Date created: 26 May 1995
+[this is the person who did the original port to FreeBSD, in particular, the
+person who wrote the first version of this Makefile. Remember, this should
+not be changed when upgrading the port later.]
+# Whom: Satoshi Asami <asami@FreeBSD.ORG>
+#
+# $Id$
+[ ^^^^ This will be automatically replaced with RCS ID string by CVS
+when it is committed to our repository.]
+#
+
+[section to describe the port itself and the master site - DISTNAME
+ is always first, followed by PKGNAME (if necessary), CATEGORIES,
+ and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR.
+ After those, one of EXTRACT_SUFX or DISTFILES can be specified too.]
+DISTNAME= xdvi
+PKGNAME= xdvi-pl18
+CATEGORIES= print
+[do not forget the trailing slash ("/")!
+ if you aren't using MASTER_SITE_* macros]
+MASTER_SITES= ${MASTER_SITE_XCONTRIB}
+MASTER_SITE_SUBDIR= applications
+[set this if the source is not in the standard ".tar.gz" form]
+EXTRACT_SUFX= .tar.Z
+
+[section for distributed patches -- can be empty]
+PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/
+PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz
+
+[maintainer; *mandatory*! This is the person (preferably with commit
+ privileges) who a user can contact for questions and bug reports - this
+ person should be the porter or someone who can forward questions to the
+ original porter reasonably promptly. If you really do not want to have
+ your address here, set it to "ports@FreeBSD.ORG".]
+MAINTAINER= asami@FreeBSD.ORG
+
+[dependencies -- can be empty]
+RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript
+LIB_DEPENDS= Xpm.5:${PORTSDIR}/graphics/xpm
+
+[this section is for other standard bsd.port.mk variables that do not
+ belong to any of the above]
+[If it asks questions during configure, build, install...]
+IS_INTERACTIVE= yes
+[If it extracts to a directory other than ${DISTNAME}...]
+WRKSRC= ${WRKDIR}/xdvi-new
+[If the distributed patches were not made relative to ${WRKSRC}, you
+ may need to tweak this]
+PATCH_DIST_STRIP= -p1
+[If it requires a "configure" script generated by GNU autoconf to be run]
+GNU_CONFIGURE= yes
+[If it requires GNU make, not /usr/bin/make, to build...]
+USE_GMAKE= yes
+[If it is an X application and requires "xmkmf -a" to be run...]
+USE_IMAKE= yes
+[et cetera.]
+
+[non-standard variables to be used in the rules below]
+MY_FAVORITE_RESPONSE= "yeah, right"
+
+[then the special rules, in the order they are called]
+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
+
+[and then the epilogue]
+.include <bsd.port.mk></programlisting>
+
+ </sect2>
+
+ <sect2 id="porting-pkgname">
+ <title>Package Names</title>
+
+ <para>The following are the conventions you should follow in
+ naming your packages. This is to have our package directory
+ easy to scan, as there are already lots and lots of packages and
+ users are going to turn away if they hurt their eyes!</para>
+
+ <para>The package name should look like <filename><replaceable>language-</replaceable>name<replaceable>-compiled.specifics</replaceable><replaceable>-version.numbers</replaceable></filename>.</para>
+
+ <para>If your <makevar>DISTNAME</makevar>
+ doesn't look like that, set <makevar>PKGNAME</makevar> to something in that
+ format.</para>
+
+
+ <orderedlist>
+
+ <listitem>
+ <para>FreeBSD strives to support the native language of its
+ users. The <replaceable>language-</replaceable> part should be a two letter
+ abbreviation of the natural language defined by ISO-639 if
+ the port is specific to a certain language. Examples are
+ <literal>ja</literal> for Japanese, <literal>ru</literal> for Russian, <literal>vi</literal> for Vietnamese,
+ <literal>zh</literal> for Chinese, <literal>ko</literal> for Korean and <literal>de</literal> for German.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <filename>name</filename> part
+ should be all lowercases, except for a really large
+ package (with lots of programs in it). Things like
+ XFree86 (yes there really is a port of it, check it
+ out) and ImageMagick fall into this category. Otherwise,
+ convert the name (or at least the first letter) to
+ lowercase. If the capital letters are
+ important to the name (for example, with one-letter names
+ like <literal>R</literal> or <literal>V</literal>) you may use capital letters at your discretion.
+ There is a tradition of naming Perl 5 modules by prepending
+ <literal>p5-</literal> and converting the double-colon separator to a hyphen;
+ for example, the <literal>Data::Dumper</literal> module becomes
+ <literal>p5-Data-Dumper</literal>. If the software in question has numbers,
+ hyphens, or underscores in its name, you may include them as
+ well (like <literal>kinput2</literal>).</para>
+ </listitem>
+
+ <listitem>
+ <para>If the port can be built with different <link linkend="porting-masterdir">hardcoded
+ defaults</link> (usually part of the directory name in a
+ family of ports), the
+ <replaceable>-compiled.specifics</replaceable> part should state the
+ compiled-in defaults (the hyphen is optional). Examples
+ are papersize and font units.</para>
+ </listitem>
+
+ <listitem>
+ <para>The version string should be a period-separated list
+ of integers and single lowercase alphabetics. The only
+ exception is the string <literal>pl</literal> (meaning `patchlevel'), which
+ can be used <emphasis>only</emphasis> when there are no
+ major and minor version numbers in the software.</para>
+ </listitem>
+
+ </orderedlist>
+
+
+ <para>Here are some (real) examples on how to convert a <makevar>DISTNAME</makevar> into a suitable <makevar>PKGNAME</makevar>:</para>
+
+ <informaltable frame="none">
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Distribution Name</entry>
+ <entry>Package Name</entry>
+ <entry>Reason</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>mule-2.2.2.</entry>
+ <entry>mule-2.2.2</entry>
+ <entry>No changes required</entry>
+ </row>
+
+ <row>
+ <entry>XFree86-3.1.2</entry>
+ <entry>XFree86-3.1.2</entry>
+ <entry>No changes required</entry>
+ </row>
+
+ <row>
+ <entry>EmiClock-1.0.2</entry>
+ <entry>emiclock-1.0.2</entry>
+ <entry>No uppercase names for single programs</entry>
+ </row>
+
+ <row>
+ <entry>gmod1.4</entry>
+ <entry>gmod-1.4</entry>
+ <entry>Need a hyphen before version numbers</entry>
+ </row>
+
+ <row>
+ <entry>xmris.4.0.2</entry>
+ <entry>xmris-4.0.2</entry>
+ <entry>Need a hyphen before version numbers</entry>
+ </row>
+
+ <row>
+ <entry>rdist-1.3alpha</entry>
+ <entry>rdist-1.3a</entry>
+ <entry>No strings like <literal>alpha</literal>
+ allowed</entry>
+ </row>
+
+ <row>
+ <entry>es-0.9-beta1</entry>
+ <entry>es-0.9b1</entry>
+ <entry>No strings like <literal>beta</literal>
+ allowed</entry>
+ </row>
+
+ <row>
+ <entry>v3.3beta021.src</entry>
+ <entry>tiff-3.3</entry>
+ <entry>What the heck was that anyway?</entry>
+ </row>
+
+ <row>
+ <entry>tvtwm</entry>
+ <entry>tvtwm-pl11</entry>
+ <entry>Version string always required</entry>
+ </row>
+
+ <row>
+ <entry>piewm</entry>
+ <entry>piewm-1.0</entry>
+ <entry>Version string always required</entry>
+ </row>
+
+ <row>
+ <entry>xvgr-2.10pl1</entry>
+ <entry>xvgr-2.10.1</entry>
+ <entry><literal>pl</literal> allowed only when no
+ major/minor version numbers</entry>
+ </row>
+
+ <row>
+ <entry>gawk-2.15.6</entry>
+ <entry>ja-gawk-2.15.6</entry>
+ <entry>Japanese language version</entry>
+ </row>
+
+ <row>
+ <entry>psutils-1.13</entry>
+ <entry>psutils-letter-1.13</entry>
+ <entry>Papersize hardcoded at package build time</entry>
+ </row>
+
+ <row>
+ <entry>pkfonts</entry>
+ <entry>pkfonts300-1.0</entry>
+ <entry>Package for 300dpi fonts</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>If there is absolutely no trace of version information in
+ the original source and it is unlikely that the original author
+ will ever release another version, just set the version string
+ to <literal>1.0</literal> (like the piewm example above). Otherwise, ask the
+ original author or use the date string (<literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>) as the
+ version.</para>
+
+ </sect2>
+
+ <sect2 id="porting-categories">
+ <title>Categories</title>
+
+ <para>As you already know, ports are classified in several
+ categories. But for this to wor, it is important that porters and
+ users understand what each category and how we deicde what to put in
+ each category.</para>
+
+ <sect3>
+ <title>Current list of categories</title>
+
+ <para>First, this is the current list of port categories. Those
+ marked with an asterisk (<literal>*</literal>) are
+ <emphasis>virtual</emphasis> categories—those that do not
+ have a corresponding subdirectory in the ports tree.</para>
+
+ <note>
+ <para>For non-virtual categories, you will find a one-line
+ description in the <filename>pkg/COMMENT</filename> file in that
+ subdirectory (e.g.,
+ <filename>archivers/pkg/COMMENT</filename>).</para>
+ </note>
+
+ <informaltable frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Category</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><filename>archivers</filename></entry>
+ <entry>Archiving tools.</entry>
+ </row>
+
+ <row>
+ <entry><filename>astro</filename></entry>
+ <entry>Astronomical ports.</entry>
+ </row>
+
+ <row>
+ <entry><filename>audio</filename></entry>
+ <entry>Sound support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>benchmarks</filename></entry>
+ <entry>Benchmarking utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>biology</filename></entry>
+ <entry>Biology-related software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>cad</filename></entry>
+ <entry>Computer aided design tools.</entry>
+ </row>
+
+ <row>
+ <entry><filename>chinese</filename></entry>
+ <entry>Chinese language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>comms</filename></entry>
+ <entry>Communication software. Mostly software to talk to
+ your serial port.</entry>
+ </row>
+
+ <row>
+ <entry><filename>converters</filename></entry>
+ <entry>Character code converters.</entry>
+ </row>
+
+ <row>
+ <entry><filename>databases</filename></entry>
+ <entry>Databases.</entry>
+ </row>
+
+ <row>
+ <entry><filename>deskutils</filename></entry>
+ <entry>Things that used to be on the desktop before
+ computers were invented.</entry>
+ </row>
+
+ <row>
+ <entry><filename>devel</filename></entry>
+ <entry>Development utilities. Do not put libraries here just
+ because they are libraries—unless they truly don't
+ belong to anywhere else, they shouldn't be in this
+ category.</entry>
+ </row>
+
+ <row>
+ <entry><filename>editors</filename></entry>
+ <entry>General editors. Specialized editors go in the
+ section for those tools (e.g., a mathematical-formula
+ editor will go in <filename>math</filename>).</entry>
+ </row>
+
+ <row>
+ <entry><filename>elisp</filename></entry>
+ <entry>Emacs-lisp ports.</entry>
+ </row>
+
+ <row>
+ <entry><filename>emulators</filename></entry>
+ <entry>Emulators for other operating systems. Terminal
+ emulators do <emphasis>not</emphasis> belong
+ here—X-based ones should go to
+ <filename>x11</filename> and text-based ones to either
+ <filename>comms</filename> or <filename>misc</filename>,
+ depending on the exact functionality.</entry>
+ </row>
+
+ <row>
+ <entry><filename>games</filename></entry>
+ <entry>Games.</entry>
+ </row>
+
+ <row>
+ <entry><filename>german</filename></entry>
+ <entry>German language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>graphics</filename></entry>
+ <entry>Graphics utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>japanese</filename></entry>
+ <entry>Japanese language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>kde*</filename></entry>
+ <entry>Ports that form the K Desktop Environment
+ (kde).</entry>
+ </row>
+
+ <row>
+ <entry><filename>korean</filename></entry>
+ <entry>Korean language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>lang</filename></entry>
+ <entry>Programming languages.</entry>
+ </row>
+
+ <row>
+ <entry><filename>mail</filename></entry>
+ <entry>Mail software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>math</filename></entry>
+ <entry>Numerical computation software and other utilities
+ for mathematics.</entry>
+ </row>
+
+ <row>
+ <entry><filename>mbone</filename></entry>
+ <entry>MBone applications.</entry>
+ </row>
+
+ <row>
+ <entry><filename>misc</filename></entry>
+ <entry>Miscellaneous utilities—basically things that
+ doesn't belong to anywhere else. This is the only category
+ that should not appear with any other non-virtual
+ category. If you have <literal>misc</literal> with
+ something else in your <makevar>CATEGORIES</makevar> line,
+ that means you can safely delete <literal>misc</literal>
+ and just put the port in that other subdirectory!</entry>
+ </row>
+
+ <row>
+ <entry><filename>net</filename></entry>
+ <entry>Miscellaneous networking software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>news</filename></entry>
+ <entry>USENET news software.</entry>
+ </row>
+
+ <row>
+ <entry><filename>offix*</filename></entry>
+ <entry>Ports from the OffiX suite.</entry>
+ </row>
+
+ <row>
+ <entry><filename>perl5*</filename></entry>
+ <entry>Ports that require perl version 5 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>pilot*</filename></entry>
+ <entry>Software to use with the 3Com PalmPilot.</entry>
+ </row>
+
+ <row>
+ <entry><filename>plan9</filename></entry>
+ <entry>Various programs from Plan9.</entry>
+ </row>
+
+ <row>
+ <entry><filename>print</filename></entry>
+ <entry>Printing software. Desktop publishing tools
+ (previewers, etc.) belong here too.</entry>
+ </row>
+
+ <row>
+ <entry><filename>python*</filename></entry>
+ <entry>Software written in python.</entry>
+ </row>
+
+ <row>
+ <entry><filename>russian</filename></entry>
+ <entry>Russian language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>security</filename></entry>
+ <entry>Security utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>shells</filename></entry>
+ <entry>Command line shells.</entry>
+ </row>
+
+ <row>
+ <entry><filename>sysutils</filename></entry>
+ <entry>System utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl75*</filename></entry>
+ <entry>Ports that use tcl version 7.5 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl76*</filename></entry>
+ <entry>Ports that use tcl version 7.6 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl80*</filename></entry>
+ <entry>Ports that use tcl version 8.0 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tcl81*</filename></entry>
+ <entry>Ports that use tcl version 8.1 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>textproc</filename></entry>
+ <entry>Text processing utilities. It does not include
+ desktop publishing tools, which go to print/.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk41*</filename></entry>
+ <entry>Ports that use tk version 4.1 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk42*</filename></entry>
+ <entry>Ports that use tk version 4.2 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk80*</filename></entry>
+ <entry>Ports that use tk version 8.0 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>tk81*</filename></entry>
+ <entry>Ports that use tk version 8.1 to run.</entry>
+ </row>
+
+ <row>
+ <entry><filename>vietnamese</filename></entry>
+ <entry>Vietnamese language support.</entry>
+ </row>
+
+ <row>
+ <entry><filename>www</filename></entry>
+ <entry>Software related to the World Wide Web. HTML language
+ support belong here too.</entry>
+ </row>
+
+ <row>
+ <entry>x11</entry>
+ <entry>The X window system and friends. This category is
+ only for software that directly support the window system.
+ Do not put regular X applications here. If your port is
+ an X application, define <makevar>USE_XLIB</makevar>
+ (implied by <makevar>USE_IMAKE</makevar>) and put it in
+ appropriate categories. Also, many of them go into other
+ <filename>x11-*</filename> categories (see below).</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-clocks</filename></entry>
+ <entry>X11 clocks.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-fm</filename></entry>
+ <entry>X11 file managers.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-fonts</filename></entry>
+ <entry>X11 fonts and font utilities.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-toolkits</filename></entry>
+ <entry>X11 toolkits.</entry>
+ </row>
+
+ <row>
+ <entry><filename>x11-wm</filename></entry>
+ <entry>X11 window managers.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect3>
+
+ <sect3>
+ <title>Choosing the right category</title>
+
+ <para>As many of the categories overlap, you often have to choose
+ which of the categories should be the primary category of your
+ port. There are several rules that govern this usse. Here is the
+ list of priorities, in decreasing order of precedence.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Language specific categories alwasys come first. For
+ example, if your port installs Japanese X11 fonts, then your
+ <makevar>CATEGORIES</makevar> line would read
+ <literal>japanese x11</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Specific categories win over less-specific ones. For
+ instance, an HTML editor should be listed as <literal>www
+ editors</literal>, not the other way around. Also, you don't
+ need to list <literal>net</literal> when the port belongs to
+ either of <literal>mail</literal>, <literal>mbone</literal>,
+ <literal>news</literal>, <literal>security</literal>, or
+ <literal>www</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>x11</literal> is used as a secondary category
+ only when the primary category is a natural language. In
+ particular, you should not put <literal>x11</literal> in the
+ category line for X applications.</para>
+ </listitem>
+
+ <listitem>
+ <para>If your port truly does not belong anywhere else, put it
+ in <literal>misc</literal>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>If you are not sure about the category, please put a comment
+ to that effect in your <command>send-pr</command> submission so we
+ can discuss it before import it. (If you are a committer, send a
+ note &a.ports; so we can discuss it first—too often new
+ ports are imported to a wrong category only to be moved right
+ away.)</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Changes to this document and the ports system</title>
+
+ <para>If you maintain a lot of ports, you should consider following
+ the &a.ports;. Important changes to
+ the way ports work will be announced there. You can always
+ find more detailed information on the latest changes by
+ looking at <ulink
+ url="http://www.FreeBSD.ORG/cgi/cvsweb.cgi/src/share/mk/bsd.port.mk">
+ the bsd.port.mk CVS log</ulink>.</para>
+ </sect2>
+
+ <sect2>
+ <title>That is It, Folks!</title>
+
+ <para>Boy, this sure was a long tutorial, wasn't it? Thanks for
+ following us to here, really.</para>
+
+ <para>Well, now that you know how to do a port, let us go at it
+ and convert everything in the world into ports! That is the
+ easiest way to start contributing to the FreeBSD Project!
+ <!-- smiley --><emphasis>:)</emphasis></para>
+
+ </sect2>
+ </sect1>
+
</chapter>
@@ -1053,9 +4516,7 @@ grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up arc
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
- sgml-shorttag: nil
sgml-always-quote-attributes: t
- sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->