svn commit: r43852 - head/en_US.ISO8859-1/books/porters-handbook/porting-dads
Warren Block
wblock at FreeBSD.org
Sun Feb 9 23:16:50 UTC 2014
Author: wblock
Date: Sun Feb 9 23:16:49 2014
New Revision: 43852
URL: http://svnweb.freebsd.org/changeset/doc/43852
Log:
Whitespace-only fixes, translators please ignore.
Modified:
head/en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml
Modified: head/en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml Sun Feb 9 08:19:54 2014 (r43851)
+++ head/en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml Sun Feb 9 23:16:49 2014 (r43852)
@@ -5,720 +5,715 @@
$FreeBSD$
-->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="porting-dads">
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="porting-dads">
+
+ <title>Dos and Don'ts</title>
+
+ <sect1 xml:id="dads-intro">
+ <title>Introduction</title>
+
+ <para>Here is a list of common dos and don'ts that are encountered
+ during the porting process. Check the port against this list,
+ but also check ports in the <link
+ xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">PR
+ database</link> that others have submitted. Submit any
+ comments on ports you check as described in <link
+ xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug
+ Reports and General Commentary</link>. Checking ports in the
+ PR database will both make it faster for us to commit them, and
+ prove that you know what you are doing.</para>
+ </sect1>
+
+ <sect1 xml:id="porting-wrkdir">
+ <title><varname>WRKDIR</varname></title>
+
+ <para>Do not write anything to files outside
+ <varname>WRKDIR</varname>. <varname>WRKDIR</varname> is the
+ only place that is guaranteed to be writable during the port
+ build (see <link
+ xlink:href="&url.books.handbook;/ports-using.html#PORTS-CD">
+ installing ports from a CDROM</link> for an example of
+ building ports from a read-only tree). If you need to modify
+ one of the <filename>pkg-*</filename> files, do so by
+ <link linkend="porting-pkgfiles">redefining a variable</link>,
+ not by writing over it.</para>
+ </sect1>
+
+ <sect1 xml:id="porting-wrkdirprefix">
+ <title><varname>WRKDIRPREFIX</varname></title>
+
+ <para>Make sure your port honors <varname>WRKDIRPREFIX</varname>.
+ Most ports do not have to worry about this. In particular, if
+ you are referring to a <varname>WRKDIR</varname> of another
+ port, note that the correct location is
+ <filename>WRKDIRPREFIXPORTSDIR/subdir/name/work</filename> not
+ <filename>PORTSDIR/subdir/name/work</filename> or
+ <filename>.CURDIR/../../subdir/name/work</filename> or some
+ such.</para>
+
+ <para>Also, if you are defining <varname>WRKDIR</varname>
+ yourself, make sure you prepend
+ <literal>${WRKDIRPREFIX}${.CURDIR}</literal> in
+ the front.</para>
+ </sect1>
+
+ <sect1 xml:id="porting-versions">
+ <title>Differentiating Operating Systems and OS Versions</title>
+
+ <para>You may come across code that needs modifications or
+ conditional compilation based upon what version of &os; Unix it
+ is running under. The preferred way to tell &os; versions apart
+ are the <literal>__FreeBSD_version</literal> and
+ <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>.
+ If this file is not included add the code,</para>
+
+ <programlisting>#include <sys/param.h></programlisting>
+
+ <para>to the proper place in the <filename>.c</filename>
+ file.</para>
+
+ <para><literal>__FreeBSD__</literal> is defined in all versions
+ of &os; as their major version number. For example, in &os;
+ 9.x, <literal>__FreeBSD__</literal> is defined to be
+ <literal>9</literal>.</para>
- <title>Dos and Don'ts</title>
-
- <sect1 xml:id="dads-intro">
- <title>Introduction</title>
-
- <para>Here is a list of common dos and don'ts that are
- encountered during the porting process. Check the port
- against this list, but also check ports in the <link
- xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">PR
- database</link> that others have submitted. Submit any
- comments on ports you check as described in <link
- xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug
- Reports and General Commentary</link>. Checking ports in
- the PR database will both make it faster for us to commit
- them, and prove that you know what you are doing.</para>
- </sect1>
-
- <sect1 xml:id="porting-wrkdir">
- <title><varname>WRKDIR</varname></title>
-
- <para>Do not write anything to files outside
- <varname>WRKDIR</varname>. <varname>WRKDIR</varname> is the
- only place that is guaranteed to be writable during the port
- build (see <link
- xlink:href="&url.books.handbook;/ports-using.html#PORTS-CD">
- installing ports from a CDROM</link> for an example of
- building ports from a read-only tree). If you need to modify
- one of the <filename>pkg-*</filename> files, do so by
- <link linkend="porting-pkgfiles">redefining a variable</link>,
- not by writing over it.</para>
- </sect1>
-
- <sect1 xml:id="porting-wrkdirprefix">
- <title><varname>WRKDIRPREFIX</varname></title>
-
- <para>Make sure your port honors
- <varname>WRKDIRPREFIX</varname>. Most ports do not have to
- worry about this. In particular, if you are referring to a
- <varname>WRKDIR</varname> of another port, note that the
- correct location is
- <filename>WRKDIRPREFIXPORTSDIR/subdir/name/work</filename>
- not
- <filename>PORTSDIR/subdir/name/work</filename>
- or
- <filename>.CURDIR/../../subdir/name/work</filename>
- or some such.</para>
-
- <para>Also, if you are defining <varname>WRKDIR</varname>
- yourself, make sure you prepend
- <literal>${WRKDIRPREFIX}${.CURDIR}</literal> in
- the front.</para>
- </sect1>
-
- <sect1 xml:id="porting-versions">
- <title>Differentiating Operating Systems and OS Versions</title>
-
- <para>You may come across code that needs modifications or
- conditional compilation based upon what version of &os; Unix
- it is running under. The preferred way to tell &os; versions
- apart are the <literal>__FreeBSD_version</literal> and
- <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>.
- If this file is not included add the code,</para>
-
- <programlisting>#include <sys/param.h></programlisting>
-
- <para>to the proper place in the <filename>.c</filename>
- file.</para>
-
- <para><literal>__FreeBSD__</literal> is defined in all
- versions of &os; as their major version number. For
- example, in &os; 9.x, <literal>__FreeBSD__</literal> is
- defined to be <literal>9</literal>.</para>
-
- <programlisting>#if __FreeBSD__ >= 9
+ <programlisting>#if __FreeBSD__ >= 9
# if __FreeBSD_version >= 901000
/* 9.1+ release specific code here */
# endif
#endif</programlisting>
- </sect1>
+ </sect1>
- <sect1 xml:id="dads-after-port-mk">
- <title>Writing Something After
- <filename>bsd.port.mk</filename></title>
-
- <para>Do not write anything after the <literal>.include
- <bsd.port.mk></literal> line. It usually can be
- avoided by including <filename>bsd.port.pre.mk</filename>
- somewhere in the middle of your <filename>Makefile</filename>
- and <filename>bsd.port.post.mk</filename> at the end.</para>
-
- <note>
- <para>Include either the
- <filename>bsd.port.pre.mk</filename>/<filename>bsd.port.post.mk</filename>
- pair or <filename>bsd.port.mk</filename> only; do not mix
- these two usages.</para>
- </note>
-
- <para><filename>bsd.port.pre.mk</filename> only defines a few
- variables, which can be used in tests in the
- <filename>Makefile</filename>,
- <filename>bsd.port.post.mk</filename> defines the rest.</para>
-
- <para>Here are some important variables defined in
- <filename>bsd.port.pre.mk</filename> (this is not the complete
- list, please read <filename>bsd.port.mk</filename> for the
- complete list).</para>
-
- <informaltable frame="none" pgwide="0">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Variable</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><varname>ARCH</varname></entry>
- <entry>The architecture as returned by <command>uname
- -m</command> (e.g., <literal>i386</literal>)</entry>
- </row>
-
- <row>
- <entry><varname>OPSYS</varname></entry>
- <entry>The operating system type, as returned by
- <command>uname -s</command> (e.g.,
- <literal>FreeBSD</literal>)</entry>
- </row>
-
- <row>
- <entry><varname>OSREL</varname></entry>
- <entry>The release version of the operating system
- (e.g., <literal>2.1.5</literal> or
- <literal>2.2.7</literal>)</entry>
- </row>
-
- <row>
- <entry><varname>OSVERSION</varname></entry>
- <entry>The numeric version of the operating system; the
- same as <link
- linkend="freebsd-versions"><literal>__FreeBSD_version</literal></link>.</entry>
- </row>
-
- <row>
- <entry><varname>LOCALBASE</varname></entry>
- <entry>The base of the <quote>local</quote> tree (e.g.,
- <literal>/usr/local</literal>)</entry>
- </row>
-
- <row>
- <entry><varname>PREFIX</varname></entry>
-
- <entry>Where the port installs itself (see
- <link linkend="porting-prefix">more on
- <varname>PREFIX</varname></link>).</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <note>
- <para>If you have to define the variable
- <varname>MASTERDIR</varname>, do so before including
- <filename>bsd.port.pre.mk</filename>.</para>
- </note>
+ <sect1 xml:id="dads-after-port-mk">
+ <title>Writing Something After
+ <filename>bsd.port.mk</filename></title>
+
+ <para>Do not write anything after the
+ <literal>.include <bsd.port.mk></literal> line. It
+ usually can be avoided by including
+ <filename>bsd.port.pre.mk</filename> somewhere in the middle of
+ your <filename>Makefile</filename> and
+ <filename>bsd.port.post.mk</filename> at the end.</para>
+
+ <note>
+ <para>Include either the
+ <filename>bsd.port.pre.mk</filename>/<filename>bsd.port.post.mk</filename>
+ pair or <filename>bsd.port.mk</filename> only; do not mix
+ these two usages.</para>
+ </note>
+
+ <para><filename>bsd.port.pre.mk</filename> only defines a few
+ variables, which can be used in tests in the
+ <filename>Makefile</filename>,
+ <filename>bsd.port.post.mk</filename> defines the rest.</para>
+
+ <para>Here are some important variables defined in
+ <filename>bsd.port.pre.mk</filename> (this is not the complete
+ list, please read <filename>bsd.port.mk</filename> for the
+ complete list).</para>
+
+ <informaltable frame="none" pgwide="0">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Variable</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><varname>ARCH</varname></entry>
+ <entry>The architecture as returned by <command>uname
+ -m</command> (e.g., <literal>i386</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><varname>OPSYS</varname></entry>
+ <entry>The operating system type, as returned by
+ <command>uname -s</command> (e.g.,
+ <literal>FreeBSD</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><varname>OSREL</varname></entry>
+ <entry>The release version of the operating system
+ (e.g., <literal>2.1.5</literal> or
+ <literal>2.2.7</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><varname>OSVERSION</varname></entry>
+ <entry>The numeric version of the operating system; the
+ same as <link
+ linkend="freebsd-versions"><literal>__FreeBSD_version</literal></link>.</entry>
+ </row>
+
+ <row>
+ <entry><varname>LOCALBASE</varname></entry>
+ <entry>The base of the <quote>local</quote> tree (e.g.,
+ <literal>/usr/local</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><varname>PREFIX</varname></entry>
+
+ <entry>Where the port installs itself (see
+ <link linkend="porting-prefix">more on
+ <varname>PREFIX</varname></link>).</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <note>
+ <para>If you have to define the variable
+ <varname>MASTERDIR</varname>, do so before including
+ <filename>bsd.port.pre.mk</filename>.</para>
+ </note>
- <para>Here are some examples of things you can write after
- <filename>bsd.port.pre.mk</filename>:</para>
+ <para>Here are some examples of things you can write after
+ <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
BROKEN= perl is in system
.endif</programlisting>
- <para>You did remember to use tab instead of spaces after
- <literal>BROKEN=</literal> and
- <!-- smiley -->:-).</para>
- </sect1>
-
- <sect1 xml:id="dads-sh-exec">
- <title>Use the <function>exec</function> Statement in Wrapper
- Scripts</title>
-
- <para>If the port installs a shell script whose purpose is to
- launch another program, and if launching that program is the
- last action performed by the script, make sure to launch the
- program using the <function>exec</function> statement, for
- instance:</para>
+ <para>You did remember to use tab instead of spaces after
+ <literal>BROKEN=</literal> and
+ <!-- smiley -->:-).</para>
+ </sect1>
+
+ <sect1 xml:id="dads-sh-exec">
+ <title>Use the <function>exec</function> Statement in Wrapper
+ Scripts</title>
+
+ <para>If the port installs a shell script whose purpose is to
+ launch another program, and if launching that program is the
+ last action performed by the script, make sure to launch the
+ program using the <function>exec</function> statement, for
+ instance:</para>
- <programlisting>#!/bin/sh
+ <programlisting>#!/bin/sh
exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting>
- <para>The <function>exec</function> statement replaces the shell
- process with the specified program. If
- <function>exec</function> is omitted, the shell process
- remains in memory while the program is executing, and
- needlessly consumes system resources.</para>
- </sect1>
-
- <sect1 xml:id="dads-rational">
- <title>Do Things Rationally</title>
-
- <para>The <filename>Makefile</filename> should do things simply
- and reasonably. If you can make it a couple of lines shorter
- or more readable, then do so. Examples include using a make
- <literal>.if</literal> construct instead of a shell
- <literal>if</literal> construct, not redefining
- <buildtarget>do-extract</buildtarget> if you can redefine
- <varname>EXTRACT*</varname> instead, and using
- <varname>GNU_CONFIGURE</varname> instead of
- <literal>CONFIGURE_ARGS
- += --prefix=${PREFIX}</literal>.</para>
-
- <para>If you find yourself having to write a lot of new code to
- try to do something, please go back and review
- <filename>bsd.port.mk</filename> to see if it contains an
- existing implementation of what you are trying to do. While
- hard to read, there are a great many seemingly-hard problems
- for which <filename>bsd.port.mk</filename> already provides a
- shorthand solution.</para>
- </sect1>
-
- <sect1 xml:id="dads-cc">
- <title>Respect Both <varname>CC</varname> and
- <varname>CXX</varname></title>
-
- <para>The port must respect both <varname>CC</varname> and
- <varname>CXX</varname> variables. What we mean by this is
- that the port must not set the values of these variables
- absolutely, overriding existing values; instead, it may
- append whatever values it needs to the existing values. This
- is so that build options that affect all ports can be set
- globally.</para>
-
- <para>If the port does not respect these variables,
- please add
- <literal>NO_PACKAGE=ignores either cc or cxx</literal> to the
- <filename>Makefile</filename>.</para>
-
- <para>An example of a <filename>Makefile</filename> respecting
- both <varname>CC</varname> and <varname>CXX</varname>
- variables follows. Note the <varname>?=</varname>:</para>
-
- <programlisting>CC?= gcc</programlisting>
-
- <programlisting>CXX?= g++</programlisting>
-
- <para>Here is an example which respects neither
- <varname>CC</varname> nor <varname>CXX</varname>
- variables:</para>
-
- <programlisting>CC= gcc</programlisting>
-
- <programlisting>CXX= g++</programlisting>
-
- <para>Both <varname>CC</varname> and <varname>CXX</varname>
- variables can be defined on &os; systems in
- <filename>/etc/make.conf</filename>. The first example
- defines a value if it was not previously set in
- <filename>/etc/make.conf</filename>, preserving any
- system-wide definitions. The second example clobbers
- anything previously defined.</para>
- </sect1>
-
- <sect1 xml:id="dads-cflags">
- <title>Respect <varname>CFLAGS</varname></title>
-
- <para>The port must respect the <varname>CFLAGS</varname>
- variable. What we mean by this is that the port must not
- set the value of this variable absolutely, overriding the
- existing value; instead, it may append whatever values it
- needs to the existing value. This is so that build options
- that affect all ports can be set globally.</para>
-
- <para>If it does not, please add
- <literal>NO_PACKAGE=ignores cflags</literal> to the
- <filename>Makefile</filename>.</para>
-
- <para>An example of a <filename>Makefile</filename> respecting
- the <varname>CFLAGS</varname> variable follows. Note the
- <varname>+=</varname>:</para>
-
- <programlisting>CFLAGS+= -Wall -Werror</programlisting>
-
- <para>Here is an example which does not respect the
- <varname>CFLAGS</varname> variable:</para>
-
- <programlisting>CFLAGS= -Wall -Werror</programlisting>
-
- <para>The <varname>CFLAGS</varname> variable is defined on
- &os; systems in <filename>/etc/make.conf</filename>. The
- first example appends additional flags to the
- <varname>CFLAGS</varname> variable, preserving any system-wide
- definitions. The second example clobbers anything previously
- defined.</para>
-
- <para>You should remove optimization flags from the third party
- <filename>Makefile</filename>s. System
- <varname>CFLAGS</varname> contains system-wide optimization
- flags. An example from an unmodified
- <filename>Makefile</filename>:</para>
-
- <programlisting>CFLAGS= -O3 -funroll-loops -DHAVE_SOUND</programlisting>
-
- <para>Using system optimization flags, the
- <filename>Makefile</filename> would look similar to the
- following example:</para>
-
- <programlisting>CFLAGS+= -DHAVE_SOUND</programlisting>
- </sect1>
-
- <sect1 xml:id="dads-pthread">
- <title>Threading Libraries</title>
-
- <para>The threading library must be linked to the binaries using
- a special flag <literal>-pthread</literal> on &os;. If
- a port insists on linking <literal>-lpthread</literal>
- directly, patch it to use <literal>-pthread</literal>.</para>
-
- <note>
- <para>If building the port errors out with
- <literal>unrecognized option '-pthread'</literal>, it may be
- desirable to use <command>cc</command> as linker by setting
- <varname>CONFIGURE_ENV</varname> to
- <literal>LD=${CC}</literal>. The
- <literal>-pthread</literal> option is not supported by
- <command>ld</command> directly.</para>
- </note>
- </sect1>
-
- <sect1 xml:id="dads-feedback">
- <title>Feedback</title>
-
- <para>Do send applicable changes/patches to the original
- author/maintainer for inclusion in next release of the code.
- This will only make your job that much easier for the next
- release.</para>
- </sect1>
-
- <sect1 xml:id="dads-readme">
- <title><filename>README.html</filename></title>
-
- <para><filename>README.html</filename> is not part of the port,
- but generated by <command>make readme</command>. Do not
- include this file in patches or commits.</para>
-
- <note>
- <para>If <command>make readme</command> fails, make sure that
- the default value of <varname>ECHO_MSG</varname> has not
- been modified by the port.</para>
- </note>
- </sect1>
-
- <sect1 xml:id="dads-noinstall">
- <title>Marking a Port Not Installable with
- <varname>BROKEN</varname>, <varname>FORBIDDEN</varname>, or
- <varname>IGNORE</varname></title>
-
- <para>In certain cases users should be prevented from installing
- 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 <command>make</command> variables will be the
- reason that is 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 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>
-
- <sect2 xml:id="dads-noinstall-variables">
- <title>Variables</title>
-
- <itemizedlist>
- <listitem>
- <para><varname>BROKEN</varname> is reserved for ports that
- currently do not compile, install, or deinstall
- correctly. It should be used for ports where the
- problem is believed to be temporary.</para>
-
- <para>If instructed, the build cluster will still attempt
- to try to build them to see if the underlying problem
- has been resolved. (However, in general, the cluster is
- run without this.)</para>
-
- <para>For instance, use <varname>BROKEN</varname> 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></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>
- <para><varname>FORBIDDEN</varname> is used for ports that
- contain a security vulnerability or induce grave concern
- regarding the security of a &os; system with a given
- port installed (e.g., a reputably insecure program or a
- program that provides easily exploitable services).
- Ports should be marked as <varname>FORBIDDEN</varname>
- 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 &os; hosts (we like being known
- for being secure), however sometimes there is a
- noticeable time gap between disclosure of a
- vulnerability and an updated release of the vulnerable
- software. Do not mark a port
- <varname>FORBIDDEN</varname> for any reason other than
- security.</para>
- </listitem>
-
- <listitem>
- <para><varname>IGNORE</varname> is reserved for ports that
- should not be built for some other reason. It should be
- used for ports where the problem is believed to be
- structural. The build cluster will not, under any
- circumstances, build ports marked as
- <varname>IGNORE</varname>. For instance, use
- <varname>IGNORE</varname> 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>has a distfile which may not be automatically
- fetched due to licensing restrictions</para>
- </listitem>
-
- <listitem>
- <para>does not work with some other currently
- installed port (for instance, the port depends on
- <package role="port">www/apache20</package> but
- <package role="port">www/apache22</package> is
- installed)</para>
- </listitem>
- </itemizedlist>
-
- <note>
- <para>If a port would conflict with a currently
- installed port (for example, if they install a file in
- the same place that performs a different function),
- <link linkend="conflicts">use
- <varname>CONFLICTS</varname> instead</link>.
- <varname>CONFLICTS</varname> will set
- <varname>IGNORE</varname> by itself.</para>
- </note>
- </listitem>
-
- <listitem>
- <para>If a port should be marked <varname>IGNORE</varname>
- only on certain architectures, there are two other
- convenience variables that will automatically set
- <varname>IGNORE</varname> for you:
- <varname>ONLY_FOR_ARCHS</varname> and
- <varname>NOT_FOR_ARCHS</varname>. Examples:</para>
-
- <programlisting>ONLY_FOR_ARCHS= i386 amd64</programlisting>
-
- <programlisting>NOT_FOR_ARCHS= ia64 sparc64</programlisting>
-
- <para>A custom <varname>IGNORE</varname> message can be
- set using <varname>ONLY_FOR_ARCHS_REASON</varname> and
- <varname>NOT_FOR_ARCHS_REASON</varname>. Per
- architecture entries are possible with
- <varname>ONLY_FOR_ARCHS_REASON_<replaceable>ARCH</replaceable></varname>
- and
- <varname>NOT_FOR_ARCHS_REASON_<replaceable>ARCH</replaceable></varname>.</para>
- </listitem>
-
- <listitem>
- <para>If a port fetches i386 binaries and installs them,
- <varname>IA32_BINARY_PORT</varname> should be set. If
- this variable is set, it will be checked whether the
- <filename>/usr/lib32</filename> directory is available
- for IA32 versions of libraries and whether the kernel
- has IA32 compatibility compiled in. If one of these two
- dependencies is not satisfied, <varname>IGNORE</varname>
- will be set automatically.</para>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <sect2 xml:id="dads-noinstall-notes">
- <title>Implementation Notes</title>
-
- <para>The strings should not be quoted.
- 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= fails to link with base -lcrypto</programlisting>
-
- <programlisting>IGNORE= unsupported on recent versions</programlisting>
-
- <para>resulting in the following output from
- <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 unsupported on recent versions.</programlisting>
- </sect2>
- </sect1>
-
- <sect1 xml:id="dads-deprecated">
- <title>Marking a Port for Removal with
- <varname>DEPRECATED</varname> or
- <varname>EXPIRATION_DATE</varname></title>
-
- <para>Do remember that <varname>BROKEN</varname> and
- <varname>FORBIDDEN</varname> are to be used as a temporary
- resort if a port is not working. 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 <varname>DEPRECATED</varname>
- and <varname>EXPIRATION_DATE</varname>. 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 <varname>DEPRECATED</varname>
- without an <varname>EXPIRATION_DATE</varname> (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 xml:id="dads-dot-error">
- <title>Avoid Use of the <literal>.error</literal>
- Construct</title>
-
- <para>The correct way for a <filename>Makefile</filename> to
- signal that the port can not be installed due to some external
- factor (for instance, the user has specified an illegal
- combination of build options) is to set a non-blank value to
- <varname>IGNORE</varname>. This value will be formatted and
- shown to the user by <command>make install</command>.</para>
-
- <para>It is a common mistake to use <literal>.error</literal>
- for this purpose. The problem with this is that many
- automated tools that work with the ports tree will fail in
- this situation. The most common occurrence of this is seen
- when trying to build <filename>/usr/ports/INDEX</filename>
- (see <xref linkend="make-describe"/>). However, even more
- trivial commands such as <command>make maintainer</command>
- also fail in this scenario. This is not acceptable.</para>
-
- <example xml:id="dot-error-breaks-index">
- <title>How to Avoid Using <literal>.error</literal></title>
-
- <para>The first of the
- next two <filename>Makefile</filename> snippets will cause
- <command>make index</command> to fail, while the second one
- will not:</para>
-
- <programlisting>.error "option is not supported"</programlisting>
-
- <programlisting>IGNORE=option is not supported</programlisting>
- </example>
- </sect1>
-
- <sect1 xml:id="dads-sysctl">
- <title>Usage of <filename>sysctl</filename></title>
-
- <para>The usage of <filename>sysctl</filename> is discouraged
- except in targets. This is because the evaluation of any
- <literal>makevar</literal>s, such as used during
- <command>make index</command>, then has to run the command,
- further slowing down that process.</para>
-
- <para>Usage of &man.sysctl.8; should always be done with the
- <varname>SYSCTL</varname> variable, as it contains the fully
- qualified path and can be overridden, if one has such a
- special need.</para>
- </sect1>
-
- <sect1 xml:id="dads-rerolling-distfiles">
- <title>Rerolling Distfiles</title>
-
- <para>Sometimes the authors of software change the content of
- released distfiles without changing the file's name. You have
- to verify that the changes are official and have been
- performed by the author. It has happened in the past that the
- distfile was silently altered on the download servers with the
- intent to cause harm or compromise end user security.</para>
-
- <para>Put the old distfile aside, download the new one, unpack
- them and compare the content with &man.diff.1;. If you see
- nothing suspicious, you can update
- <filename>distinfo</filename>. Be sure to summarize the
- differences in your PR or commit log, so that other people
- know that you have taken care to ensure that nothing bad has
- happened.</para>
-
- <para>You might also want to contact the authors of the software
- and confirm the changes with them.</para>
- </sect1>
-
- <sect1 xml:id="dads-avoiding-linuxisms">
- <title>Avoiding Linuxisms</title>
-
- <para>Do not use <filename>/proc</filename> if there are any
- other ways of getting the information, e.g.,
- <function>setprogname(argv[0])</function> in
- <function>main()</function> and then &man.getprogname.3; if
- you want to <quote>know your name</quote>.</para>
-
- <para>Do not rely on behaviour that is undocumented by
- <acronym>POSIX</acronym>.</para>
-
- <para>Do not record timestamps in the critical path of the
- application if it also works without. Getting timestamps may
- be slow, depending on the accuracy of timestamps in the
- <acronym>OS</acronym>. If timestamps are really needed,
- determine how precise they have to be and use an
- <acronym>API</acronym> which is documented to just deliver the
- needed precision.</para>
-
- <para>A number of simple syscalls (for example
- &man.gettimeofday.2;, &man.getpid.2;) are much faster on
- &linux; than on any other operating system due to caching and
- the vsyscall performance optimizations. Do not rely on them
- being cheap in performance-critical applications. In general,
- try hard to avoid syscalls if possible.</para>
-
- <para>Do not rely on &linux;-specific socket behaviour. In
- particular, default socket buffer sizes are different (call
- &man.setsockopt.2; with <literal>SO_SNDBUF</literal> and
- <literal>SO_RCVBUF</literal>, and while &linux;'s &man.send.2;
- blocks when the socket buffer is full, &os;'s will fail and
- set <literal>ENOBUFS</literal> in errno.</para>
-
- <para>If relying on non-standard behaviour is required,
- encapsulate it properly into a generic <acronym>API</acronym>,
- do a check for the behaviour in the configure stage, and stop
- if it is missing.</para>
-
- <para>Check the
- <link xlink:href="http://www.freebsd.org/cgi/man.cgi">man
- pages</link> to see if the function used is a
- <acronym>POSIX</acronym> interface (in the
- <quote>STANDARDS</quote> section of the man page).</para>
-
- <para>Do not assume that <filename>/bin/sh</filename> is
- <application>bash</application>. Ensure that a command line
- passed to &man.system.3; will work with a
- <acronym>POSIX</acronym> compliant shell.</para>
-
- <para>A list of common <application>bash</application>isms is
- available <link
- xlink:href="https://wiki.ubuntu.com/DashAsBinSh">here</link>.</para>
-
- <para>Check that headers are included in the
- <acronym>POSIX</acronym> or man page recommended way, e.g.,
- <filename>sys/types.h</filename> is often forgotten, which is
- not as much of a problem for &linux; as it is for &os;.</para>
-
- <para>Compile threaded applications with
- <quote>-pthread</quote>, not <quote>-lpthread</quote> or
- variations thereof.</para>
- </sect1>
-
- <sect1 xml:id="dads-misc">
- <title>Miscellanea</title>
-
- <para>The files <filename>pkg-descr</filename> and
- <filename>pkg-plist</filename> should each be double-checked.
- If you are reviewing a port and feel they can be worded
- better, do so.</para>
-
- <para>Do not copy more copies of the GNU General Public License
- into our system, please.</para>
-
- <para>Please be careful to note any legal issues! Do not let us
- illegally distribute software!</para>
- </sect1>
- </chapter>
-
+ <para>The <function>exec</function> statement replaces the shell
+ process with the specified program. If
+ <function>exec</function> is omitted, the shell process remains
+ in memory while the program is executing, and needlessly
+ consumes system resources.</para>
+ </sect1>
+
+ <sect1 xml:id="dads-rational">
+ <title>Do Things Rationally</title>
+
+ <para>The <filename>Makefile</filename> should do things simply
+ and reasonably. If you can make it a couple of lines shorter or
+ more readable, then do so. Examples include using a make
+ <literal>.if</literal> construct instead of a shell
+ <literal>if</literal> construct, not redefining
+ <buildtarget>do-extract</buildtarget> if you can redefine
+ <varname>EXTRACT*</varname> instead, and using
+ <varname>GNU_CONFIGURE</varname> instead of
+ <literal>CONFIGURE_ARGS
+ += --prefix=${PREFIX}</literal>.</para>
+
+ <para>If you find yourself having to write a lot of new code to
+ try to do something, please go back and review
+ <filename>bsd.port.mk</filename> to see if it contains an
+ existing implementation of what you are trying to do. While
+ hard to read, there are a great many seemingly-hard problems for
+ which <filename>bsd.port.mk</filename> already provides a
+ shorthand solution.</para>
+ </sect1>
+
+ <sect1 xml:id="dads-cc">
+ <title>Respect Both <varname>CC</varname> and
+ <varname>CXX</varname></title>
+
+ <para>The port must respect both <varname>CC</varname> and
+ <varname>CXX</varname> variables. What we mean by this is that
+ the port must not set the values of these variables absolutely,
+ overriding existing values; instead, it may append whatever
+ values it needs to the existing values. This is so that build
+ options that affect all ports can be set globally.</para>
+
+ <para>If the port does not respect these variables,
+ please add
+ <literal>NO_PACKAGE=ignores either cc or cxx</literal> to the
+ <filename>Makefile</filename>.</para>
+
+ <para>An example of a <filename>Makefile</filename> respecting
+ both <varname>CC</varname> and <varname>CXX</varname>
+ variables follows. Note the <varname>?=</varname>:</para>
+
+ <programlisting>CC?= gcc</programlisting>
+
+ <programlisting>CXX?= g++</programlisting>
+
+ <para>Here is an example which respects neither
+ <varname>CC</varname> nor <varname>CXX</varname>
+ variables:</para>
+
+ <programlisting>CC= gcc</programlisting>
+
+ <programlisting>CXX= g++</programlisting>
+
+ <para>Both <varname>CC</varname> and <varname>CXX</varname>
+ variables can be defined on &os; systems in
+ <filename>/etc/make.conf</filename>. The first example defines
+ a value if it was not previously set in
+ <filename>/etc/make.conf</filename>, preserving any system-wide
+ definitions. The second example clobbers anything previously
+ defined.</para>
+ </sect1>
+
+ <sect1 xml:id="dads-cflags">
+ <title>Respect <varname>CFLAGS</varname></title>
+
+ <para>The port must respect the <varname>CFLAGS</varname>
+ variable. What we mean by this is that the port must not set
+ the value of this variable absolutely, overriding the existing
+ value; instead, it may append whatever values it needs to the
+ existing value. This is so that build options that affect all
+ ports can be set globally.</para>
+
+ <para>If it does not, please add
+ <literal>NO_PACKAGE=ignores cflags</literal> to the
+ <filename>Makefile</filename>.</para>
+
+ <para>An example of a <filename>Makefile</filename> respecting
+ the <varname>CFLAGS</varname> variable follows. Note the
+ <varname>+=</varname>:</para>
+
+ <programlisting>CFLAGS+= -Wall -Werror</programlisting>
+
+ <para>Here is an example which does not respect the
+ <varname>CFLAGS</varname> variable:</para>
+
+ <programlisting>CFLAGS= -Wall -Werror</programlisting>
+
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-all
mailing list