porters-handbook/porting-dads/chapter.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->

<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="https://bugs.FreeBSD.org/search/">PR
        database</link> that others have submitted.  Submit any
      comments on ports 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).  The
      <filename>pkg-<replaceable>*</replaceable></filename> files can
      be modified by <link linkend="pkg-names">redefining a
        variable</link> rather than overwriting the file.</para>
  </sect1>

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

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

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

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

    <para>Some code 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 &lt;sys/param.h&gt;</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__ &gt;= 9
#  if __FreeBSD_version &gt;= 901000
         /* 9.1+ release specific code here */
#  endif
#endif</programlisting>

      <para>A complete list of <literal>__FreeBSD_version</literal>
        values is available in <xref linkend="versions"/>.</para>
  </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 &lt;bsd.port.mk&gt;</literal> line.  It
      usually can be avoided by including
      <filename>bsd.port.pre.mk</filename> somewhere in the middle of
      the <filename>Makefile</filename> and
      <filename>bsd.port.post.mk</filename> at the end.</para>

    <important>
      <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>
    </important>

    <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> (for example,
              <literal>i386</literal>)</entry>
          </row>

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

          <row>
            <entry><varname>OSREL</varname></entry>
            <entry>The release version of the operating system
              (for example, <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="versions"><literal>__FreeBSD_version</literal></link>.</entry>
          </row>

          <row>
            <entry><varname>LOCALBASE</varname></entry>
            <entry>The base of the <quote>local</quote> tree (for
              example, <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>When <varname>MASTERDIR</varname> is needed, always define
        it before including
        <filename>bsd.port.pre.mk</filename>.</para>
    </note>

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

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

    <para>Always use tab instead of spaces after
      <literal>BROKEN=</literal>.</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
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 in a
      simple and reasonable manner.  Making it a couple of lines
      shorter or more readable is always better.  Examples include
      using a make <literal>.if</literal> construct instead of a shell
      <literal>if</literal> construct, not redefining
      <buildtarget>do-extract</buildtarget> if redefining
      <varname>EXTRACT*</varname> is enough, and using
      <varname>GNU_CONFIGURE</varname> instead of
      <literal>CONFIGURE_ARGS
        += --prefix=&dollar;{PREFIX}</literal>.</para>

    <para>If a lot of new code is needed to do something, there may
      already be an implementation of it in
      <filename>bsd.port.mk</filename>.  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>.  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>Here is an example of a <filename>Makefile</filename>
      respecting both <varname>CC</varname> and
      <varname>CXX</varname>.  Note the <literal>?=</literal>:</para>

    <programlisting>CC?= gcc</programlisting>

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

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

    <programlisting>CC= gcc</programlisting>

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

    <para>Both <varname>CC</varname> and <varname>CXX</varname>
      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 <varname>CFLAGS</varname>.
      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>Here is an example of a <filename>Makefile</filename>
      respecting <varname>CFLAGS</varname>.  Note the
      <literal>+=</literal>:</para>

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

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

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

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

    <para>Remove optimization flags from the third party
      <filename>Makefile</filename>s.  The 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 this
      example:</para>

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

  <sect1 xml:id="dads-verbose-logs">
    <title>Verbose Build Logs</title>

    <para>Make the port build system display all commands executed
      during the build stage.  Complete build logs are crucial to
      debugging port problems.</para>

    <para>Non-informative build log example (bad):</para>

    <programlisting>  CC     source1.o
  CC     source2.o
  CCLD   someprogram</programlisting>

    <para>Verbose build log example (good):</para>

    <programlisting>cc -O2 -pipe -I/usr/local/include -c -o source1.o source1.c
cc -O2 -pipe -I/usr/local/include -c -o source2.o source2.c
cc -o someprogram source1.o source2.o -L/usr/local/lib -lsomelib</programlisting>

    <para>Some build systems such as <application>CMake</application>,
      <application>ninja</application>, and <application>GNU
      configure</application> are set up for verbose logging by
      the ports framework.  In other cases, ports might need
      individial tweaks.</para>
  </sect1>

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

    <para>Do send applicable changes and patches to the upstream
      maintainer for inclusion in the next release of the code.
      This makes updating to the next release that much easier.</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-arch-neutral">
    <title>Marking a Port as Architecture Neutral</title>

    <para>Ports that do not have any architecture-dependent files
      or requirements are identified by setting
      <literal>NO_ARCH=yes</literal>.</para>
  </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 must be prevented from installing
      a port.  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.  The value of
      these make variables will be the
      reason that is shown to users for why the port refuses to
      install itself.  Please use the correct make
      variable.  Each variable conveys radically different
      meanings, both to users and to automated systems that depend on
      <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, deinstall, or run
            correctly.  Use it 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>${PREFIX}</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>

            <listitem>
              <para>has runtime issues on systems where it is
                supposed to run fine.</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 (for example, a reputably insecure program or a
            program that provides easily exploitable services).  Mark
            ports as <varname>FORBIDDEN</varname> as soon as a
            particular piece of software has a vulnerability and there
            is no released upgrade.  Ideally upgrade ports 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
            must not be built for some other reason.  Use it
            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>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>To mark a port as <varname>IGNORE</varname>d
            only on certain architectures, there are two other
            convenience variables that will automatically set
            <varname>IGNORE</varname>:
            <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,
            set <varname>IA32_BINARY_PORT</varname>.  If this variable
            is set, <filename>/usr/lib32</filename> must be present
            for IA32 versions of libraries and the kernel must support
            IA32 compatibility.  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>Do not quote the values of <varname>BROKEN</varname>,
        <varname>IGNORE</varname>, and related variables.  Due to the
        way the information is shown to the user, the wording of
        messages for each variable differ:</para>

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

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

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

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

      <programlisting>===&gt;  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
      will 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 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 cannot 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>Only use &man.sysctl.8; through
      <varname>SYSCTL</varname>, 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.
      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 there is
      nothing suspicious, update
      <filename>distinfo</filename>.  Be sure to summarize the
      differences in the PR or commit log, so that other people know
      that nothing bad has
      happened.</para>

    <para>Contact the authors of the software
      and confirm the changes with them.</para>
  </sect1>

  <sect1 xml:id="dads-use-posix-standards">
    <title>Use <acronym>POSIX</acronym> Standards</title>

    <para>&os; ports generally expect <acronym>POSIX</acronym>
      compliance.  Some software and build systems make assumptions
      based on a particular operating system or environment that can
      cause problems when used in a port.</para>

    <para>Do not use <filename>/proc</filename> if there are any
      other ways of getting the information.  For example,
      <function>setprogname(argv[0])</function> in
      <function>main()</function> and then &man.getprogname.3;
      to know the executable name.</para>

    <para>Do not rely on behavior 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 behavior.  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 behavior is required,
      encapsulate it properly into a generic <acronym>API</acronym>,
      do a check for the behavior 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.  For
      example, <filename>sys/types.h</filename> is often forgotten,
      which is not as much of a problem for &linux; as it is for
      &os;.</para>
  </sect1>

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

    <para>Always double-check <filename>pkg-descr</filename> and
      <filename>pkg-plist</filename>.
      If reviewing a port and a better wording can be achieved,
      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>