Rework section on BROKEN, FORBIDDEN, and especially IGNORE. Cross-
reference CONFLICTS in the latter. Add NOT_FOR_ARCHS and ONLY_FOR_ARCHS. While here, tweak references to FreshPorts and portsmon. Reviewed by: simon, pav
This commit is contained in:
Mark Linimon
parent
498c8c74a5
commit
4d39466453
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=23215
1 changed files with 111 additions and 34 deletions
|
|
@ -3484,6 +3484,12 @@ PORTVERSION= 1.0</programlisting>
|
|||
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
|
||||
in <xref linkend="dads-noinstall">.</para>
|
||||
</note>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="makefile-build">
|
||||
|
|
@ -5359,8 +5365,8 @@ IGNORE=POINTYHAT is not supported
|
|||
|
||||
<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 @@ IGNORE=POINTYHAT is not supported
|
|||
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
|
||||
|
|
@ -7990,38 +7996,36 @@ bopm:*:717:</programlisting>
|
|||
</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>
|
||||
|
|
@ -8046,23 +8050,80 @@ bopm:*:717:</programlisting>
|
|||
|
||||
<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 set policy on how much notice to give.
|
||||
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">
|
||||
|
|
@ -8291,7 +8352,7 @@ pre-install:
|
|||
<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
|
||||
|
|
@ -8351,8 +8412,9 @@ pre-install:
|
|||
|
||||
</sect1>
|
||||
|
||||
<sect1>
|
||||
<title>The &os; Port Building Cluster</title>
|
||||
<sect1 id="build-cluster">
|
||||
<title>The &os; Port Building Cluster on
|
||||
<hostid role="hostname">pointyhat.FreeBSD.org</hostid></title>
|
||||
|
||||
<para>One of the least-publicized strengths of &os; is that
|
||||
an entire cluster of machines is dedicated to continually
|
||||
|
|
@ -8362,6 +8424,13 @@ pre-install:
|
|||
<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>
|
||||
|
|
@ -8382,7 +8451,7 @@ pre-install:
|
|||
|
||||
</sect1>
|
||||
|
||||
<sect1>
|
||||
<sect1 id="portsmon">
|
||||
|
||||
<title>The &os; Ports Monitoring System</title>
|
||||
|
||||
|
|
@ -8402,6 +8471,14 @@ pre-install:
|
|||
<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>
|
||||
|
|
|
|||
Loading…
Reference in a new issue