Attachment 32291 Details for Bug 53422 – file.diff

[patch] file.diff

file.diff (text/plain), 45.29 KB, created by Mark Linimon on 2003-06-17 21:50:09 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Mark Linimon

Created: 2003-06-17 21:50:09 UTC

Size: 45.29 KB

patch

obsolete

>--- 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&mdash;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"
>+	&mdash;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&mdash;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&mdash;and the associated definitions&mdash;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 &mdash; 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&mdash;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&mdash;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&mdash;X-based ones should go to
>                   <filename>x11</filename> and text-based ones to either
>                   <filename>comms</filename> or <filename>misc</filename>,
>-                  depending on the exact functionality.</entry>
>+                  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&mdash;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&mdash;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.  <emphasis>:-)</emphasis></para>
> 
>+        <para>The format used should be <literal>user@hostname.domain</literal>.
>+          Please do not include any descriptive text such as your real
>+          name in this entry&mdash;that merely confuses
>+          <filename>bsd.port.mk</filename>.  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&mdash;including yourself&mdash;
>+          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>&dollar;{SH} pkg-install &dollar;{PKGNAME}
>           PRE-INSTALL</literal> and the second time as
>           <literal>&dollar;{SH} pkg-install &dollar;{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?
>+          :-).</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=&dollar;{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>

Actions: View | Diff

Attachments on bug 53422: 32291