os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Try to clear up the ongoing confusion between the usage of the BROKEN

Browse source 
and IGNORE Makevars.  Include example reasons to use BROKEN and example
usages of both BROKEN and IGNORE.  Remove text made redundant by this.
Finally, to try to make the added text more readable, add some sections
to try to break up the flow.

I would accept the argument that these sections (now 17.18 and 17.19)
now have a sufficient amount of text that they should be moved up one
level to become the new section 17.

Requested by:	many
This commit is contained in:
Mark Linimon 2005-07-22 04:54:42 +00:00
parent f6434bfa46
commit 6898a9706e
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=25201
1 changed files with 80 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

93
en_US.ISO8859-1/books/porters-handbook/book.sgml
View file

@ -9081,14 +9081,11 @@ bacula:*:910:</programlisting>
</sect1>
<sect1 id="dads-noinstall">
<title>Marking a port <makevar>BROKEN</makevar>, <makevar>FORBIDDEN</makevar>, or otherwise not installable</title>
<title>Marking a port not installable with <makevar>BROKEN</makevar>,
<makevar>FORBIDDEN</makevar>, or <makevar>IGNORE</makevar></title>
<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 tell a user that
a port. 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
@ -9102,14 +9099,42 @@ bacula:*:910:</programlisting>
<link linkend="freshports">FreshPorts</link>, and
<link linkend="portsmon">portsmon</link>.</para>
<sect2 id="dads-noinstall-variables">
<title>Variables</title>
<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.
currently do not compile, install, or deinstall correctly.
It should be used for ports where the the problem is
believed to be temporary.
The build cluster will still attempt to try to build
them to see if the underlying problem has been
resolved.</para>
resolved. For instance, use
<makevar>BROKEN</makevar> when a port:</para>
<itemizedlist>
<listitem>
<para>does not compile</para>
</listitem>
<listitem>
<para>fails its configuration or installation process</para>
</listitem>
<listitem>
<para>installs files outside of
<filename>${LOCALBASE}</filename> and
<filename>${X11BASE}</filename></para>
</listitem>
<listitem>
<para>does not remove all its files cleanly upon
deinstall (however, it may be acceptable, and desirable,
for the port to leave user-modified files behind)</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
@ -9134,7 +9159,10 @@ bacula:*:910:</programlisting>
<listitem>
<para><makevar>IGNORE</makevar> is reserved for ports that
should not be built for some other reason. The build
should not be built for some other reason.
It should be used for ports where the the problem is
believed to be structural.
The build
cluster will not, under any
circumstances, build ports marked as
<makevar>IGNORE</makevar>. For instance, use
@ -9160,18 +9188,26 @@ bacula:*:910:</programlisting>
</listitem>
<listitem>
<para>does not work with a currently installed port</para>
<para>does not work with some other currently installed
port (for instance, the port depends on
<filename role="package">www/apache21</filename> but
<filename role="package">www/apache13</filename>
is installed)</para>
</listitem>
</itemizedlist>
<note>
<para>If a port would conflict with a currently installed
port, <link linkend="conflicts">use
port (for example, if they install a file in the same
place that perfoms a different function),
<link linkend="conflicts">use
<makevar>CONFLICTS</makevar> instead</link>.
<makevar>CONFLICTS</makevar> will set
<makevar>IGNORE</makevar> by itself.</para>
</note>
</listitem>
<listitem>
<para>If a port sould be marked <makevar>IGNORE</makevar>
only on certain architectures, there are two other
convenience variables that will automatically set
@ -9186,9 +9222,40 @@ bacula:*:910:</programlisting>
</itemizedlist>
</sect2>
<sect2 id="dads-noinstall-notes">
<title>Implementation Notes</title>
<para>Due to vagaries in the usage of <makevar>IGNORECMD</makevar>
in <filename>bsd.port.mk</filename> among other places,
the value of <makevar>BROKEN</makevar> should be enclosed
in quotes, and the value of <makevar>IGNORE</makevar> should
not be enclosed in quotes.</para>
<para>Also, the wording of the string should be somewhat
different due to the way the information is shown to the
user. Examples:</para>
<programlisting>BROKEN= "this port is unsupported on FreeBSD 5.x"</programlisting>
<programlisting>IGNORE= is unsupported on FreeBSD 5.x</programlisting>
<para>resulting in the following output from
<command>make describe</command>:</para>
<programlisting>===> foobar-0.1 is marked as broken: this port is unsupported on FreeBSD 5.x.</programlisting>
<programlisting>===> foobar-0.1 is unsupported on FreeBSD 5.x.</programlisting>
</sect2>
</sect1>
<sect1 id="dads-deprecated">
<title>Marking a port for removal with <makevar>DEPRECATED</makevar>
or <makevar>EXPIRATION_DATE</makevar></title>
<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
temporary resort if a port is not working. Permanently
broken ports should be removed from the tree
entirely.</para>