CFD: update to Porter's Handbook to document build Makevars
Mark Linimon
linimon at lonesome.com
Sun Dec 12 22:49:07 UTC 2004
pav just committed some things to disambiguate the meaning of BROKEN
and IGNORE but there's still more to do. In fact, several other
things are completely missing, like NOT_FOR_ARCHS and DEPRECATED.
The following patch attempts to fix all that up. The HTML for the
one page is on http://www.lonesome.com/FreeBSD_doc/dads-noinstall.html.
I plan to commit it unless someone points out any markup bugs.
mcl
Index: book.sgml
===================================================================
RCS file: /home/FreeBSD/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
retrieving revision 1.500
diff -u -r1.500 book.sgml
--- book.sgml 12 Dec 2004 14:15:09 -0000 1.500
+++ book.sgml 12 Dec 2004 21:26:58 -0000
@@ -3484,6 +3484,12 @@
package itself, or else forcing its installation with
<makevar>FORCE_PKG_REGISTER</makevar> will no longer work.
</para>
+
+ <note>
+ <para><makevar>CONFLICTS</makevar> automatically sets
+ <makevar>IGNORE</makevar>, which is more fully documented
+ <link linkend="dads-noinstall">here.</link></para>
+ </note>
</sect1>
<sect1 id="makefile-build">
@@ -5359,8 +5365,8 @@
<para>However, sometimes people forget to put the name of the port
into the Synopsis field in an unambiguous fashion. In that case,
- you can try the <ulink url="http://portsmon.firepipe.net">
- FreeBSD Ports Monitoring System</ulink> (also known as
+ you can try the <link linkend="portsmon">
+ FreeBSD Ports Monitoring System</link> (also known as
<literal>portsmon</literal>). This system attempts to classify
port PRs by portname. To search for PRs about a particular port,
use the <ulink url="http://portsmon.firepipe.net/portoverview.py">
@@ -5498,7 +5504,7 @@
patch or a new version instantly, and you will
only need to update the port promptly with respect to
the author's fix. If the fix is delayed for some reason,
- you should either <link linkend="dads-broken">mark the port as
+ you should either <link linkend="dads-noinstall">mark the port as
<makevar>FORBIDDEN</makevar></link>
or introduce a patch file of your own to the port. In
the case of a vulnerable port, just fix the port as soon as
@@ -7984,38 +7990,36 @@
</para>
</sect1>
- <sect1 id="dads-broken">
- <title>Marking a port <makevar>BROKEN</makevar>, <makevar>FORBIDDEN</makevar>, or otherwise</title>
+ <sect1 id="dads-noinstall">
+ <title>Marking a port <makevar>BROKEN</makevar>, <makevar>FORBIDDEN</makevar>, or otherwise not installable</title>
- <para>Invariably there will come a time when a particular port
+ <para>In certain cases users should be prevented from installing
+ a port. For instance, there may come a time when a particular port
will contain a security vulnerability, will be radically
broken and needs many hours of tender loving care, or is
generally obsoleted, but for one reason or another should
- remain in the tree (and get fixed, right?). To designate a
- port as broken, there are three <command>make</command>
+ remain in the tree (and get fixed, right?). To tell a user that
+ a port should not be installed, there are several <command>make</command>
variables that can be used in a port's
<filename>Makefile</filename>. The value of the following
<command>make</command> variables will be the reason that is
- given back to users for why the port was marked as broken.
+ given back to users for why the port refuses to install itself.
Please use the correct <command>make</command> variable as
each make variable conveys radically different meanings to
- both users, and to automated systems that parse
- <filename>Makefile</filename>s.</para>
+ both users, and to automated systems that depend on the
+ <filename>Makefile</filename>s, such as
+ <link linkend="build-cluster">the ports build cluster</link>,
+ <link linkend="FreshPorts">FreshPorts</link>, and
+ <link linkend="portsmon">portsmon</link>.</para>
<itemizedlist>
<listitem>
<para><makevar>BROKEN</makevar> is reserved for ports that
do not compile or install. This will prevent users
- from wasting their time trying to install the port.</para>
- </listitem>
-
- <listitem>
- <para><makevar>TRYBROKEN</makevar> is used for ports
- if you want to attempt a build of a
- <makevar>BROKEN</makevar> port. Ports marked as
- <makevar>TRYBROKEN</makevar> will be also built by
- <ulink url="http://pointyhat.FreeBSD.org/">the Pointyhat
- cluster</ulink>.</para>
+ from wasting their time trying to install the port.
+ The build cluster will still attempt to try to build
+ them to see if the underlying problem has been
+ resolved.</para>
</listitem>
<listitem>
@@ -8040,23 +8044,80 @@
<listitem>
<para><makevar>IGNORE</makevar> is reserved for ports that
- should not be built for one reason or another. Users
- and <ulink url="http://pointyhat.FreeBSD.org/">the Pointyhat
- cluster</ulink> will not, under any
+ should not be built for some other reason. The build
+ cluster will not, under any
circumstances, build ports marked as
- <makevar>IGNORE</makevar>. The <makevar>IGNORE</makevar>
- variable should also be used for ports that compile but do
- not run properly. If in doubt, do use
- <makevar>IGNORE</makevar> to prevent a port from being
- built.</para>
+ <makevar>IGNORE</makevar>. For instance, use
+ <makevar>IGNORE</makevar> when a port:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>compiles but does not run properly</para>
+ </listitem>
+
+ <listitem>
+ <para>does not work on the installed version of &os;</para>
+ </listitem>
+
+ <listitem>
+ <para>requires &os; kernel sources to build, but the
+ user does not have them installed</para>
+ </listitem>
+
+ <listitem>
+ <para>has a distfile which may not be automatically
+ fetched due to licensing restrictions</para>
+ </listitem>
+
+ <listitem>
+ <para>does not work with a currently installed port</para>
+ </listitem>
+ </itemizedlist>
+
+ <note>
+ <para>If a port would conflict with a currently installed
+ port, <link linkend="conflicts">use
+ <makevar>CONFLICTS</makevar> instead</link>.
+ <makevar>CONFLICTS</makevar> will set
+ <makevar>IGNORE</makevar> by itself.</para>
+ </note>
+
+ <para>If a port sould be marked <makevar>IGNORE</makevar>
+ only on certain architectures, there are two other
+ convenience variables that will automatically set
+ <makevar>IGNORE</makevar> for you:
+ <makevar>ONLY_FOR_ARCHS</makevar> and
+ <makevar>NOT_FOR_ARCHS</makevar>. Examples:</para>
+
+ <programlisting>ONLY_FOR_ARCHS = i386 amd64</programlisting>
+
+ <programlisting>NOT_FOR_ARCHS = alpha ia64 sparc64</programlisting>
</listitem>
</itemizedlist>
- <para>Do remember that these variables are to be used as a
+ <para>Do remember that <makevar>BROKEN</makevar> and
+ <makevar>FORBIDDEN</makevar> are to be used as a
last resort if a port is not upgradeable. Permanently
broken ports should be removed from the tree
entirely.</para>
+
+ <para>When it makes sense to do so, users can be warned about
+ a pending port removal with <makevar>DEPRECATED</makevar>
+ and <makevar>EXPIRATION_DATE</makevar>. The former is
+ simply a string stating why the port is scheduled for removal;
+ the latter is a string in ISO 8601 format (YYYY-MM-DD). Both
+ will be shown to the user.</para>
+
+ <para>It is possible to set <makevar>DEPRECATED</makevar>
+ without an <makevar>EXPIRATION_DATE</makevar> (for
+ instance, recommending a newer version of the port), but
+ the converse does not make any sense.</para>
+
+ <para>There is no policy on how long to give users notice.
+ Current practice seems to be one month for security-related
+ issues and two months for build issues. This also gives any
+ interested committers a little time to fix the problems.</para>
</sect1>
<sect1 id="dads-workarounds">
@@ -8285,7 +8346,7 @@
<para>The &os; Ports Collection is constantly changing. Here is
some information on how to keep up.</para>
- <sect1>
+ <sect1 id="FreshPorts">
<title>FreshPorts</title>
<para>One of the easiest ways to learn about updates that have
@@ -8345,8 +8406,8 @@
</sect1>
- <sect1>
- <title>The &os; Port Building Cluster</title>
+ <sect1 id="build-cluster">
+ <title>The &os; Port Building Cluster on pointyhat</title>
<para>One of the least-publicized strengths of &os; is that
an entire cluster of machines is dedicated to continually
@@ -8356,6 +8417,13 @@
<ulink url="http://pointyhat.FreeBSD.org/">package building logs
and errors</ulink>.</para>
+ <para>Individual ports are built unless they are specifically
+ marked with <makevar>IGNORE</makevar>. Ports that are
+ marked with <makevar>BROKEN</makevar> will still be attempted,
+ to see if the underlying problem has been resolved. (This
+ is done by passing <makevar>TRYBROKEN</makevar> to the
+ port's <filename>Makefile</filename>.)</para>
+
</sect1>
<sect1>
@@ -8376,7 +8444,7 @@
</sect1>
- <sect1>
+ <sect1 id="portsmon">
<title>The &os; Ports Monitoring System</title>
@@ -8396,6 +8464,14 @@
<ulink url="http://portsmon.firepipe.net/portoverview.py">
Overview of One Port</ulink>.</para>
+ <para>As of this writing, this is the only resource available
+ that maps GNATS PR entries to portnames. (PR submitters
+ do not always include the portname in their Synopsis, although
+ we would prefer that they did.) So, <literal>portsmon</literal>)
+ is a good place to start if you want to find out whether an
+ existing port has any PRs filed against it and/or any build
+ errors; or, to find out if a new port that you may be thinking
+ about creating has already been submitted.</para>
</sect1>
</chapter>
More information about the freebsd-doc
mailing list