Date: Sun, 12 Dec 2004 16:49:06 -0600 (CST) From: Mark Linimon <linimon@lonesome.com> To: freebsd-doc@FreeBSD.org Subject: CFD: update to Porter's Handbook to document build Makevars Message-ID: <Pine.LNX.4.44.0412121644060.22127-100000@pancho>
next in thread | raw e-mail | index | archive | help
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.LNX.4.44.0412121644060.22127-100000>