Date: Sun, 9 Feb 2014 23:16:49 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43852 - head/en_US.ISO8859-1/books/porters-handbook/porting-dads Message-ID: <201402092316.s19NGnNx084645@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201402092316.s19NGnNx084645>