docs/53422: [patch] rework of parts of Porter's Handbook part 3 of 5: additional content
Mark Linimon
linimon at lonesome.com
Tue Jun 17 20:50:15 UTC 2003
>Number: 53422
>Category: docs
>Synopsis: [patch] rework of parts of Porter's Handbook part 3 of 5: additional content
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: change-request
>Submitter-Id: current-users
>Arrival-Date: Tue Jun 17 13:50:09 PDT 2003
>Closed-Date:
>Last-Modified:
>Originator: Mark Linimon
>Release: FreeBSD-4.7
>Organization:
FreeBSD
>Environment:
System: FreeBSD lonesome.lonesome.com 4.7-STABLE FreeBSD 4.7-STABLE #0: Fri Nov 8 23:46:29 CST 2002 root at lonesome.lonesome.com:/usr/src/sys/compile/MULTIMEDIA i386
>Description:
The Porter's Handbook is insufficiently clear in some places, and
needs expanding in others. As requested I have tried to break
out the rework that I did into several pieces. This third piece
is what adds the main content that I did. Parts 1 and 2 of this
patch represent the factoring-out of the work that I did into
parts that have 1) only to do with style fixes; 2) only have to
do with whitespace. Both are prerequisites for this patch to
apply cleanly.
Translators should note that some of these changes are changed
themselves by parts 4 and 5; these were based on later changes
to the handbook made by others while these patches were still
circulating, and feedback reflecting the concerns of others.
I apologize for any extra work that this will put on you;
however, as these patches have been circulating for some time,
I've had to redo the patches on multiple occasions and this
is about the best I can do. Fortunately several parts of 5)
merely remove some of these changes, as various people
objected to them.
>How-To-Repeat:
n/a
>Fix:
--- book.sgml.style_and_whitespace Mon May 12 21:50:47 2003
+++ book.sgml Mon May 12 22:20:20 2003
@@ -42,10 +42,38 @@
</bookinfo>
+ <chapter id="why-port">
+ <title>Introduction</title>
+
+ <para>The FreeBSD ports collection is the way almost everyone
+ installs applications ("ports") on FreeBSD. Like everything
+ else about FreeBSD, it is primarily a volunteer effort.
+ It's important to keep this in mind when reading this
+ document.</para>
+
+ <para>In FreeBSD, anyone may submit a new port, or volunteer
+ to maintain an existing port if it is unmaintained—you
+ do not need any special commit privileges to do so.
+ Over time, if you gain experience and respect within the
+ developer community, you may eventually gain a ports
+ "commit bit" and thus become a ports "committer"
+ —someone who has the right to commit to the FreeBSD
+ ports CVS tree.</para>
+
+ <para>A typical problem, however, is that there are many
+ more people who want to add new ports than to maintain
+ existing ports, and many more people who want to maintain
+ existing ports than who want to serve as ports committers.
+ Please keep this in mind when deciding whether to port
+ something in the first place—it does not make the project
+ overall look good to have ports in the tree that do not
+ work because they are no longer maintained.</para>
+ </chapter>
+
<chapter id="own-port">
<title>Making a port yourself</title>
- <para>So, now you are interested in making your own port or
+ <para>So, you are still interested in making your own port or
upgrading an existing one? Great!</para>
<para>What follows are some guidelines for creating a new port for
@@ -64,8 +96,9 @@
<para>Only a fraction of the variables
(<makevar><replaceable>VAR</replaceable></makevar>) that can be
overridden 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.
+ are documented at the start of <filename>bsd.port.mk</filename>;
+ the others probably ought to be.
+ Note that this file uses a non-standard tab setting:
<application>Emacs</application> and
<application>Vim</application> should recognize the setting on
loading the file. Both &man.vi.1; and
@@ -79,7 +112,8 @@
<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>
+ is not sufficient, so you will have to read further on into
+ the document.</para>
<para>First, get the original tarball and put it into
<makevar>DISTDIR</makevar>, which defaults to
@@ -134,7 +168,12 @@
<filename>pkg-descr</filename> and
<filename>pkg-plist</filename>. Their
<filename>pkg-</filename> prefix distinguishes them from
- other files.</para>
+ other files. (Note: the former
+ <filename>pkg-comment</filename> files have now been folded
+ into the <filename>Makefile</filename>s themselves as the
+ one-line <literal>COMMENT</literal> variable and are
+ thus deprecated. Please make sure your port does not
+ include them.)</para>
<sect2>
<title><filename>pkg-descr</filename></title>
@@ -497,8 +536,8 @@
make sure all the stages up to that one are completed and call
the real targets or scripts, and they are not intended to be
changed. If you want to fix the extraction, fix
- <maketarget>do-extract</maketarget>, but never ever touch
- <maketarget>extract</maketarget>!</para>
+ <maketarget>do-extract</maketarget>, but never ever change
+ the way <maketarget>extract</maketarget> operates!</para>
</note>
<para>Now that you understand what goes on when the user types
@@ -516,16 +555,26 @@
<emphasis>mainstream</emphasis> sources when and where you
can.</para>
+ <para>You will need to set the variable <makevar>MASTER_SITES</makevar>
+ to reflect where the original tarball resides. You will find
+ convenient shorthand definitions for most mainstream sites
+ in <filename>bsd.sites.mk</filename>. Please use these
+ sites—and the associated definitions—if
+ at all possible, to help avoid the problem of having the same
+ information repeated over again many times in the source base.
+ As these sites tend to change over time, this becomes a
+ maintainence nightmare for everyone involved.</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>
+ server that you control (e.g., your home page).</para>
<para>If you cannot find somewhere convenient and reliable to put the
distfile
we can <quote>house</quote> it ourselves
- on <hostid>ftp.FreeBSD.org</hostid>.
+ on <hostid>ftp.FreeBSD.org</hostid>; however, this is the
+ least-preferred solution, as files housed there tend to get stale.
The distfile must be placed into
<filename>~/public_distfiles/</filename> of someone's
<hostid>freefall</hostid> account.
@@ -535,9 +584,14 @@
<makevar>MASTER_SITE_SUBDIR</makevar> to their
<hostid>freefall</hostid> username.</para>
- <para>If your port's distfile changes all the time for no good reason,
+ <para>If your port's distfile changes all the time without any
+ kind of version update by the author,
consider putting the distfile in your home page and listing it as
- the first <makevar>MASTER_SITES</makevar>. This will prevent users
+ the first <makevar>MASTER_SITES</makevar>. (It is too bad we
+ cannot always talk port authors out of doing this, because it
+ really helps to establish some kind of source code control, but
+ alas this is not always easy). Hosting your own version will
+ prevent users
from getting <errorname>checksum mismatch</errorname> errors, and
also reduce the workload of maintainers of our FTP site. Also, if
there is only one master site for the port, it is recommended that
@@ -583,8 +637,9 @@
<para>In the preparation of the port, files that have been added or
changed can be picked up with a recursive &man.diff.1;
- for later feeding to &man.patch.1;. Each set of patches you
- wish to apply should be collected into a file named
+ for later feeding to &man.patch.1;.
+ Each set of patches you wish to apply should be collected
+ into a file named
<filename>patch-<replaceable>*</replaceable></filename> where
<replaceable>*</replaceable> denotes the sequence in which the
patches will be applied — these are done in
@@ -644,12 +699,13 @@
<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 <filename>Makefile</filename>. This
+ you must set <makevar>IS_INTERACTIVE</makevar> in your Makefile. This
will allow <quote>overnight builds</quote> 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>
+ built). This will save a lot of wasted time on the set of
+ machines that continually build ports (see below).</para>
<para>It is also recommended that if there are reasonable default
answers to the questions, you check the
@@ -669,6 +725,19 @@
and sections in that template to make your port easier for others to
read.</para>
+ <important>
+ <para>There are a large number of port <literal>Makefile</literal>s
+ in the ports collection that get the ordering of these variables
+ wrong. Please do not blindly copy other <literal>Makefile</literal>s
+ from other ports without checking the order of these variables;
+ this just encourages wider propogation of bad usage in the source
+ base. If in doubt of what the <quote>canonical order</quote> of the
+ variables ought to be, try to follow the order in
+ <filename>bsd.port.mk</filename>. (In fact blindly copying
+ other <literal>Makefile</literal>s may encourage even worse
+ brokenness that just the ordering of the variables!)</para>
+ </important>
+
<para>Now, consider the following problems in sequence as you design
your new <filename>Makefile</filename>:</para>
@@ -805,10 +874,12 @@
</itemizedlist>
<para>A rule of thumb is to ask yourself whether a change
- committed to a port is something which someone, somewhere,
+ committed to a port is something which everyone
would benefit from having (either because of an
enhancement, fix, or by virtue that the new package will
- actually work for them). If yes, the
+ actually work at all), and weigh that against that fact
+ that it will cause everyone who regularly updates their
+ ports tree to be compelled to update. If yes, the
<makevar>PORTREVISION</makevar> should be bumped so that
automated tools (e.g. &man.pkg.version.1;)
will highlight the fact that a new package is
@@ -830,7 +901,7 @@
<makevar>PORTEPOCH</makevar> version should be increased.
If <makevar>PORTEPOCH</makevar> is nonzero it is appended
to the package name as described in section 0 above.
- <makevar>PORTEPOCH</makevar> is never decreased or reset
+ <makevar>PORTEPOCH</makevar> must never be decreased or reset
to zero, because that would cause comparison to a package
from an earlier epoch to fail (i.e. the package would not
be detected as out of date): the new version number (e.g.
@@ -840,6 +911,12 @@
automated tools and found to be greater than the implied
suffix <literal>,0</literal> on the earlier package.</para>
+ <para>Dropping or resetting <makevar>PORTEPOCH</makevar>
+ incorrectly is a common error in the ports collection and leads
+ to no end of grief; if you do not understand the above discussion,
+ please keep after it until you do, or ask questions on
+ the mailing lists.</para>
+
<para>It is expected that <makevar>PORTEPOCH</makevar> will
not be used for the majority of ports, and that sensible
use of <makevar>PORTVERSION</makevar> can often pre-empt
@@ -890,7 +967,7 @@
<literal>0.1.0</literal>, not <quote>what comes after
0.9</quote> - oops, too late now). Since the new minor
version <literal>2</literal> is numerically less than the
- previous version <literal>10</literal> the
+ previous version <literal>10</literal>, the
<makevar>PORTEPOCH</makevar> must be bumped to manually
force the new package to be detected as <quote>newer</quote>. Since it
is a new vendor release of the code,
@@ -921,7 +998,12 @@
installed the <literal>gtkmumble-0.10_1</literal> package would not detect
the <literal>gtkmumble-0.3</literal> package as newer, since
<literal>3</literal> is still numerically less than
- <literal>10</literal>.</para>
+ <literal>10</literal>. This is the whole point of
+ <makevar>PORTEPOCH</makevar> in the first place.</para>
+
+ <para>Yes, this is subtle, but again, do not fiddle with
+ the setting of <makevar>PORTEPOCH</makevar> until you
+ understand this!</para>
</note>
</sect3>
</sect2>
@@ -937,11 +1019,11 @@
<literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>.
Make sure this conforms to our <link
linkend="porting-pkgname">guidelines for a good package
- name</link>. In particular, you are not allowed to use a
+ name</link>. In particular, you are <emphasis>not</emphasis> allowed to use a
hyphen (<literal>-</literal>) in
<makevar>PORTVERSION</makevar>. Also, if the package name
has the <replaceable>language-</replaceable> or the
- <replaceable>-compiled.specifics</replaceable> part, use
+ <replaceable>-compiled.specifics</replaceable> part (see below), use
<makevar>PKGNAMEPREFIX</makevar> and
<makevar>PKGNAMESUFFIX</makevar>, respectively. Do not make
them part of <makevar>PORTNAME</makevar>.</para>
@@ -952,7 +1034,7 @@
<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
+ there are already thousands of packages and users are going to
turn away if they hurt their eyes!</para>
<para>The package name should look like
@@ -1216,16 +1298,29 @@
<para>If your 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>
+ category. However, in general, until there are more than a
+ handful of ports which could be reclassified into the category
+ you propose, you will probably be turned down.</para>
+
+ <para>(Aside: occasionally someone proposes redoing the categories
+ as either a 2-level structure, or some other kind of keyword
+ structure. To date, nothing has come of any of these proposals,
+ because while they are very easy to make, the effort involved to
+ retrofit the entire existing ports collection with any kind of
+ reorganization is daunting to say the very least. Please read
+ the history of these proposals in the past mailing lists before
+ you post this idea; further, you should be prepared to be
+ challenged to offer some kind of working prototype.)</para>
</sect2>
<sect2 id="porting-categories">
<title>Current list of categories</title>
- <para>First, this is the current list of port categories. Those
+ <para>Here is the current list of port categories. Those
marked with an asterisk (<literal>*</literal>) are
<emphasis>virtual</emphasis> categories—those that do not have
- a corresponding subdirectory in the ports tree.</para>
+ a corresponding subdirectory in the ports tree. They are only
+ used as secondary categories, and only for search purposes.</para>
<note>
<para>For non-virtual categories, you will find a one-line
@@ -1251,7 +1346,9 @@
<row>
<entry><filename>afterstep*</filename></entry>
- <entry>Ports to support the AfterStep window manager.</entry>
+ <entry>Ports to support the
+ <ulink url="http://www.afterstep.org">
+ AfterStep</ulink> window manager.</entry>
</row>
<row>
@@ -1291,8 +1388,8 @@
<row>
<entry><filename>comms</filename></entry>
- <entry>Communication software. Mostly software to talk to
- your serial port.</entry>
+ <entry>Communication software. (Mostly software to talk to
+ your serial port.)</entry>
</row>
<row>
@@ -1313,17 +1410,17 @@
<row>
<entry><filename>devel</filename></entry>
- <entry>Development utilities. Do not put libraries here just
+ <entry>Development utilities. (Note: do not put libraries here just
because they are libraries—unless they truly do not
belong anywhere else, they should not be in this
- category.</entry>
+ category.)</entry>
</row>
<row>
<entry><filename>editors</filename></entry>
- <entry>General editors. Specialized editors go in the section
+ <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>
+ in <filename>math</filename>) ).</entry>
</row>
<row>
@@ -1333,12 +1430,12 @@
<row>
<entry><filename>emulators</filename></entry>
- <entry>Emulators for other operating systems. Terminal
+ <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>
+ depending on the exact functionality.)</entry>
</row>
<row>
@@ -1353,10 +1450,10 @@
<row>
<entry><filename>ftp</filename></entry>
- <entry>FTP client and server utilities. If your
+ <entry>FTP client and server utilities. (If your
port speaks both FTP and HTTP, put it in
<filename>ftp</filename> with a secondary
- category of <filename>www</filename>.</entry>
+ category of <filename>www</filename>.)</entry>
</row>
<row>
@@ -1371,8 +1468,9 @@
<row>
<entry><filename>gnome*</filename></entry>
- <entry>Ports from the GNU Object Model Environment (GNOME)
- Project.</entry>
+ <entry>Ports from the
+ <ulink url="http://www.gnome.org">GNOME
+ project</ulink>.</entry>
</row>
<row>
@@ -1417,8 +1515,9 @@
<row>
<entry><filename>kde*</filename></entry>
- <entry>Ports from the K Desktop Environment (KDE)
- Project.</entry>
+ <entry>Ports from the
+ <ulink url="http://www.kde.org">K Desktop Environment (KDE)
+ Project</ulink>.</entry>
</row>
<row>
@@ -1455,12 +1554,15 @@
<row>
<entry><filename>misc</filename></entry>
<entry>Miscellaneous utilities—basically things that
- do not belong anywhere else. This is the only category
+ do not belong 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>
+ in that other subdirectory! Also note: if at all possible,
+ try to find a better category for your port than
+ <filename>misc</filename>; ports tend to get overlooked
+ in here.)</entry>
</row>
<row>
@@ -1480,12 +1582,14 @@
<row>
<entry><filename>offix*</filename></entry>
- <entry>Ports from the OffiX suite.</entry>
+ <entry>Ports from the
+ <ulink url="http://leb.net/OffiX/">OffiX</ulink> suite.</entry>
</row>
<row>
<entry><filename>palm</filename></entry>
- <entry>Software support for the Palm(tm) series.</entry>
+ <entry>Software support for the
+ <ulink url="http://www.palm.com/">Palm(tm)</ulink> series.</entry>
</row>
<row>
@@ -1495,17 +1599,21 @@
<row>
<entry><filename>perl5*</filename></entry>
- <entry>Ports that require <literal>perl</literal> version 5 to run.</entry>
+ <entry>Ports that require <command>perl</command> version 5 to run.</entry>
</row>
<row>
<entry><filename>picobsd</filename></entry>
- <entry>Ports to support PicoBSD.</entry>
+ <entry>Ports to support
+ <ulink url="http://people.FreeBSD.org/~picobsd/">
+ PicoBSD</ulink>.</entry>
</row>
<row>
<entry><filename>plan9*</filename></entry>
- <entry>Various programs from Plan9.</entry>
+ <entry>Various programs from
+ <ulink url="http://www.cs.bell-labs.com/plan9dist/">
+ Plan9</ulink>.</entry>
</row>
<row>
@@ -1515,13 +1623,15 @@
<row>
<entry><filename>print</filename></entry>
- <entry>Printing software. Desktop publishing tools
- (previewers, etc.) belong here too.</entry>
+ <entry>Printing software. (Desktop publishing tools
+ (previewers, etc.) belong here too.)</entry>
</row>
<row>
<entry><filename>python*</filename></entry>
- <entry>Software related to the Python language.</entry>
+ <entry>Software related to the
+ <ulink url="http://www.python.org/">Python</ulink>
+ language.</entry>
</row>
<row>
@@ -1584,8 +1694,9 @@
<row>
<entry><filename>textproc</filename></entry>
- <entry>Text processing utilities. It does not include
- desktop publishing tools, which go to <filename>print</filename>.</entry>
+ <entry>Text processing utilities. (This does not include
+ desktop publishing tools, which should go to
+ <filename>print</filename>.)</entry>
</row>
<row>
@@ -1636,19 +1747,19 @@
<row>
<entry><filename>www</filename></entry>
- <entry>Software related to the World Wide Web. HTML language
- support belongs here too.</entry>
+ <entry>Software related to the World Wide Web. (HTML language
+ support belongs here too.)</entry>
</row>
<row>
<entry><filename>x11</filename></entry>
- <entry>The X Window System and friends. This category is only
+ <entry>The X Window System and friends. (This category is only
for software that directly supports the window system. Do not
- put regular X applications here. If your port is an X
+ put regular X applications here; most of them should go
+ into other <filename>x11-*</filename> categories (see below).
+ Note: if your port <emphasis>is</emphasis> an X
application, define <makevar>USE_XLIB</makevar> (implied by
- <makevar>USE_IMAKE</makevar>) and put it in the appropriate
- categories. Also, many of them go into other
- <filename>x11-*</filename> categories (see below).</entry>
+ <makevar>USE_IMAKE</makevar>) ).</entry>
</row>
<row>
@@ -1683,7 +1794,8 @@
<row>
<entry><filename>zope*</filename></entry>
- <entry>Zope support.</entry>
+ <entry><ulink url="http://www.zope.org/">Zope</ulink>
+ support.</entry>
</row>
</tbody>
</tgroup>
@@ -1709,11 +1821,12 @@
<listitem>
<para>Specific categories win over less-specific ones. For
instance, an HTML editor should be listed as <filename>www
- editors</filename>, not the other way around. Also, you do not
- need to list <filename>net</filename> when the port belongs to
+ editors</filename>, not the other way around. Also, you should
+ not list <filename>net</filename> when the port belongs to
any of <filename>irc</filename>, <filename>mail</filename>,
<filename>mbone</filename>, <filename>news</filename>,
- <filename>security</filename>, or <filename>www</filename>.</para>
+ <filename>security</filename>, or <filename>www</filename>, as
+ <filename>net</filename> is included implicitly.</para>
</listitem>
<listitem>
@@ -1743,8 +1856,10 @@
<para>If you are not sure about the category, please put a comment to
that effect in your &man.send-pr.1; submission so we can
discuss it before we import it. If you are a committer, send a note
- to the &a.ports; so we can discuss it first—too often new ports are
- imported to the wrong category only to be moved right away.</para>
+ to the &a.ports; so we can discuss it first. Too often, new ports are
+ imported to the wrong category only to be moved right away.
+ This causes unneccessary, and undesired, bloat in the master
+ source repository.</para>
</sect2>
</sect1>
@@ -1800,9 +1915,10 @@
<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
+ wide-area network problems. (We are hoping to add support
for automatically determining the closest master site and fetching
- from there!</para>
+ from there in the future; having multiple sites will go
+ a long way towards helping this effort.)</para>
<para>If the original tarball is part of one of the popular
archives such as X-contrib, GNU, or Perl CPAN, you may be able
@@ -1848,8 +1964,10 @@
neither of these are set then <makevar>EXTRACT_SUFX</makevar>
defaults to <literal>.tar.gz</literal>.</para>
- <para>You never need to set both <makevar>EXTRACT_SUFX</makevar> and
- <makevar>DISTFILES</makevar>.</para>
+ <note>
+ <para>You never need to set both <makevar>EXTRACT_SUFX</makevar> and
+ <makevar>DISTFILES</makevar>.</para>
+ </note>
</sect2>
<sect2>
@@ -1937,6 +2055,10 @@
sites and subdirectories
(<literal>MASTER_SITES:n</literal>)</title>
+ <para>(Consider this to be a somewhat <quote>advanced topic</quote>;
+ those new to this document may wish to skip this section at first).
+ </para>
+
<para>This section has information on the fetching mechanism
known as both <literal>MASTER_SITES:n</literal> and
<literal>MASTER_SITES_NN</literal>. We will refer to this
@@ -2609,6 +2731,12 @@
<para>Set your mail-address here. Please. <!-- smiley
--><emphasis>:-)</emphasis></para>
+ <para>The format used should be <literal>user at hostname.domain</literal>.
+ Please do not include any descriptive text such as your real
+ name in this entry—that merely confuses
+ <filename>bsd.port.mk</filename>. Instead, put that information
+ into your <filename>pkg-descr</filename>.</para>
+
<para>For a detailed description of the responsibilities of maintainers,
refer to the <ulink url="../developers-handbook/policies.html#POLICIES-MAINTAINER">MAINTAINER on
Makefiles</ulink> section.</para>
@@ -2620,7 +2748,8 @@
<para>This is a one-line description of the port.
<emphasis>Please</emphasis> do not include the package name (or
version number of the software) in the comment. The comment
- should begin with a capital, and end without a period. Here
+ should begin with a capital, end without a period, and
+ should not be surrounded by quotes. Here
is an example:</para>
<programlisting>COMMENT= A cat chasing a mouse all over the screen</programlisting>
@@ -2910,7 +3039,9 @@
<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>
+ environment. This may be particularly desireable if the
+ port has something that takes a long time to rebuild in its
+ dependency list, such as KDE, GNOME, Apache, and so forth.</para>
<para>To depend on another port unconditionally, use the
variable <makevar>${NONEXISTENT}</makevar> as the first field
@@ -2969,13 +3100,34 @@
<makevar>WANT_IMLIB</makevar>, and
<makevar>WANT_GNOME</makevar>.</para>
</sect2>
+
+ <sect2>
+ <title>Circular dependencies are fatal</title>
+
+ <important>
+ <para>Do not introduce any circular dependencies into the
+ ports tree!</para>
+ </important>
+
+ <para>The ports building technology does not tolerate
+ circular dependencies. If you introduce one, you will have
+ someone, somewhere in the world, whose FreeBSD installation will
+ break almost immediately, with many others quickly to follow.
+ These can really be hard to detect, especially with,
+ for instance, the GNOME libraries. If in doubt, before
+ you make that change, make sure you have done the following:
+ <command>cd /usr/ports; make index</command>. That process
+ can be quite slow on older machines, but you may be able to
+ save a large number of people—including yourself—
+ a lot of grief in the process.</para>
+ </sect2>
</sect1>
<sect1 id="makefile-wrkdir">
<title>Specifying the working directory</title>
<para>Each port is extracted in to a working directory, which must be
- writable. The ports system assumes that the
+ writable. The ports system defaults to having the
<makevar>DISTFILES</makevar> unpack in to a directory called
<literal>${DISTNAME}</literal>. In other words, if you have
set:</para>
@@ -2987,7 +3139,7 @@
<filename>foo-1.0</filename>, and the rest of the files are located
under that directory.</para>
- <para>There are a number of variables you can set if that is not the
+ <para>There are a number of variables you can override if that is not the
case.</para>
<sect2>
@@ -3164,8 +3316,10 @@
<para>This variable indicates that although we are allowed to generate
binary packages, we are not allowed to put those packages, or the
- port's <makevar>DISTFILES</makevar>, on to CDROM for resale. The
- <makevar>DISTFILES</makevar> will still be available via FTP.</para>
+ port's <makevar>DISTFILES</makevar>, onto a CDROM (or DVD-ROM)
+ for resale. The
+ <makevar>DISTFILES</makevar> will still be available via FTP
+ (or HTTP if you set it up that way.)</para>
<para><makevar>NO_PACKAGE</makevar> and <makevar>NO_CDROM</makevar>
can be set simultaneously.</para>
@@ -3176,11 +3330,15 @@
<para>Set this variable if the application's license also forbids us
from mirroring the application's <makevar>DISTFILES</makevar> via
- FTP.</para>
+ FTP (or HTTP if you set it up that way.)</para>
<para>Also set this if the application's license has general
restrictions on who may use it, e.g. the application is for
non-commercial use only.</para>
+
+ <para>Note that the port committer should add an entry to
+ <filename>/usr/ports/LEGAL</filename> describing exactly
+ what the restriction entails.</para>
</sect2>
<sect2>
@@ -3563,31 +3721,31 @@
<sect1 id="using-bison">
<title>Using Bison</title>
- <para></para>
+ <para>This section is yet to be written.</para>
</sect1>
<sect1 id="using-java">
<title>Using Java</title>
- <para></para>
+ <para>This section is yet to be written.</para>
</sect1>
<sect1 id="using-python">
<title>Using Python</title>
- <para></para>
+ <para>This section is yet to be written.</para>
</sect1>
<sect1 id="using-emacs">
<title>Using Emacs</title>
- <para></para>
+ <para>This section is yet to be written.</para>
</sect1>
<sect1 id="using-ruby">
<title>Using Ruby</title>
- <para></para>
+ <para>This section is yet to be written.</para>
</sect1>
</chapter>
@@ -3956,7 +4114,8 @@
<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
+ source of your port to reference this wherever the Motif library
+ is referenced in the
<filename>Makefile</filename> or
<filename>Imakefile</filename>.</para>
@@ -3991,7 +4150,7 @@
<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 <application>XFree86 3.3.3</application>. If it does not exist,
+ This directory was new to <application>XFree86 3.3.3</application>. If it does not exist,
please create it, and print out a message urging the user to update
their <application>XFree86</application> to 3.3.3 or newer, or at least add this directory to the
font path in <filename>/etc/XF86Config</filename>.</para>
@@ -4295,7 +4454,7 @@
is installed with &man.pkg.add.1; you can do this via the
<filename>pkg-install</filename> script. This script will
automatically be added to the package, and will be run twice by
- &man.pkg.add.1;. The first time as
+ &man.pkg.add.1;: the first time as
<literal>${SH} pkg-install ${PKGNAME}
PRE-INSTALL</literal> and the second time as
<literal>${SH} pkg-install ${PKGNAME} POST-INSTALL</literal>.
@@ -4344,10 +4503,10 @@
<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 <literal>perl</literal> (e.g.,
+ <literal>4.8</literal>). <literal>%%PERL_VERSION%%</literal> is
+ the full version number of <command>perl</command> (e.g.,
<literal>5.00502</literal>)
- and <literal>%%PERL_VER%%</literal> is the <literal>perl</literal>
+ and <literal>%%PERL_VER%%</literal> is the <command>perl</command>
version number minus
the patchlevel (e.g., <literal>5.005</literal>).</para>
@@ -4476,7 +4635,7 @@
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
+ <para>Avoiding 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
@@ -4533,7 +4692,7 @@
<sect1 id="testing-freshports">
<title>FreshPorts sanity tests</title>
- <para><ulink url="http://www.FreshPorts.org/">FreshPorts</ulink> has
+ <para><ulink url="http://www.FreshPorts.org/"></ulink> has
a sanity test feature which automatically tests each commit to the
FreeBSD ports tree. If subscribed to this service, you will be
notified of any errors which FreshPorts detects during sanity
@@ -4584,6 +4750,12 @@
doing a commit. If the diff is more than about 20KB, please compress
and uuencode it; otherwise, just include it in the PR as is.</para>
+ <para>Finally, please see the
+ <ulink url="../../articles/problem-reports/pr-writing.html">
+ Writing the problem report</ulink> section in the Problem
+ Reports article for more information about how to write
+ useful problem reports.</para>
+
<important>
<para>If your upgrade is motivated by security concerns or a
serious fault in the currently committed port, please notify
@@ -4603,14 +4775,20 @@
<chapter id="porting-dads">
<title>Dos and Don'ts</title>
+ <sect1 id="dads-intro">
+ <title>Introduction</title>
+
<para>Here is a list of common dos and don'ts 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
+ but you can also check ports in the
+ <ulink url="http://www.freebsd.org/cgi/query-pr-summary.cgi?query">
+ PR database</ulink> that others have
submitted. Submit any comments on ports you check as described in
<ulink url="../../articles/contributing/contrib-how.html#CONTRIB-GENERAL">Bug Reports and General
Commentary</ulink>. 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>
+ </sect1>
<sect1 id="dads-strip">
<title>Stripping Binaries</title>
@@ -4678,7 +4856,7 @@
<makevar>WRKDIR</makevar>. <makevar>WRKDIR</makevar> is the only
place that is guaranteed to be writable during the port build (see
<ulink url="../handbook/ports-using.html#PORTS-CD">
- compiling ports from CDROM</ulink> for an
+ installing ports from a CDROM</ulink> for an
example of building ports from a read-only tree). If you need to
modify one of the <filename>pkg-<replaceable>*</replaceable></filename>
files, do so by <link
@@ -4708,7 +4886,7 @@
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
+ so that we can back-port code to older FreeBSD systems and cross-port
to other BSD systems such as 4.4BSD from CSRG, BSD/386, 386BSD,
NetBSD, and OpenBSD.</para>
@@ -4777,13 +4955,13 @@
<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
+ <literal>1</literal>. Later versions always 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
+ system and a FreeBSD 2.x or above 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
@@ -5757,7 +5935,7 @@
<row>
<entry><makevar>OSVERSION</makevar></entry>
- <entry>The numeric version of the operating system, same as
+ <entry>The numeric version of the operating system; same as
<link
linkend="freebsd-versions"><literal>__FreeBSD_version</literal></link>.</entry>
</row>
@@ -5765,7 +5943,9 @@
<row>
<entry><makevar>PORTOBJFORMAT</makevar></entry>
<entry>The object format of the system
- (<literal>aout</literal> or <literal>elf</literal>)</entry>
+ (<literal>elf</literal> or <literal>aout</literal>;
+ note that for <quote>modern</quote> versions of FreeBSD,
+ <literal>aout</literal> is deprecated.)</entry>
</row>
<row>
@@ -5817,6 +5997,11 @@
.if ${PORTOBJFORMAT} == "aout"
${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so
.endif</programlisting>
+
+ <para>You did remember to use tab instead of spaces after
+ <literal>BROKEN=</literal> and
+ <literal>TCL_LIB_FILE=</literal>, did you not?
+ <!-- smiley -->:-).</para>
</sect1>
<sect1 id="dads-documentation">
@@ -5873,7 +6058,7 @@
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
+ not work well with the BSD paradigm. Many of the files should be
moved to one of the following: <filename>etc</filename>
(setup/configuration files), <filename>libexec</filename>
(executables started internally), <filename>sbin</filename>
@@ -5935,7 +6120,8 @@
other ports. This is the current list of UIDs between 50 and
999.</para>
- <programlisting>majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent
+ <programlisting>bind:*:53:53:Bind Sandbox:/:/sbin/nologin
+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
@@ -5982,6 +6168,16 @@
<makevar>EXTRACT*</makevar> instead, and using
<makevar>GNU_CONFIGURE</makevar> instead of <literal>CONFIGURE_ARGS
+= --prefix=${PREFIX}</literal>.</para>
+
+ <para>If you find yourself having to write a whole lot of lines
+ of new code to try to do something, please go back and review
+ <filename>bsd.port.mk</filename> to see if it contains an
+ existing implementation of what you are trying to do. While
+ hard to read, there are a great many seemingly-hard problems for
+ which <filename>bsd.port.mk</filename> already provides a
+ shorthand solution. There is almost nothing in
+ <filename>bsd.port.mk</filename> which was included by
+ accident and is not continually being worked on.</para>
</sect1>
<sect1 id="dads-cc">
@@ -5989,7 +6185,13 @@
<makevar>CXX</makevar></title>
<para>The port should respect both <makevar>CC</makevar>
- and <makevar>CXX</makevar> variables. If it does not,
+ and <makevar>CXX</makevar> variables. What we mean by this
+ is that the port should not set the values of these variables
+ absolutely, overriding existing values; instead, it should append
+ whatever values it needs to the existing values. This is so that
+ build options that affect all ports can be set globally.</para>
+
+ <para>If the port does not respect these variables,
please add <literal>NO_PACKAGE=ignores either cc or
cxx</literal> to the <filename>Makefile</filename>.</para>
@@ -6020,7 +6222,13 @@
<title>Respect <makevar>CFLAGS</makevar></title>
<para>The port should respect the <makevar>CFLAGS</makevar> variable.
- If it does not, please add <literal>NO_PACKAGE=ignores
+ Again, what we mean by this
+ is that the port should not set the value of this variable
+ absolutely, overriding the existing value; instead, it should append
+ whatever values it needs to the existing value. This is so that
+ build options that affect all ports can be set globally.</para>
+
+ <para>Again, if it does not, please add <literal>NO_PACKAGE=ignores
cflags</literal> to the <filename>Makefile</filename>.</para>
<para>An example of a <filename>Makefile</filename> respecting
@@ -6337,7 +6545,8 @@
<para>Other resources to assist port maintainers include a list of
<ulink url="http://bento.FreeBSD.org/">package building logs and
- errors </ulink> and the <ulink
+ errors</ulink> hosted on the <literal>bento cluster</literal>,
+ and also the <ulink
url="http://people.FreeBSD.org/~fenner/portsurvey/">FreeBSD
Ports distfiles survey</ulink>.</para>
</chapter>
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-doc
mailing list