Differential D647 Diff 1229 en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml

Changeset View

Standalone View

en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml

Show All 11 Lines	<chapter xmlns="http://docbook.org/ns/docbook"
<title>Dos and Don'ts</title>		<title>Dos and Don'ts</title>

<sect1 xml:id="dads-intro">		<sect1 xml:id="dads-intro">
<title>Introduction</title>		<title>Introduction</title>

<para>Here is a list of common dos and don'ts that are encountered		<para>Here is a list of common dos and don'ts that are encountered
during the porting process. Check the port against this list,		during the porting process. Check the port against this list,
but also check ports in the <link		but also check ports in the <link
xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">PR		xlink:href="http://bugs.FreeBSD.org/search/">PR
database</link> that others have submitted. Submit any		database</link> that others have submitted. Submit any
comments on ports you check as described in <link		comments on ports as described in <link
xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug		xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug
Reports and General Commentary</link>. Checking ports in the		Reports and General Commentary</link>. Checking ports in the
PR database will both make it faster for us to commit them, and		PR database will both make it faster for us to commit them, and
prove that you know what you are doing.</para>		prove that you know what you are doing.</para>
</sect1>		</sect1>

<sect1 xml:id="porting-wrkdir">		<sect1 xml:id="porting-wrkdir">
<title><varname>WRKDIR</varname></title>		<title><varname>WRKDIR</varname></title>

<para>Do not write anything to files outside		<para>Do not write anything to files outside
<varname>WRKDIR</varname>. <varname>WRKDIR</varname> is the		<varname>WRKDIR</varname>. <varname>WRKDIR</varname> is the
only place that is guaranteed to be writable during the port		only place that is guaranteed to be writable during the port
build (see <link		build (see <link
xlink:href="&url.books.handbook;/ports-using.html#PORTS-CD">		xlink:href="&url.books.handbook;/ports-using.html#PORTS-CD">
installing ports from a CDROM</link> for an example of		installing ports from a CDROM</link> for an example of
building ports from a read-only tree). If you need to modify		building ports from a read-only tree). To modify
one of the <filename>pkg-<replaceable>*</replaceable></filename>		one of <filename>pkg-<replaceable>*</replaceable></filename>,
files, do so by <link linkend="pkg-names">redefining a		do so by <link linkend="pkg-names">redefining a
		wblockUnsubmitted Not Done Inline Actions The <filename>pkg-<replaceable></replaceable></filename> files can be modified by <link linkend="pkg-names">redefining a variable</link> rather than overwriting the file. wblock:* The <filename>pkg-<replaceable>*</replaceable></filename> files can be modified by <link…
variable</link>, not by writing over it.</para>		variable</link>, not by writing over it.</para>
</sect1>		</sect1>

<sect1 xml:id="porting-wrkdirprefix">		<sect1 xml:id="porting-wrkdirprefix">
<title><varname>WRKDIRPREFIX</varname></title>		<title><varname>WRKDIRPREFIX</varname></title>

<para>Make sure your port honors <varname>WRKDIRPREFIX</varname>.		<para>Make sure the port honors <varname>WRKDIRPREFIX</varname>.
Most ports do not have to worry about this. In particular, if		Most ports do not have to worry about this. In particular, when
you are referring to a <varname>WRKDIR</varname> of another		referring to a <varname>WRKDIR</varname> of another
port, note that the correct location is		port, note that the correct location is
<filename>WRKDIRPREFIXPORTSDIR/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename>		<filename>WRKDIRPREFIXPORTSDIR/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename>
not		not
<filename>PORTSDIR/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename>		<filename>PORTSDIR/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename>
or		or
<filename>.CURDIR/../../<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename>		<filename>.CURDIR/../../<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename>
or some such.</para>		or some such.</para>

<para>Also, if you are defining <varname>WRKDIR</varname>		<para>Also, if defining <varname>WRKDIR</varname>,
yourself, make sure you prepend		make sure to prepend
<literal>&dollar;{WRKDIRPREFIX}&dollar;{.CURDIR}</literal> in		<literal>&dollar;{WRKDIRPREFIX}&dollar;{.CURDIR}</literal> in
the front.</para>		the front.</para>
</sect1>		</sect1>

<sect1 xml:id="porting-versions">		<sect1 xml:id="porting-versions">
<title>Differentiating Operating Systems and OS Versions</title>		<title>Differentiating Operating Systems and OS Versions</title>

<para>You may come across code that needs modifications or		<para>When code needs modifications or
		wblockUnsubmitted Not Done Inline Actions Some code needs modifications or wblock: Some code needs modifications or
conditional compilation based upon what version of &os; Unix it		conditional compilation based upon what version of &os; Unix it
is running under. The preferred way to tell &os; versions apart		is running under. The preferred way to tell &os; versions apart
are the <literal>__FreeBSD_version</literal> and		are the <literal>__FreeBSD_version</literal> and
<literal>__FreeBSD__</literal> macros defined in <link		<literal>__FreeBSD__</literal> macros defined in <link
xlink:href="http://svnweb.freebsd.org/base/head/sys/sys/param.h?view=markup">sys/param.h</link>.		xlink:href="http://svnweb.freebsd.org/base/head/sys/sys/param.h?view=markup">sys/param.h</link>.
If this file is not included add the code,</para>		If this file is not included add the code,</para>

<programlisting>#include <sys/param.h></programlisting>		<programlisting>#include <sys/param.h></programlisting>
Show All 16 Lines	#endif</programlisting>
<sect1 xml:id="dads-after-port-mk">		<sect1 xml:id="dads-after-port-mk">
<title>Writing Something After		<title>Writing Something After
<filename>bsd.port.mk</filename></title>		<filename>bsd.port.mk</filename></title>

<para>Do not write anything after the		<para>Do not write anything after the
<literal>.include <bsd.port.mk></literal> line. It		<literal>.include <bsd.port.mk></literal> line. It
usually can be avoided by including		usually can be avoided by including
<filename>bsd.port.pre.mk</filename> somewhere in the middle of		<filename>bsd.port.pre.mk</filename> somewhere in the middle of
your <filename>Makefile</filename> and		the <filename>Makefile</filename> and
<filename>bsd.port.post.mk</filename> at the end.</para>		<filename>bsd.port.post.mk</filename> at the end.</para>

<note>		<important>
<para>Include either the		<para>Include either
<filename>bsd.port.pre.mk</filename>/<filename>bsd.port.post.mk</filename>		<filename>bsd.port.pre.mk</filename>/<filename>bsd.port.post.mk</filename>
pair or <filename>bsd.port.mk</filename> only; do not mix		pair or <filename>bsd.port.mk</filename> only; do not mix
these two usages.</para>		these two usages.</para>
</note>		</important>

<para><filename>bsd.port.pre.mk</filename> only defines a few		<para><filename>bsd.port.pre.mk</filename> only defines a few
variables, which can be used in tests in the		variables, which can be used in tests in the
<filename>Makefile</filename>,		<filename>Makefile</filename>,
<filename>bsd.port.post.mk</filename> defines the rest.</para>		<filename>bsd.port.post.mk</filename> defines the rest.</para>

<para>Here are some important variables defined in		<para>Here are some important variables defined in
<filename>bsd.port.pre.mk</filename> (this is not the complete		<filename>bsd.port.pre.mk</filename> (this is not the complete
list, please read <filename>bsd.port.mk</filename> for the		list, please read <filename>bsd.port.mk</filename> for the
complete list).</para>		complete list).</para>

<informaltable frame="none" pgwide="0">		<informaltable frame="none" pgwide="0">
<tgroup cols="2">		<tgroup cols="2">
<thead>		<thead>
<row>		<row>
<entry>Variable</entry>		<entry>Variable</entry>
<entry>Description</entry>		<entry>Description</entry>
</row>		</row>
</thead>		</thead>

<tbody>		<tbody>
<row>		<row>
<entry><varname>ARCH</varname></entry>		<entry><varname>ARCH</varname></entry>
<entry>The architecture as returned by <command>uname		<entry>The architecture as returned by <command>uname
-m</command> (e.g., <literal>i386</literal>)</entry>		-m</command> (for example, <literal>i386</literal>)</entry>
</row>		</row>

<row>		<row>
<entry><varname>OPSYS</varname></entry>		<entry><varname>OPSYS</varname></entry>
<entry>The operating system type, as returned by		<entry>The operating system type, as returned by
<command>uname -s</command> (e.g.,		<command>uname -s</command> (for example,
<literal>FreeBSD</literal>)</entry>		<literal>FreeBSD</literal>)</entry>
</row>		</row>

<row>		<row>
<entry><varname>OSREL</varname></entry>		<entry><varname>OSREL</varname></entry>
<entry>The release version of the operating system		<entry>The release version of the operating system
(e.g., <literal>2.1.5</literal> or		(for example, <literal>2.1.5</literal> or
<literal>2.2.7</literal>)</entry>		<literal>2.2.7</literal>)</entry>
</row>		</row>

<row>		<row>
<entry><varname>OSVERSION</varname></entry>		<entry><varname>OSVERSION</varname></entry>
<entry>The numeric version of the operating system; the		<entry>The numeric version of the operating system; the
same as <link		same as <link
linkend="freebsd-versions"><literal>__FreeBSD_version</literal></link>.</entry>		linkend="freebsd-versions"><literal>__FreeBSD_version</literal></link>.</entry>
</row>		</row>

<row>		<row>
<entry><varname>LOCALBASE</varname></entry>		<entry><varname>LOCALBASE</varname></entry>
<entry>The base of the <quote>local</quote> tree (e.g.,		<entry>The base of the <quote>local</quote> tree (for example,
<literal>/usr/local</literal>)</entry>		<literal>/usr/local</literal>)</entry>
</row>		</row>

<row>		<row>
<entry><varname>PREFIX</varname></entry>		<entry><varname>PREFIX</varname></entry>

<entry>Where the port installs itself (see		<entry>Where the port installs itself (see
<link linkend="porting-prefix">more on		<link linkend="porting-prefix">more on
<varname>PREFIX</varname></link>).</entry>		<varname>PREFIX</varname></link>).</entry>
</row>		</row>
</tbody>		</tbody>
</tgroup>		</tgroup>
</informaltable>		</informaltable>

<note>		<note>
<para>If you have to define the variable		<para>When <varname>MASTERDIR</varname> is needed, always define
<varname>MASTERDIR</varname>, do so before including		it before including
<filename>bsd.port.pre.mk</filename>.</para>		<filename>bsd.port.pre.mk</filename>.</para>
</note>		</note>

<para>Here are some examples of things you can write after		<para>Here are some examples of things that can be written after
<filename>bsd.port.pre.mk</filename>:</para>		<filename>bsd.port.pre.mk</filename>:</para>

<programlisting># no need to compile lang/perl5 if perl5 is already in system		<programlisting># no need to compile lang/perl5 if perl5 is already in system
.if ${OSVERSION} > 300003		.if ${OSVERSION} > 300003
BROKEN= perl is in system		BROKEN= perl is in system
.endif</programlisting>		.endif</programlisting>

<para>You did remember to use tab instead of spaces after		<para>Always use tab instead of spaces after
<literal>BROKEN=</literal> and		<literal>BROKEN=</literal> and
		wblockUnsubmitted Not Done Inline Actions The rest of the sentence starting with "and" seems unnecessary here. Also, if we must include smileys, they should probably be ☺. wblock: The rest of the sentence starting with "and" seems unnecessary here. Also, if we must include…
<!-- smiley -->:-).</para>		<!-- smiley -->:-).</para>
</sect1>		</sect1>

<sect1 xml:id="dads-sh-exec">		<sect1 xml:id="dads-sh-exec">
<title>Use the <function>exec</function> Statement in Wrapper		<title>Use the <function>exec</function> Statement in Wrapper
Scripts</title>		Scripts</title>

<para>If the port installs a shell script whose purpose is to		<para>If the port installs a shell script whose purpose is to
Show All 10 Lines	<para>The <function>exec</function> statement replaces the shell
<function>exec</function> is omitted, the shell process remains		<function>exec</function> is omitted, the shell process remains
in memory while the program is executing, and needlessly		in memory while the program is executing, and needlessly
consumes system resources.</para>		consumes system resources.</para>
</sect1>		</sect1>

<sect1 xml:id="dads-rational">		<sect1 xml:id="dads-rational">
<title>Do Things Rationally</title>		<title>Do Things Rationally</title>

<para>The <filename>Makefile</filename> should do things simply		<para>The <filename>Makefile</filename> should do things in a
and reasonably. If you can make it a couple of lines shorter or		simple and resaonnable manner. Making it a couple of lines shorter or
		wblockUnsubmitted Not Done Inline Actions s/resaonnable/reasonable/ wblock: s/resaonnable/reasonable/
		wblockUnsubmitted Not Done Inline Actions Spelling: s/reasonnable/reasonable/ wblock: Spelling: s/reasonnable/reasonable/
more readable, then do so. Examples include using a make		more readable, is always better. Examples include using a make
		wblockUnsubmitted Not Done Inline Actions s/,// wblock: s/,//
<literal>.if</literal> construct instead of a shell		<literal>.if</literal> construct instead of a shell
<literal>if</literal> construct, not redefining		<literal>if</literal> construct, not redefining
<buildtarget>do-extract</buildtarget> if you can redefine		<buildtarget>do-extract</buildtarget> if redefining
<varname>EXTRACT*</varname> instead, and using		<varname>EXTRACT*</varname> is enough, and using
<varname>GNU_CONFIGURE</varname> instead of		<varname>GNU_CONFIGURE</varname> instead of
<literal>CONFIGURE_ARGS		<literal>CONFIGURE_ARGS
+= --prefix=&dollar;{PREFIX}</literal>.</para>		+= --prefix=&dollar;{PREFIX}</literal>.</para>

<para>If you find yourself having to write a lot of new code to		<para>If a lot of new code is needed to do something, there may
try to do something, please go back and review		already be an implementation of it in
<filename>bsd.port.mk</filename> to see if it contains an		<filename>bsd.port.mk</filename>. While
existing implementation of what you are trying to do. While
hard to read, there are a great many seemingly-hard problems for		hard to read, there are a great many seemingly-hard problems for
which <filename>bsd.port.mk</filename> already provides a		which <filename>bsd.port.mk</filename> already provides a
shorthand solution.</para>		shorthand solution.</para>
</sect1>		</sect1>

<sect1 xml:id="dads-cc">		<sect1 xml:id="dads-cc">
<title>Respect Both <varname>CC</varname> and		<title>Respect Both <varname>CC</varname> and
<varname>CXX</varname></title>		<varname>CXX</varname></title>

<para>The port must respect both <varname>CC</varname> and		<para>The port must respect both <varname>CC</varname> and
<varname>CXX</varname> variables. What we mean by this is that		<varname>CXX</varname>. What we mean by this is that
the port must not set the values of these variables absolutely,		the port must not set the values of these variables absolutely,
overriding existing values; instead, it may append whatever		overriding existing values; instead, it may append whatever
values it needs to the existing values. This is so that build		values it needs to the existing values. This is so that build
options that affect all ports can be set globally.</para>		options that affect all ports can be set globally.</para>

<para>If the port does not respect these variables,		<para>If the port does not respect these variables,
please add		please add
<literal>NO_PACKAGE=ignores either cc or cxx</literal> to the		<literal>NO_PACKAGE=ignores either cc or cxx</literal> to the
<filename>Makefile</filename>.</para>		<filename>Makefile</filename>.</para>

<para>An example of a <filename>Makefile</filename> respecting		<para>An example of a <filename>Makefile</filename> respecting
both <varname>CC</varname> and <varname>CXX</varname>		both <varname>CC</varname> and <varname>CXX</varname>
variables follows. Note the <varname>?=</varname>:</para>		follows. Note the <literal>?=</literal>:</para>

<programlisting>CC?= gcc</programlisting>		<programlisting>CC?= gcc</programlisting>

<programlisting>CXX?= g++</programlisting>		<programlisting>CXX?= g++</programlisting>

<para>Here is an example which respects neither		<para>Here is an example which respects neither
<varname>CC</varname> nor <varname>CXX</varname>		<varname>CC</varname> nor <varname>CXX</varname>:</para>
variables:</para>

<programlisting>CC= gcc</programlisting>		<programlisting>CC= gcc</programlisting>

<programlisting>CXX= g++</programlisting>		<programlisting>CXX= g++</programlisting>

<para>Both <varname>CC</varname> and <varname>CXX</varname>		<para>Both <varname>CC</varname> and <varname>CXX</varname>
variables can be defined on &os; systems in		can be defined on &os; systems in
<filename>/etc/make.conf</filename>. The first example defines		<filename>/etc/make.conf</filename>. The first example defines
a value if it was not previously set in		a value if it was not previously set in
<filename>/etc/make.conf</filename>, preserving any system-wide		<filename>/etc/make.conf</filename>, preserving any system-wide
definitions. The second example clobbers anything previously		definitions. The second example clobbers anything previously
defined.</para>		defined.</para>
</sect1>		</sect1>

<sect1 xml:id="dads-cflags">		<sect1 xml:id="dads-cflags">
<title>Respect <varname>CFLAGS</varname></title>		<title>Respect <varname>CFLAGS</varname></title>

<para>The port must respect the <varname>CFLAGS</varname>		<para>The port must respect <varname>CFLAGS</varname>.
variable. What we mean by this is that the port must not set		What we mean by this is that the port must not set
the value of this variable absolutely, overriding the existing		the value of this variable absolutely, overriding the existing
value; instead, it may append whatever values it needs to the		value; instead, it may append whatever values it needs to the
		wblockUnsubmitted Not Done Inline Actions Break sentence at semicolon. wblock: Break sentence at semicolon.
existing value. This is so that build options that affect all		existing value. This is so that build options that affect all
ports can be set globally.</para>		ports can be set globally.</para>

<para>If it does not, please add		<para>If it does not, please add
<literal>NO_PACKAGE=ignores cflags</literal> to the		<literal>NO_PACKAGE=ignores cflags</literal> to the
<filename>Makefile</filename>.</para>		<filename>Makefile</filename>.</para>

<para>An example of a <filename>Makefile</filename> respecting		<para>An example of a <filename>Makefile</filename> respecting
the <varname>CFLAGS</varname> variable follows. Note the		<varname>CFLAGS</varname> follows. Not
<varname>+=</varname>:</para>		<literal>+=</literal>:</para>

<programlisting>CFLAGS+= -Wall -Werror</programlisting>		<programlisting>CFLAGS+= -Wall -Werror</programlisting>

<para>Here is an example which does not respect the		<para>Here is an example which does not respect
<varname>CFLAGS</varname> variable:</para>		<varname>CFLAGS</varname>:</para>

<programlisting>CFLAGS= -Wall -Werror</programlisting>		<programlisting>CFLAGS= -Wall -Werror</programlisting>

<para>The <varname>CFLAGS</varname> variable is defined on		<para><varname>CFLAGS</varname> is defined on
&os; systems in <filename>/etc/make.conf</filename>. The first		&os; systems in <filename>/etc/make.conf</filename>. The first
example appends additional flags to the		example appends additional flags to
<varname>CFLAGS</varname> variable, preserving any system-wide		<varname>CFLAGS</varname>, preserving any system-wide
definitions. The second example clobbers anything previously		definitions. The second example clobbers anything previously
defined.</para>		defined.</para>

<para>You should remove optimization flags from the third party		<para>Remove optimization flags from the third party
<filename>Makefile</filename>s. System		<filename>Makefile</filename>s. System
		wblockUnsubmitted Not Done Inline Actions s/System/The system/ wblock: s/System/The system/
<varname>CFLAGS</varname> contains system-wide optimization		<varname>CFLAGS</varname> contains system-wide optimization
flags. An example from an unmodified		flags. An example from an unmodified
<filename>Makefile</filename>:</para>		<filename>Makefile</filename>:</para>

<programlisting>CFLAGS= -O3 -funroll-loops -DHAVE_SOUND</programlisting>		<programlisting>CFLAGS= -O3 -funroll-loops -DHAVE_SOUND</programlisting>

<para>Using system optimization flags, the		<para>Using system optimization flags, the
<filename>Makefile</filename> would look similar to the		<filename>Makefile</filename> would look similar to this
following example:</para>		example:</para>

<programlisting>CFLAGS+= -DHAVE_SOUND</programlisting>		<programlisting>CFLAGS+= -DHAVE_SOUND</programlisting>
</sect1>		</sect1>

<sect1 xml:id="dads-pthread">		<sect1 xml:id="dads-pthread">
<title>Threading Libraries</title>		<title>Threading Libraries</title>

<para>The threading library must be linked to the binaries using		<para>The threading library must be linked to the binaries using
Show All 10 Lines	exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
option is not supported by <command>ld</command>		option is not supported by <command>ld</command>
directly.</para>		directly.</para>
</note>		</note>
</sect1>		</sect1>

<sect1 xml:id="dads-feedback">		<sect1 xml:id="dads-feedback">
<title>Feedback</title>		<title>Feedback</title>

<para>Do send applicable changes/patches to the original		<para>Do send applicable changes/patches to the original
		wblockUnsubmitted Not Done Inline Actions Do send applicable changes and patches to the upstream wblock: Do send applicable changes and patches to the upstream
author/maintainer for inclusion in next release of the code.		author/maintainer for inclusion in next release of the code.
		wblockUnsubmitted Not Done Inline Actions maintainer for inclusion in the next release of the code. wblock: maintainer for inclusion in the next release of the code.
This will only make your job that much easier for the next		This will only make the job that much easier for the next
		wblockUnsubmitted Not Done Inline Actions This makes the next release that much easier. wblock: This makes the next release that much easier.
release.</para>		release.</para>
</sect1>		</sect1>

<sect1 xml:id="dads-readme">		<sect1 xml:id="dads-readme">
<title><filename>README.html</filename></title>		<title><filename>README.html</filename></title>

<para><filename>README.html</filename> is not part of the port,		<para><filename>README.html</filename> is not part of the port,
but generated by <command>make readme</command>. Do not		but generated by <command>make readme</command>. Do not
Show All 14 Lines	<para>Ports that do not have any architecture-dependent files
<literal>NO_ARCH=yes</literal>.</para>		<literal>NO_ARCH=yes</literal>.</para>
</sect1>		</sect1>

<sect1 xml:id="dads-noinstall">		<sect1 xml:id="dads-noinstall">
<title>Marking a Port Not Installable with		<title>Marking a Port Not Installable with
<varname>BROKEN</varname>, <varname>FORBIDDEN</varname>, or		<varname>BROKEN</varname>, <varname>FORBIDDEN</varname>, or
<varname>IGNORE</varname></title>		<varname>IGNORE</varname></title>

<para>In certain cases users should be prevented from installing		<para>In certain cases users must be prevented from installing
a port. To tell a user that a port should not be installed,		a port. To tell a user that a port must not be installed,
		wblockUnsubmitted Not Done Inline Actions s/cases/cases,/ wblock: s/cases/cases,/
		wblockUnsubmitted Not Done Inline Actions There are several variables that can be used in a port's <filename>Makefile</filename> to tell the user that the port cannot be installed. wblock: There are several variables that can be used in a port's <filename>Makefile</filename> to tell…
there are several <command>make</command> variables that can be		there are several <command>make</command> variables that can be
used in a port's <filename>Makefile</filename>. The value of		used in a port's <filename>Makefile</filename>. The value of
the following <command>make</command> variables will be the		these <command>make</command> variables will be the
		wblockUnsubmitted Not Done Inline Actions <command>make</command> is not really needed here. wblock: <command>make</command> is not really needed here.
reason that is given back to users for why the port refuses to		reason that is given back to users for why the port refuses to
		wblockUnsubmitted Not Done Inline Actions s/given back/shown/ wblock: s/given back/shown/
install itself. Please use the correct <command>make</command>		install itself. Please use the correct <command>make</command>
		wblockUnsubmitted Not Done Inline Actions Remove <command>make</command>. wblock: Remove <command>make</command>.
variable as each make variable conveys radically different		variable as each make variable conveys radically different
		wblockUnsubmitted Not Done Inline Actions variable. Each variable conveys radically different wblock: variable. Each variable conveys radically different
meanings to both users, and to automated systems that depend on		meanings to both users, and to automated systems that depend on
		wblockUnsubmitted Not Done Inline Actions meanings, both to users and to automated systems that depend on wblock: meanings, both to users and to automated systems that depend on
the <filename>Makefile</filename>s, such as		the <filename>Makefile</filename>s, such as
		wblockUnsubmitted Not Done Inline Actions "the" is not needed here. wblock: "the" is not needed here.
<link linkend="build-cluster">the ports build cluster</link>,		<link linkend="build-cluster">the ports build cluster</link>,
<link linkend="freshports">FreshPorts</link>, and		<link linkend="freshports">FreshPorts</link>, and
<link linkend="portsmon">portsmon</link>.</para>		<link linkend="portsmon">portsmon</link>.</para>

<sect2 xml:id="dads-noinstall-variables">		<sect2 xml:id="dads-noinstall-variables">
<title>Variables</title>		<title>Variables</title>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para><varname>BROKEN</varname> is reserved for ports that		<para><varname>BROKEN</varname> is reserved for ports that
currently do not compile, install, deinstall, or run		currently do not compile, install, deinstall, or run
correctly. It should be used for ports where the problem		correctly. Use it for ports where the problem
is believed to be temporary.</para>		is believed to be temporary.</para>

<para>If instructed, the build cluster will still attempt		<para>If instructed, the build cluster will still attempt
to try to build them to see if the underlying problem has		to try to build them to see if the underlying problem has
been resolved. (However, in general, the cluster is run		been resolved. (However, in general, the cluster is run
without this.)</para>		without this.)</para>

<para>For instance, use <varname>BROKEN</varname> when a		<para>For instance, use <varname>BROKEN</varname> when a
Show All 27 Lines	supposed to run fine.</para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>
</listitem>		</listitem>

<listitem>		<listitem>
<para><varname>FORBIDDEN</varname> is used for ports that		<para><varname>FORBIDDEN</varname> is used for ports that
contain a security vulnerability or induce grave concern		contain a security vulnerability or induce grave concern
regarding the security of a &os; system with a given port		regarding the security of a &os; system with a given port
installed (e.g., a reputably insecure program or a program		installed (for example, a reputably insecure program or a program
that provides easily exploitable services). Ports should		that provides easily exploitable services). Mark ports
be marked as <varname>FORBIDDEN</varname> as soon as a		as <varname>FORBIDDEN</varname> as soon as a
particular piece of software has a vulnerability and there		particular piece of software has a vulnerability and there
is no released upgrade. Ideally ports should be upgraded		is no released upgrade. Ideally upgrade ports
as soon as possible when a security vulnerability is		as soon as possible when a security vulnerability is
discovered so as to reduce the number of vulnerable &os;		discovered so as to reduce the number of vulnerable &os;
hosts (we like being known for being secure), however		hosts (we like being known for being secure), however
sometimes there is a noticeable time gap between		sometimes there is a noticeable time gap between
disclosure of a vulnerability and an updated release of		disclosure of a vulnerability and an updated release of
the vulnerable software. Do not mark a port		the vulnerable software. Do not mark a port
<varname>FORBIDDEN</varname> for any reason other than		<varname>FORBIDDEN</varname> for any reason other than
security.</para>		security.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para><varname>IGNORE</varname> is reserved for ports that		<para><varname>IGNORE</varname> is reserved for ports that
should not be built for some other reason. It should be		must not be built for some other reason. Use it
used for ports where the problem is believed to be		for ports where the problem is believed to be
structural. The build cluster will not, under any		structural. The build cluster will not, under any
circumstances, build ports marked as		circumstances, build ports marked as
<varname>IGNORE</varname>. For instance, use		<varname>IGNORE</varname>. For instance, use
<varname>IGNORE</varname> when a port:</para>		<varname>IGNORE</varname> when a port:</para>

<itemizedlist>		<itemizedlist>
<listitem>		<listitem>
<para>does not work on the installed version of		<para>does not work on the installed version of
Show All 21 Lines	<note>
<link linkend="conflicts">use		<link linkend="conflicts">use
<varname>CONFLICTS</varname> instead</link>.		<varname>CONFLICTS</varname> instead</link>.
<varname>CONFLICTS</varname> will set		<varname>CONFLICTS</varname> will set
<varname>IGNORE</varname> by itself.</para>		<varname>IGNORE</varname> by itself.</para>
</note>		</note>
</listitem>		</listitem>

<listitem>		<listitem>
<para>If a port should be marked <varname>IGNORE</varname>		<para>To mark a port as <varname>IGNORE</varname>d
only on certain architectures, there are two other		only on certain architectures, there are two other
convenience variables that will automatically set		convenience variables that will automatically set
<varname>IGNORE</varname> for you:		<varname>IGNORE</varname>:
<varname>ONLY_FOR_ARCHS</varname> and		<varname>ONLY_FOR_ARCHS</varname> and
<varname>NOT_FOR_ARCHS</varname>. Examples:</para>		<varname>NOT_FOR_ARCHS</varname>. Examples:</para>

<programlisting>ONLY_FOR_ARCHS= i386 amd64</programlisting>		<programlisting>ONLY_FOR_ARCHS= i386 amd64</programlisting>

<programlisting>NOT_FOR_ARCHS= ia64 sparc64</programlisting>		<programlisting>NOT_FOR_ARCHS= ia64 sparc64</programlisting>

<para>A custom <varname>IGNORE</varname> message can be		<para>A custom <varname>IGNORE</varname> message can be
set using <varname>ONLY_FOR_ARCHS_REASON</varname> and		set using <varname>ONLY_FOR_ARCHS_REASON</varname> and
<varname>NOT_FOR_ARCHS_REASON</varname>. Per		<varname>NOT_FOR_ARCHS_REASON</varname>. Per
architecture entries are possible with		architecture entries are possible with
<varname>ONLY_FOR_ARCHS_REASON_<replaceable>ARCH</replaceable></varname>		<varname>ONLY_FOR_ARCHS_REASON_<replaceable>ARCH</replaceable></varname>
and		and
<varname>NOT_FOR_ARCHS_REASON_<replaceable>ARCH</replaceable></varname>.</para>		<varname>NOT_FOR_ARCHS_REASON_<replaceable>ARCH</replaceable></varname>.</para>
</listitem>		</listitem>

<listitem>		<listitem>
<para>If a port fetches i386 binaries and installs them,		<para>If a port fetches i386 binaries and installs them,
<varname>IA32_BINARY_PORT</varname> should be set. If		set <varname>IA32_BINARY_PORT</varname>. If
this variable is set, it will be checked whether the		this variable is set, it will be checked whether
		wblockUnsubmitted Not Done Inline Actions "it will be checked" is ambiguous. If this variable is set, <filename>/usr/lib32</filename> must be present for IA32 versions of libraries and the kernel must support IA32 compatibility. wblock: "it will be checked" is ambiguous. If this variable is set, <filename>/usr/lib32</filename>…
<filename>/usr/lib32</filename> directory is available for		<filename>/usr/lib32</filename> is available for
IA32 versions of libraries and whether the kernel has IA32		IA32 versions of libraries and whether the kernel has IA32
compatibility compiled in. If one of these two		compatibility compiled in. If one of these two
dependencies is not satisfied, <varname>IGNORE</varname>		dependencies is not satisfied, <varname>IGNORE</varname>
will be set automatically.</para>		will be set automatically.</para>
</listitem>		</listitem>
</itemizedlist>		</itemizedlist>
</sect2>		</sect2>

<sect2 xml:id="dads-noinstall-notes">		<sect2 xml:id="dads-noinstall-notes">
<title>Implementation Notes</title>		<title>Implementation Notes</title>

<para>The strings should not be quoted. Also, the wording of		<para>Do not quote the values of <varname>BROKEN</varname>,
		antoineUnsubmitted Not Done Inline Actions the strings? antoine: the strings?
		wblockUnsubmitted Not Done Inline Actions It's a little ambiguous. Maybe "any of these strings". Also, s/note/not/ wblock: It's a little ambiguous. Maybe "any of these strings". Also, s/note/not/
		wblockUnsubmitted Not Done Inline Actions "should be" is okay here, it is making a recommendation. But this sentence is vague. It's hard to tell what it is saying. The string should be different... from what? I think it is saying that the wording of the message depends on which variable is used. The example shows that BROKEN and IGNORE are worded differently. wblock: "should be" is okay here, it is making a recommendation. But this sentence is vague. It's…
the string should be somewhat different due to the way the		<varname>IGNORE</varname>, and related variables. Also, due
		wblockUnsubmitted Not Done Inline Actions Due to the way the information is shown to the user, the wording of messages for each variable differ:</para> wblock: Due to the way the information is shown to the user, the wording of messages for each variable…
information is shown to the user. Examples:</para>		to the way the information is shown to the user, their
		wordings should be different. Examples:</para>

<programlisting>BROKEN= fails to link with base -lcrypto</programlisting>		<programlisting>BROKEN= fails to link with base -lcrypto</programlisting>

<programlisting>IGNORE= unsupported on recent versions</programlisting>		<programlisting>IGNORE= unsupported on recent versions</programlisting>

<para>resulting in the following output from		<para>resulting in this output from
<command>make describe</command>:</para>		<command>make describe</command>:</para>

<programlisting>===> foobar-0.1 is marked as broken: fails to link with base -lcrypto.</programlisting>		<programlisting>===> foobar-0.1 is marked as broken: fails to link with base -lcrypto.</programlisting>

<programlisting>===> foobar-0.1 is unsupported on recent versions.</programlisting>		<programlisting>===> foobar-0.1 is unsupported on recent versions.</programlisting>
</sect2>		</sect2>
</sect1>		</sect1>

<sect1 xml:id="dads-deprecated">		<sect1 xml:id="dads-deprecated">
<title>Marking a Port for Removal with		<title>Marking a Port for Removal with
<varname>DEPRECATED</varname> or		<varname>DEPRECATED</varname> or
<varname>EXPIRATION_DATE</varname></title>		<varname>EXPIRATION_DATE</varname></title>

<para>Do remember that <varname>BROKEN</varname> and		<para>Do remember that <varname>BROKEN</varname> and
<varname>FORBIDDEN</varname> are to be used as a temporary		<varname>FORBIDDEN</varname> are to be used as a temporary
resort if a port is not working. Permanently broken ports		resort if a port is not working. Permanently broken ports
should be removed from the tree entirely.</para>		will be removed from the tree entirely.</para>

<para>When it makes sense to do so, users can be warned about		<para>When it makes sense to do so, users can be warned about
a pending port removal with <varname>DEPRECATED</varname> and		a pending port removal with <varname>DEPRECATED</varname> and
<varname>EXPIRATION_DATE</varname>. The former is simply a		<varname>EXPIRATION_DATE</varname>. The former is a
string stating why the port is scheduled for removal; the latter		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		is a string in ISO 8601 format (YYYY-MM-DD). Both will be shown
to the user.</para>		to the user.</para>

<para>It is possible to set <varname>DEPRECATED</varname>		<para>It is possible to set <varname>DEPRECATED</varname>
without an <varname>EXPIRATION_DATE</varname> (for instance,		without an <varname>EXPIRATION_DATE</varname> (for instance,
recommending a newer version of the port), but the converse		recommending a newer version of the port), but the converse
does not make any sense.</para>		does not make any sense.</para>
▲ Show 20 Lines • Show All 42 Lines • ▼ Show 20 Lines	<sect1 xml:id="dads-sysctl">
<title>Usage of <filename>sysctl</filename></title>		<title>Usage of <filename>sysctl</filename></title>

<para>The usage of <filename>sysctl</filename> is discouraged		<para>The usage of <filename>sysctl</filename> is discouraged
except in targets. This is because the evaluation of any		except in targets. This is because the evaluation of any
<literal>makevar</literal>s, such as used during		<literal>makevar</literal>s, such as used during
<command>make index</command>, then has to run the command,		<command>make index</command>, then has to run the command,
further slowing down that process.</para>		further slowing down that process.</para>

<para>Usage of &man.sysctl.8; should always be done with the		<para>Only use &man.sysctl.8; through
<varname>SYSCTL</varname> variable, as it contains the fully		<varname>SYSCTL</varname>, as it contains the fully
qualified path and can be overridden, if one has such a		qualified path and can be overridden, if one has such a
special need.</para>		special need.</para>
</sect1>		</sect1>

<sect1 xml:id="dads-rerolling-distfiles">		<sect1 xml:id="dads-rerolling-distfiles">
<title>Rerolling Distfiles</title>		<title>Rerolling Distfiles</title>

<para>Sometimes the authors of software change the content of		<para>Sometimes the authors of software change the content of
released distfiles without changing the file's name. You have		released distfiles without changing the file's name.
to verify that the changes are official and have been performed		Check that the changes are official and have been performed
		wblockUnsubmitted Not Done Inline Actions s/Check/Verify/ wblock: s/Check/Verify/
by the author. It has happened in the past that the distfile		by the author. It has happened in the past that the distfile
was silently altered on the download servers with the intent to		was silently altered on the download servers with the intent to
cause harm or compromise end user security.</para>		cause harm or compromise end user security.</para>

<para>Put the old distfile aside, download the new one, unpack		<para>Put the old distfile aside, download the new one, unpack
them and compare the content with &man.diff.1;. If you see		them and compare the content with &man.diff.1;. If there is
nothing suspicious, you can update		nothing suspicious, update
<filename>distinfo</filename>. Be sure to summarize the		<filename>distinfo</filename>. Be sure to summarize the
differences in your PR or commit log, so that other people know		differences in the PR or commit log, so that other people know
that you have taken care to ensure that nothing bad has		that nothing bad has
happened.</para>		happened.</para>

<para>You might also want to contact the authors of the software		<para>Maybe also contact the authors of the software
		wblockUnsubmitted Not Done Inline Actions s/Maybe also contact/Contact/ wblock: s/Maybe also contact/Contact/
and confirm the changes with them.</para>		and confirm the changes with them.</para>
</sect1>		</sect1>

<sect1 xml:id="dads-avoiding-linuxisms">		<sect1 xml:id="dads-avoiding-linuxisms">
<title>Avoiding Linuxisms</title>		<title>Avoiding Linuxisms</title>

<para>Do not use <filename>/proc</filename> if there are any		<para>Do not use <filename>/proc</filename> if there are any
other ways of getting the information, e.g.,		other ways of getting the information, for example,
		wblockUnsubmitted Not Done Inline Actions Break sentence after "information". wblock: Break sentence after "information".
<function>setprogname(argv[0])</function> in		<function>setprogname(argv[0])</function> in
<function>main()</function> and then &man.getprogname.3; if		<function>main()</function> and then &man.getprogname.3;
you want to <quote>know your name</quote>.</para>		to <quote>know the executable name</quote>.</para>
		wblockUnsubmitted Not Done Inline Actions The quotes seem unnecessary. to get the executable name. wblock: The quotes seem unnecessary. to get the executable name.

<para>Do not rely on behaviour that is undocumented by		<para>Do not rely on behaviour that is undocumented by
		wblockUnsubmitted Not Done Inline Actions s/behaviour/behavior/ wblock: s/behaviour/behavior/
<acronym>POSIX</acronym>.</para>		<acronym>POSIX</acronym>.</para>

<para>Do not record timestamps in the critical path of the		<para>Do not record timestamps in the critical path of the
application if it also works without. Getting timestamps may be		application if it also works without. Getting timestamps may be
slow, depending on the accuracy of timestamps in the		slow, depending on the accuracy of timestamps in the
<acronym>OS</acronym>. If timestamps are really needed,		<acronym>OS</acronym>. If timestamps are really needed,
determine how precise they have to be and use an		determine how precise they have to be and use an
<acronym>API</acronym> which is documented to just deliver the		<acronym>API</acronym> which is documented to just deliver the
Show All 29 Lines	<para>Do not assume that <filename>/bin/sh</filename> is
passed to &man.system.3; will work with a		passed to &man.system.3; will work with a
<acronym>POSIX</acronym> compliant shell.</para>		<acronym>POSIX</acronym> compliant shell.</para>

<para>A list of common <application>bash</application>isms is		<para>A list of common <application>bash</application>isms is
available <link		available <link
xlink:href="https://wiki.ubuntu.com/DashAsBinSh">here</link>.</para>		xlink:href="https://wiki.ubuntu.com/DashAsBinSh">here</link>.</para>

<para>Check that headers are included in the		<para>Check that headers are included in the
<acronym>POSIX</acronym> or man page recommended way, e.g.,		<acronym>POSIX</acronym> or man page recommended way, for example,
		wblockUnsubmitted Not Done Inline Actions Break sentence after "way". wblock: Break sentence after "way".
<filename>sys/types.h</filename> is often forgotten, which is		<filename>sys/types.h</filename> is often forgotten, which is
not as much of a problem for &linux; as it is for &os;.</para>		not as much of a problem for &linux; as it is for &os;.</para>

<para>Compile threaded applications with		<para>Compile threaded applications with
<quote>-pthread</quote>, not <quote>-lpthread</quote> or		<quote>-pthread</quote>, not <quote>-lpthread</quote> or
variations thereof.</para>		variations thereof.</para>
</sect1>		</sect1>

<sect1 xml:id="dads-misc">		<sect1 xml:id="dads-misc">
<title>Miscellanea</title>		<title>Miscellanea</title>

<para>The files <filename>pkg-descr</filename> and		<para>Always double-check <filename>pkg-descr</filename> and
<filename>pkg-plist</filename> should each be double-checked.		<filename>pkg-plist</filename>.
If you are reviewing a port and feel they can be worded better,		If reviewing a port and a better wording can be achieved,
do so.</para>		do so.</para>

<para>Do not copy more copies of the GNU General Public License		<para>Do not copy more copies of the GNU General Public License
into our system, please.</para>		into our system, please.</para>

<para>Please be careful to note any legal issues! Do not let us		<para>Please be careful to note any legal issues! Do not let us
illegally distribute software!</para>		illegally distribute software!</para>
</sect1>		</sect1>
</chapter>		</chapter>