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

Added a Dos and Don'ts chapter to the porters guide about the use of

Browse source 
BROKEN, IGNORE, and FORBIDDEN.  Also ran aspell over the document.

Prompted by:	Erwin Lansing <erwin@lansing.dk>
This commit is contained in:
Sean Chittenden 2003-02-07 10:34:14 +00:00
parent d5a877b7e7
commit 7c3d6860bc
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=15940
1 changed files with 80 additions and 10 deletions

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

@ -1197,7 +1197,7 @@ PORTEPOCH= 1</programlisting>
</sect1>
<sect1 id="makefile-categories">
<title>Categorisation</title>
<title>Categorization</title>
<sect2>
<title><makevar>CATEGORIES</makevar></title>
@ -2106,7 +2106,7 @@ DISTFILES= source1.tar.gz:source1 \
they all belong to the special group
<literal>DEFAULT</literal>. If you postfix any
elements with <literal>DEFAULT</literal>, you are just
being reduntant unless you want to have an element
being redundant unless you want to have an element
belonging to both <literal>DEFAULT</literal> and other
groups at the same time (check item <xref
linkend="porting-master-sites-n-comma-operator">).</para>
@ -2185,14 +2185,14 @@ MASTER_SITES= alpha:DEFAULT,SOME_SITE</programlisting>
on the existence of the terminator
<literal>/</literal> to avoid confusing elements
where a <literal>:n</literal> is a valid part of
the element with occurences where
the element with occurrences where
<literal>:n</literal> denotes group
<literal>n</literal>. For compatibility purposes,
since the <literal>/</literal> terminator was not
required before in both
<makevar>MASTER_SITE_SUBDIR</makevar> and
<makevar>PATCH_SITE_SUBDIR</makevar> elements, if
the postfix immediate preceeding character is not
the postfix immediate preceding character is not
a <literal>/</literal> then <literal>:n</literal>
will be considered a valid part of the element
instead of a group postfix even if an element is
@ -2967,7 +2967,7 @@ PATCHFILES= patch1:test</programlisting>
<title>Specifying the working directory</title>
<para>Each port is extracted in to a working directory, which must be
writeable. The ports system assumes that the
writable. The ports system assumes that the
<makevar>DISTFILES</makevar> unpack in to a directory called
<literal>${DISTNAME}</literal>. In other words, if you have
set:</para>
@ -3978,7 +3978,7 @@ ${PREFIX}/man/ja/man4/baz.4.gz</programlisting>
<chapter id="porting-info">
<title>Info files</title>
<para>The new version of texinfo (included in 2.2.2-RELEASE and onwards)
<para>The new version of texinfo (included in 2.2.2-RELEASE and onward)
contains a utility called <command>install-info</command> to add and
delete entries to the <filename>dir</filename> file. If your port
installs any info documents, please follow these instructions so your
@ -4058,7 +4058,7 @@ Options:
(<filename>Makefile</filename> and
<literal>@exec</literal>/<literal>@unexec</literal> of
<filename>pkg-plist</filename>; see below). However, if you have
Japanese (or other multibyte encoding) info files, you will have
Japanese (or other multi-byte encoding) info files, you will have
to use the extra arguments to <command>install-info</command>
because <command>makeinfo</command> cannot handle those texinfo
sources. (See <filename>Makefile</filename> and
@ -4733,7 +4733,7 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
FreeBSD. Use it if the change you are making
<emphasis>only</emphasis> affects FreeBSD. Porting gotchas like
the use of <literal>sys_errlist[]</literal> vs
<function>strerror()</function> are Berkeleyisms, not FreeBSD
<function>strerror()</function> are Berkeley-isms, not FreeBSD
changes.</para>
</listitem>
@ -5454,7 +5454,7 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
</row>
<row>
<entry>5.0-CURRENT after ABI change for discriptor
<entry>5.0-CURRENT after ABI change for descriptor
and creds passing on 64 bit platforms.</entry>
<entry>500025</entry>
</row>
@ -5554,7 +5554,7 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
<row>
<entry>5.0-CURRENT after various changes to disk functions
were made in the name of removing dependancy on disklabel
were made in the name of removing dependency on disklabel
structure internals.</entry>
<entry>500040</entry>
@ -5970,6 +5970,76 @@ drweb:*:426:426:Dr.Web Mail Scanner:/nonexistent:/sbin/nologin</programlisting>
</para>
</sect1>
<sect1 id="dads-broken">
<title>Marking a port <makevar>BROKEN</makevar>, <makevar>FORBIDDEN</makevar>, or otherwise</title>
<para>Invariably there will 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>
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.
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>Makefiles</filename>.</para>
<itemizedlist>
<listitem>
<para><makevar>BROKEN</makevar> is reserved for ports that
don't work and should not be installed by users. This
will prevent users from installing the port, however,
ports marked as <makevar>BROKEN</makevar> will still be
built by <ulink url="http://bento.FreeBSD.org/">the
Bento cluster</ulink>. Do mark ports as
<makevar>BROKEN</makevar> if you want users to not
install this port, but you still want to have it built
by Bento.</para>
</listitem>
<listitem>
<para><makevar>FORBIDDEN</makevar> is used for ports that
do contain a security vulnerability or induce grave
concern regarding the security of a FreeBSD system with
a given port installed (ex: a reputably insecure program
or a program that provides easily exploitable services).
Ports should be marked as <makevar>FORBIDDEN</makevar>
as soon as a particular piece of software has a
vulnerability and there is no released upgrade. Ideally
ports should be upgraded as soon as possible when a
security vulnerability is discovered so as to reduce the
number of vulnerable FreeBSD hosts (we like being known
for being secure), however sometimes there is a
noticeable time gap between disclosure of a
vulnerability and an updated software release of a piece
of vulnerable software. Don't mark a port
<makevar>FORBIDDEN</makevar> for any reason other than
security.</para>
</listitem>
<listitem>
<para><makevar>IGNORE</makevar> is reserved for ports that
should not be built for one reason or another. Users
and <ulink url="http://bento.FreeBSD.org/">the Bento
cluster</ulink> cluster will not, under any
circumstances, build ports marked as
<makevar>IGNORE</makevar>. If in doubt, do use
<makevar>IGNORE</makevar> to prevent a port from being
built.</para>
</listitem>
</itemizedlist>
<para>Do remember that these variables 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>
</sect1>
<sect1 id="dads-misc">
<title>Miscellanea</title>