path: root/doc/guide/files/fixes.xml

<!-- $NetBSD: fixes.xml,v 1.121 2013/05/26 18:21:46 wiz Exp $ -->

<chapter id="fixes"> <?dbhtml filename="fixes.html"?>
<title>Making your package work</title>

<sect1 id="general-operation">
  <title>General operation</title>

  <sect2 id="portability-of-packages">
    <title>Portability of packages</title>

    <para>One appealing feature of pkgsrc is that it runs on many
    different platforms. As a result, it is important to ensure,
    where possible, that packages in pkgsrc are portable. This
    chapter mentions some particular details you should pay
    attention to while working on pkgsrc.</para>
  </sect2>

  <sect2 id="pulling-vars-from-etc-mk.conf">
    <title>How to pull in user-settable variables from &mk.conf;</title>

    <para>The pkgsrc user can configure pkgsrc by overriding several
    variables in the file pointed to by <varname>MAKECONF</varname>,
    which is &mk.conf; by default. When you
    want to use those variables in the preprocessor directives of
    &man.make.1; (for example <literal>.if</literal> or
    <literal>.for</literal>), you need to include the file
    <filename>../../mk/bsd.prefs.mk</filename> before, which in turn
    loads the user preferences.</para>

    <para>But note that some variables may not be completely defined
    after <filename>../../mk/bsd.prefs.mk</filename> has been
    included, as they may contain references to variables that are
    not yet defined. In shell commands this is no problem, since
    variables are actually macros, which are only expanded when they
    are used. But in the preprocessor directives mentioned above and
    in dependency lines (of the form <literal>target:
    dependencies</literal>) the variables are expanded at load
    time.</para>

    <note><para>Currently there is no exhaustive list of all
    variables that tells you whether they can be used at load time
    or only at run time, but it is in preparation.</para></note>
  </sect2>

  <sect2 id="user-interaction">
    <title>User interaction</title>

    <para>Occasionally, packages require interaction from the user,
    and this can be in a number of ways:</para>

    <itemizedlist>

      <listitem>
	<para>When fetching the distfiles, some packages require user
	interaction such as entering username/password or accepting a
	license on a web page.</para>
      </listitem>

      <listitem>
	<para>When extracting the distfiles, some packages may ask for
	passwords.</para>
      </listitem>

      <listitem>
	<para>help to configure the package before it is built</para>
      </listitem>

      <listitem>
	<para>help during the build process</para>
      </listitem>

      <listitem>
	<para>help during the installation of a package</para>
      </listitem>
    </itemizedlist>

    <para>The <varname>INTERACTIVE_STAGE</varname> definition is
    provided to notify the pkgsrc mechanism of an interactive stage
    which will be needed, and this should be set in the package's
    <filename>Makefile</filename>, e.g.:</para>

    <programlisting>
INTERACTIVE_STAGE=      build
    </programlisting>

    <para>Multiple interactive stages can be specified:</para>

    <programlisting>
INTERACTIVE_STAGE=      configure install
    </programlisting>

    <para>The user can then decide to skip this package by setting the
    <varname>BATCH</varname> variable.</para>
  </sect2>

  <sect2 id="handling-licenses">
    <title>Handling licenses</title>

    <para>Authors of software can choose the licence under which
    software can be copied.  This is due to copyright law, and reasons
    for license choices are outside the scope of pkgsrc.  The pkgsrc
    system recognizes that there are a number of licenses which some
    users may find objectionable or difficult or impossible to comply
    with.  The Free Software Foundation has declared some licenses
    "Free", and the Open Source Initiative has a definition of "Open
    Source".  The pkgsrc system, as a policy choice, does not label
    packages which have licenses that are Free or Open Source.
    However, packages without a license meeting either of those tests
    are labeled with a license tag denoting the license.  Note that a
    package with no license to copy trivially does not meet either the
    Free or Open Source test.</para>

    <para>For packages which are not Free or Open Source, pkgsrc will
    not build the package unless the user has indicated to pkgsrc that
    packages with that particular license may be built.  Note that
    this documentation avoids the term "accepted the license".  The
    pkgsrc system is merely providing a mechanism to avoid
    accidentally building a package with a non-free license;
    judgement and responsibility remain with the user.  (Installation
    of binary packages are not currently subject to this mechanism;
    this is a bug.)</para>

    <para>One might want to only install packages with a BSD license,
    or the GPL, and not the other.  The free licenses are added to the 
    default <varname>ACCEPTABLE_LICENSES</varname> variable.  The
    user can override the default by setting the
    <varname>ACCEPTABLE_LICENSES</varname> variable with "=" instead
    of "+=".  The licenses accepted by default are:
    <programlisting>
	apache-1.1 apache-2.0
	arphic-public
	artistic artistic-2.0
	boost-license
	cc-by-sa-v3.0
	cddl-1.0
	cpl-1.0
	epl-v1.0
	gnu-fdl-v1.1 gnu-fdl-v1.2 gnu-fdl-v1.3
	gnu-gpl-v1
	gnu-gpl-v2 gnu-lgpl-v2 gnu-lgpl-v2.1
	gnu-gpl-v3 gnu-lgpl-v3
	ibm-public-license-1.0
	ipafont
	isc
	lppl-1.3c
	lucent
	miros
	mit
	mpl-1.0 mpl-1.1 mpl-2.0
	mplusfont
	ofl-v1.0 ofl-v1.1
	original-bsd modified-bsd 2-clause-bsd
	php
	png-license
	postgresql-license
	public-domain
	python-software-foundation
	qpl-v1.0
	sgi-free-software-b-v2.0
	sleepycat-public
	unlicense
	x11
	zlib
	zpl
    </programlisting>
    </para>

    <para>The license tag mechanism is intended to address
    copyright-related issues surrounding building, installing and
    using a package, and not to address redistribution issues (see
    <varname>RESTRICTED</varname> and
    <varname>NO_SRC_ON_FTP</varname>, etc.).  
    Packages with redistribution restrictions should set these
    tags.</para>

    <para>Denoting that a package may be copied according to a
    particular license is done by placing the license in
    <filename>pkgsrc/licenses</filename> and setting the
    <varname>LICENSE</varname> variable to a string identifying the
    license, e.g. in <filename
    role="pkg">graphics/xv</filename>:</para>

    <programlisting>
LICENSE=        xv-license
    </programlisting>

    <para>When trying to build, the user will get a notice that the
    package is covered by a license which has not been placed in the
    <varname>ACCEPTABLE_LICENSES</varname> variable:</para>

    <programlisting>
&cprompt; <userinput>make</userinput>
===> xv-3.10anb9 has an unacceptable license: xv-license.
===>     To view the license, enter "/usr/bin/make show-license".
===>     To indicate acceptance, add this line to your /etc/mk.conf:
===>     ACCEPTABLE_LICENSES+=xv-license
*** Error code 1
    </programlisting>

    <para>The license can be viewed with <command>make
    show-license</command>, and if the user so chooses, the line
    printed above can be added to &mk.conf; to
    convey to pkgsrc that it should not in the future fail because of
    that license:</para>

    <programlisting>
ACCEPTABLE_LICENSES+=xv-license
    </programlisting>

    <para>When adding a package with a new license, the following steps
    are required:</para>
    <orderedlist>
    <listitem><para>Check if the file can avoid the -license filename tag as described above by referencing <ulink url="http://www.gnu.org/licenses/license-list.html">Various Licenses and Comments about Them</ulink> and <ulink url="http://opensource.org/licenses/alphabetical">Licenses by Name | Open Source Initiative</ulink>.  If this is the case, additionally add the license filename to:</para>
    <itemizedlist>
    <listitem><para>DEFAULT_ACCEPTABLE_LICENSES in <filename>pkgsrc/mk/license.mk</filename></para></listitem>
    <listitem><para>default_acceptable_licenses in <filename>pkgsrc/pkgtools/pkg_install/files/lib/license.c</filename></para></listitem>
    <listitem><para>the ACCEPTABLE_LICENSES list in <filename>pkgsrc/doc/guide/files/fixes.xml</filename></para></listitem>
    </itemizedlist>
    <para>with the proper syntax as demonstrated in those files, respectively.</para></listitem>
    <listitem><para>The license text should be added to <filename>pkgsrc/licenses</filename> for displaying.  A list of known licenses can be seen in this directory.</para></listitem>
    </orderedlist>
    <para>When the license changes (in a way other than formatting),
    please make sure that the new license has a different name (e.g.,
    append the version number if it exists, or the date).  Just
    because a user told pkgsrc to build programs under a previous
    version of a license does not mean that pkgsrc should build
    programs under the new licenses.  The higher-level point is that
    pkgsrc does not evaluate licenses for reasonableness; the only
    test is a mechanistic test of whether a particular text has been
    approved by either of two bodies.</para>

    <para>The use of <varname>LICENSE=shareware</varname>,
    <varname>LICENSE=no-commercial-use</varname>, and similar language
    is deprecated because it does not crisply refer to a particular
    license text.  Another problem with such usage is that it does not
    enable a user to tell pkgsrc to proceed for a single package
    without also telling pkgsrc to proceed for all packages with that
    tag.</para> </sect2>

  <sect2 id="restricted-packages">
    <title>Restricted packages</title>

    <para>Some licenses restrict how software may be re-distributed.
    Because a license tag is required unless the package is Free or
    Open Source, all packages with restrictions should have license
    tags.  By declaring the restrictions, package tools can
    automatically refrain from e.g. placing binary packages on FTP
    sites.</para>

    <para>There are four restrictions that may be encoded, which are
    the cross product of sources (distfiles) and binaries not being
    placed on FTP sites and CD-ROMs.  Because this is rarely the exact
    language in any license, and because non-Free licenses tend to be
    different from each other, pkgsrc adopts a definition of FTP and
    CD-ROM.  Pkgsrc uses "FTP" to mean that the source or binary file
    should not be made available over the Internet at no charge.
    Pkgsrc uses "CD-ROM" to mean that the source or binary may not be
    made available on some kind of media, together with other source
    and binary packages, and which is sold for a distribution charge.
    </para>

    <para>In order to encode these restrictions, the package system
    defines five make variables that can be set to note these
    restrictions:</para>

    <itemizedlist>
      <listitem>
	<para><varname>RESTRICTED</varname></para>

	<para>This variable should be set whenever a restriction
	exists (regardless of its kind).  Set this variable to a
	string containing the reason for the restriction.  It should
	be understood that those wanting to understand the restriction
	will have to read the license, and perhaps seek advice of
	counsel.</para>
      </listitem>

      <listitem>
	<para><varname>NO_BIN_ON_CDROM</varname></para>

	<para>Binaries may not be placed on CD-ROM containing other
	binary packages, for which a distribution charge may be made.
	In this case, set this variable to
	<varname>${RESTRICTED}</varname>.</para>
      </listitem>

      <listitem>
	<para><varname>NO_BIN_ON_FTP</varname></para>

	<para>Binaries may not made available on the Internet without
	charge.  In this case, set this variable to
	<varname>${RESTRICTED}</varname>.  If this variable is set,
	binary packages will not be included on ftp.NetBSD.org.</para>
      </listitem>

      <listitem>
	<para><varname>NO_SRC_ON_CDROM</varname></para>

	<para>Distfiles may not be placed on CD-ROM, together with
	other distfiles, for which a fee may be charged.  In this
	case, set this variable to <varname>${RESTRICTED}</varname>.
	</para>
      </listitem>

      <listitem>
	<para><varname>NO_SRC_ON_FTP</varname></para>

	<para>Distfiles may not made available via FTP at no charge.
	In this case, set this variable to
	<varname>${RESTRICTED}</varname>.  If this variable is set,
	the distfile(s) will not be mirrored on ftp.NetBSD.org.</para>
      </listitem>
    </itemizedlist>

    <para>Please note that packages will to be removed from pkgsrc
    when the distfiles are not distributable and cannot be obtained
    for a period of one full quarter branch. Packages with manual /
    interactive fetch must have a maintainer and it is his/her
    responsibility to ensure this.</para>
  </sect2>


  <sect2 id="dependencies">
    <title>Handling dependencies</title>

    <para>Your package may depend on some other package being present
    - and there are various ways of expressing this dependency.
    pkgsrc supports the <varname>BUILD_DEPENDS</varname> and
    <varname>DEPENDS</varname> definitions, the
    <varname>USE_TOOLS</varname> definition, as well as dependencies
    via <filename>buildlink3.mk</filename>, which is the preferred way
    to handle dependencies, and which uses the variables named above.
    See <xref linkend="buildlink"/> for more information.</para>

    <para>The basic difference between the two variables is as
    follows: The <varname>DEPENDS</varname> definition registers
    that pre-requisite in the binary package so it will be pulled in
    when the binary package is later installed, whilst the
    <varname>BUILD_DEPENDS</varname> definition does not, marking a
    dependency that is only needed for building the package.</para>

    <para>This means that if you only need a package present whilst
    you are building, it should be noted as a
    <varname>BUILD_DEPENDS</varname>.</para>

    <para>The format for a <varname>BUILD_DEPENDS</varname> and a
    <varname>DEPENDS</varname> definition is:</para>

    <programlisting>
&lt;pre-req-package-name&gt;:../../&lt;category&gt;/&lt;pre-req-package&gt;
    </programlisting>

    <para>Please note that the <quote>pre-req-package-name</quote>
    may include any of the wildcard version numbers recognized by
    &man.pkg.info.1;.</para>

    <orderedlist>
      <listitem>
	<para>If your package needs another package's binaries or
	libraries to build and run, and if that package has a
	<filename>buildlink3.mk</filename> file available, use it:</para>

	<programlisting>
.include "../../graphics/jpeg/buildlink3.mk"
	</programlisting>
      </listitem>

      <listitem>
	<para>If your package needs another package's binaries or
	libraries only for building, and if that package has a
	<filename>buildlink3.mk</filename> file available, use it:</para>

	<programlisting>
.include "../../graphics/jpeg/buildlink3.mk"
	</programlisting>
	<para>but set
	<varname>BUILDLINK_DEPMETHOD.<replaceable>jpeg</replaceable>?=build</varname>
	to make it a build dependency only. This case is rather
	rare.</para>
      </listitem>

      <listitem>
	<para>If your package needs binaries from another package to build,
	use the <varname>BUILD_DEPENDS</varname> definition:</para>

	<programlisting>
BUILD_DEPENDS+= scons-[0-9]*:../../devel/scons
	</programlisting>
      </listitem>

      <listitem>
	<para>If your package needs a library with which to link and
	there is no <filename>buildlink3.mk</filename> file
	available, create one. Using
	<varname>DEPENDS</varname> won't be sufficient because the
	include files and libraries will be hidden from the compiler.</para>
      </listitem>

      <listitem>
	<para>If your package needs some executable to be able to run
	correctly and if there's no
	<filename>buildlink3.mk</filename> file, this is specified
	using the <varname>DEPENDS</varname> variable. The
	<filename role="pkg">print/lyx</filename> package needs to
	be able to execute the latex binary from the teTeX package
	when it runs, and that is specified:</para>

	<programlisting>
DEPENDS+=        teTeX-[0-9]*:../../print/teTeX
	</programlisting>
      </listitem>
      <listitem>
	<para>You can use wildcards in package dependencies. Note that
	such wildcard dependencies are retained when creating binary
	packages. The dependency is checked when installing the binary
	package and any package which matches the pattern will be
	used. Wildcard dependencies should be used with care.</para>

	<para>The <quote>-[0-9]*</quote> should be used instead of
	<quote>-*</quote> to avoid potentially ambiguous matches
	such as <quote>tk-postgresql</quote> matching a
	<quote>tk-*</quote> <varname>DEPENDS</varname>.</para>

	<para>Wildcards can also be used to specify that a package
	will only build against a certain minimum version of a
	pre-requisite:</para>

	<programlisting>
DEPENDS+=       ImageMagick>=6.0:../../graphics/ImageMagick
	</programlisting>

	<para>This means that the package will build using version 6.0
	of ImageMagick or newer. Such a dependency may be warranted
	if, for example, the command line options of an executable
	have changed.</para>

	<para>If you need to depend on minimum versions of libraries,
	see the buildlink section of the pkgsrc guide.</para>

	<para>For security fixes, please update the package
	vulnerabilities file. See <xref
	linkend="security-handling"/> for more
	information.</para>
      </listitem>
    </orderedlist>

    <para>If your package needs files from another package to build,
    add the relevant distribution files to
    <varname>DISTFILES</varname>, so they will be extracted
    automatically. See the <filename
    role="pkg">print/ghostscript</filename> package for an example.
    (It relies on the jpeg sources being present in source form
    during the build.)</para>
  </sect2>


  <sect2 id="conflicts">
    <title>Handling conflicts with other packages</title>

    <para>Your package may conflict with other packages a user might
    already have installed on his system, e.g. if your package
    installs the same set of files as another package in the pkgsrc
    tree.</para>

    <para>In this case you can set <varname>CONFLICTS</varname> to a
    space-separated list of packages (including version string) your
    package conflicts with.</para>

    <para>For example, <filename role="pkg">x11/Xaw3d</filename>
    and <filename role="pkg">x11/Xaw-Xpm</filename>
    install the same shared library, thus you set in
    <filename>pkgsrc/x11/Xaw3d/Makefile</filename>:</para>

    <programlisting>
CONFLICTS=      Xaw-Xpm-[0-9]*
    </programlisting>

    <para>and in <filename>pkgsrc/x11/Xaw-Xpm/Makefile</filename>:</para>

    <programlisting>
CONFLICTS=      Xaw3d-[0-9]*
    </programlisting>

    <para>Packages will automatically conflict with other packages
    with the name prefix and a different version
    string. <quote>Xaw3d-1.5</quote> e.g. will automatically
    conflict with the older version <quote>Xaw3d-1.3</quote>.</para>
  </sect2>


  <sect2 id="not-building-packages">
    <title>Packages that cannot or should not be built</title>

    <para>There are several reasons why a package might be
    instructed to not build under certain circumstances.  If the
    package builds and runs on most platforms, the exceptions
    should be noted with <varname>NOT_FOR_PLATFORM</varname>.  If
    the package builds and runs on a small handful of platforms,
    set <varname>ONLY_FOR_PLATFORM</varname> instead.
    Both <varname>ONLY_FOR_PLATFORM</varname> and
    <varname>NOT_FOR_PLATFORM</varname> are OS triples
    (OS-version-platform) that can use glob-style
    wildcards.</para>
    <para>Some packages are tightly bound to a specific version of an
    operating system, e.g. LKMs or <filename
    role="pkg">sysutils/lsof</filename>.  Such binary packages are not
    backwards compatible with other versions of the OS, and should be
    uploaded to a version specific directory on the FTP server.  Mark
    these packages by setting <varname>OSVERSION_SPECIFIC</varname> to
    <quote>yes</quote>.  This variable is not currently used by any of
    the package system internals, but may be used in the
    future.</para>
    <para>If the package should be skipped (for example, because it
    provides functionality already provided by the system), set
    <varname>PKG_SKIP_REASON</varname> to a descriptive message.  If
    the package should fail because some preconditions are not met,
    set <varname>PKG_FAIL_REASON</varname> to a descriptive
    message.</para>
  </sect2>


  <sect2 id="undeletable-packages">
    <title>Packages which should not be deleted, once installed</title>

    <para>To ensure that a package may not be deleted, once it has been
    installed, the <varname>PKG_PRESERVE</varname> definition should
    be set in the package Makefile. This will be carried into any
    binary package that is made from this pkgsrc entry. A
    <quote>preserved</quote> package will
    not be deleted using &man.pkg.delete.1; unless the
    <quote>-f</quote> option is used.</para>
  </sect2>


  <sect2 id="security-handling">
    <title>Handling packages with security problems</title>

    <para>When a vulnerability is found, this should be noted in
    <filename>localsrc/security/advisories/pkg-vulnerabilities</filename>,
    and after committing that file, ask pkgsrc-security@NetBSD.org to
    update the file on ftp.NetBSD.org.</para>

    <para>After fixing the vulnerability by a patch, its
    <varname>PKGREVISION</varname> should be increased (this is of
    course not necessary if the problem is fixed by using a newer
    release of the software), and the pattern in the
    pkg-vulnerabilities file must be updated.</para>

    <para>Also, if the fix should be applied to the stable pkgsrc
    branch, be sure to submit a pullup request!</para>

    <para>Binary packages already on ftp.NetBSD.org will be handled
    semi-automatically by a weekly cron job.</para>
  </sect2>


  <sect2 id="bumping-pkgrevision">
    <title>How to handle incrementing versions when fixing an existing package</title>

    <para>When making fixes to an existing package it can be useful
    to change the version number in <varname>PKGNAME</varname>. To
    avoid conflicting with future versions by the original author, a
    <quote>nb1</quote>, <quote>nb2</quote>, ... suffix can be used
    on package versions by setting <varname>PKGREVISION=1</varname>
    (2, ...). The <quote>nb</quote> is treated like a
    <quote>.</quote> by the package tools. e.g.</para>

    <programlisting>
DISTNAME=       foo-17.42
PKGREVISION=    9
    </programlisting>

    <para>will result in a <varname>PKGNAME</varname> of
    <quote>foo-17.42nb9</quote>. If you want to use the original
    value of <varname>PKGNAME</varname> without the <quote>nbX</quote>
    suffix, e.g. for setting <varname>DIST_SUBDIR</varname>, use
    <varname>PKGNAME_NOREV</varname>.</para>

    <para>When a new release of the package is released, the
    <varname>PKGREVISION</varname> should be removed, e.g. on a new
    minor release of the above package, things should be like:</para>

    <programlisting>
DISTNAME=       foo-17.43
    </programlisting>

    <para><varname>PKGREVISION</varname> should be incremented for any
    non-trivial change in the resulting binary package.  Without a
    <varname>PKGREVISION</varname> bump, someone with the previous
    version installed has no way of knowing that their package is out
    of date.  Thus, changes without increasing
    <varname>PKGREVISION</varname> are essentially labeled "this is so
    trivial that no reasonable person would want to upgrade", and this
    is the rough test for when increasing
    <varname>PKGREVISION</varname> is appropriate.  Examples of
    changes that do not merit increasing
    <varname>PKGREVISION</varname> are:</para>

    <itemizedlist><listitem>
      <para>Changing <varname>HOMEPAGE</varname>,
      <varname>MAINTAINER</varname>, <varname>OWNER</varname>,
      or comments in Makefile.</para></listitem><listitem><para>
      Changing build variables if the resulting binary package is the same.</para></listitem><listitem><para>
      Changing <filename>DESCR</filename>.</para></listitem><listitem><para>
      Adding <varname>PKG_OPTIONS</varname> if the default options don't change.</para></listitem>
    </itemizedlist>

    <para>Examples of changes that do merit an increase to
    <varname>PKGREVISION</varname> include:</para>
    <itemizedlist><listitem><para>
      Security fixes</para></listitem><listitem><para>
      Changes or additions to a patch file</para></listitem><listitem><para>
      Changes to the <filename>PLIST</filename></para></listitem>
      <listitem><para>A dependency is changed or renamed.</para></listitem>
    </itemizedlist>

    <para>PKGREVISION must also be incremented when dependencies have ABI
    changes.</para>
  </sect2>

  <sect2 id="fixes.subst">
    <title>Substituting variable text in the package files (the SUBST framework)</title>

    <para>When you want to replace the same text in multiple files
    or when the replacement text varies, patches alone cannot help.
    This is where the SUBST framework comes in. It provides an
    easy-to-use interface for replacing text in files.
    Example:</para>

    <programlisting>
SUBST_CLASSES+=                 fix-paths
SUBST_STAGE.fix-paths=          pre-configure
SUBST_MESSAGE.fix-paths=        Fixing absolute paths.
SUBST_FILES.fix-paths=          src/*.c
SUBST_FILES.fix-paths+=         scripts/*.sh
SUBST_SED.fix-paths=            -e 's,"/usr/local,"${PREFIX},g'
SUBST_SED.fix-paths+=           -e 's,"/var/log,"${VARBASE}/log,g'
    </programlisting>

    <para><varname>SUBST_CLASSES</varname> is a list of identifiers
    that are used to identify the different SUBST blocks that are
    defined. The SUBST framework is heavily used by pkgsrc, so it is
    important to always use the <literal>+=</literal> operator with
    this variable. Otherwise some substitutions may be
    skipped.</para>

    <para>The remaining variables of each SUBST block are
    parameterized with the identifier from the first line
    (<literal>fix-paths</literal> in this case.) They can be seen as
    parameters to a function call.</para>

    <para><varname>SUBST_STAGE.*</varname> specifies the stage at
    which the replacement will take place. All combinations of
    <literal>pre-</literal>, <literal>do-</literal> and
    <literal>post-</literal> together with a phase name are
    possible, though only few are actually used. Most commonly used
    are <literal>post-patch</literal> and
    <literal>pre-configure</literal>. Of these two,
    <literal>pre-configure</literal> should be preferred because
    then it is possible to run <command>bmake patch</command> and
    have the state after applying the patches but before making any
    other changes. This is especially useful when you are debugging
    a package in order to create new patches for it. Similarly,
    <literal>post-build</literal> is preferred over
    <literal>pre-install</literal>, because the install phase should
    generally be kept as simple as possible. When you use
    <literal>post-build</literal>, you have the same files in the
    working directory that will be installed later, so you can check
    if the substitution has succeeded.</para>

    <para><varname>SUBST_MESSAGE.*</varname> is an optional text
    that is printed just before the substitution is done.</para>

    <para><varname>SUBST_FILES.*</varname> is the list of shell
    globbing patterns that specifies the files in which the
    substitution will take place. The patterns are interpreted
    relatively to the <varname>WRKSRC</varname> directory.</para>

    <para><varname>SUBST_SED.*</varname> is a list of arguments to
    &man.sed.1; that specify the actual substitution. Every sed
    command should be prefixed with <literal>-e</literal>, so that
    all SUBST blocks look uniform.</para>

    <para>There are some more variables, but they are so seldomly
    used that they are only documented in the
    <filename>mk/subst.mk</filename> file.</para>

  </sect2>
</sect1>
<sect1 id="fixes.fetch">
  <title>Fixing problems in the <emphasis>fetch</emphasis> phase</title>

  <sect2 id="no-plain-download">
    <title>Packages whose distfiles aren't available for plain downloading</title>

    <para>If you need to download from a dynamic URL you can set
    <varname>DYNAMIC_MASTER_SITES</varname> and a <command>make
    fetch</command> will call <filename>files/getsite.sh</filename>
    with the name of each file to download as an argument, expecting
    it to output the URL of the directory from which to download
    it. <filename role="pkg">graphics/ns-cult3d</filename> is an
    example of this usage.</para>

    <para>If the download can't be automated, because the user must
    submit personal information to apply for a password, or must pay
    for the source, or whatever, you can set
    <varname>FETCH_MESSAGE</varname> to a list of lines that are
    displayed to the user before aborting the build. Example:</para>

    <programlisting>
FETCH_MESSAGE=  "Please download the files"
FETCH_MESSAGE+= "    "${DISTFILES:Q}
FETCH_MESSAGE+= "manually from "${MASTER_SITES:Q}"."
    </programlisting>

  </sect2>


  <sect2 id="modified-distfiles-same-name">
    <title>How to handle modified distfiles with the 'old' name</title>

    <para>Sometimes authors of a software package make some
    modifications after the software was released, and they put up a
    new distfile without changing the package's version number. If a
    package is already in pkgsrc at that time, the checksum will
    no longer match. The contents of the new distfile should be
    compared against the old one before changing anything, to make
    sure the distfile was really updated on purpose, and that
    no trojan horse or so crept in.
    Please mention that the distfiles were compared and what was found
    in your commit message.</para>
    <para>Then, the correct way to work around this is to
    set <varname>DIST_SUBDIR</varname> to a unique directory name,
    usually based on <varname>PKGNAME_NOREV</varname>. All
    <varname>DISTFILES</varname> and
    <varname>PATCHFILES</varname> for this package will be put in that
    subdirectory of the local distfiles directory.
    (See <xref linkend="bumping-pkgrevision"/> for more details.)
    In case this
    happens more often, <varname>PKGNAME</varname> can be used (thus
    including the <filename>nbX</filename> suffix) or a date stamp
    can be appended, like <varname>${PKGNAME_NOREV}-YYYYMMDD</varname>.</para>
    <para><varname>DIST_SUBDIR</varname> is also used when a distfile's name does not contain a version and the distfile is apt to change. In cases where the likelihood of this is very small, <varname>DIST_SUBDIR</varname> might not be required. Additionally, <varname>DIST_SUBDIR</varname> must not be removed unless the distfile name changes, even if a package is being moved or renamed.</para>
    <para>Do not forget regenerating the <filename>distinfo</filename> file
    after that, since it contains the <varname>DIST_SUBDIR</varname>
    path in the filenames.
    Also, increase the PKGREVISION if the installed package is different.
    Furthermore, a mail to the package's authors seems appropriate
    telling them that changing distfiles after releases without
    changing the file names is not good practice.</para>
  </sect2>
</sect1>


<sect1 id="fixes.configure">
  <title>Fixing problems in the <emphasis>configure</emphasis> phase</title>

  <sect2 id="fixes.libtool">
    <title>Shared libraries - libtool</title>

    <para>pkgsrc supports many different machines, with different
    object formats like a.out and ELF, and varying abilities to do
    shared library and dynamic loading at all. To accompany this,
    varying commands and options have to be passed to the
    compiler, linker, etc. to get the Right Thing, which can be
    pretty annoying especially if you don't have all the machines
    at your hand to test things.  The
    <filename role="pkg">devel/libtool</filename> pkg
    can help here, as it just <quote>knows</quote> how to build
    both static and dynamic libraries from a set of source files,
    thus being platform-independent.</para>

    <para>Here's how to use libtool in a package in seven simple
    steps:</para>

    <orderedlist>
      <listitem>
	<para>Add <varname>USE_LIBTOOL=yes</varname> to the package
	Makefile.</para>
      </listitem>

      <listitem>
	<para>For library objects, use <quote>${LIBTOOL} --mode=compile
	${CC}</quote> in place of <quote>${CC}</quote>. You could even
	add it to the definition of <varname>CC</varname>, if only
	libraries are being built in a given Makefile. This one command
	will build both PIC and non-PIC library objects, so you need not
	have separate shared and non-shared library rules.</para>
      </listitem>

      <listitem>
	<para>For the linking of the library, remove any
	<quote>ar</quote>, <quote>ranlib</quote>, and <quote>ld
	-Bshareable</quote> commands, and instead use:</para>

	<programlisting>
${LIBTOOL} --mode=link \
    ${CC} -o ${.TARGET:.a=.la} \
        ${OBJS:.o=.lo} \
        -rpath ${PREFIX}/lib \
        -version-info major:minor
	</programlisting>

	<para>Note that the library is changed to have a
	<filename>.la</filename> extension, and the objects are
	changed to have a <filename>.lo</filename>
	extension. Change <varname>OBJS</varname> as
	necessary. This automatically creates all of the
	<filename>.a</filename>,
	<filename>.so.major.minor</filename>, and ELF symlinks (if
	necessary) in the build directory. Be sure to include
	<quote>-version-info</quote>, especially when major and
	minor are zero, as libtool will otherwise strip off the
	shared library version.</para>

	<para>From the libtool manual:</para>

	<programlisting>
So, libtool library versions are described by three integers:

CURRENT
The most recent interface number that this library implements.

REVISION
The implementation number of the CURRENT interface.

AGE
The difference between the newest and oldest interfaces that
this library implements.  In other words, the library implements
all the interface numbers in the range from number `CURRENT -
AGE' to `CURRENT'.

If two libraries have identical CURRENT and AGE numbers, then the
dynamic linker chooses the library with the greater REVISION number.
	</programlisting>

	<para>The <quote>-release</quote> option will produce
	different results for a.out and ELF (excluding symlinks)
	in only one case. An ELF library of the form
	<quote>libfoo-release.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote>
	will have a symlink of
	<quote>libfoo.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote>
	on an a.out platform. This is handled
	automatically.</para>

	<para>The <quote>-rpath argument</quote> is the install
	directory of the library being built.</para>

	<para>In the <filename>PLIST</filename>, include only the
	<filename>.la</filename> file, the other files will be
	added automatically.</para>
      </listitem>

      <listitem>
	<para>When linking shared object (<filename>.so</filename>)
	files, i.e. files that are loaded via &man.dlopen.3;, NOT
	shared libraries, use <quote>-module
	-avoid-version</quote> to prevent them getting version
	tacked on.</para>

	<para>The <filename>PLIST</filename> file gets the
	<filename>foo.so</filename> entry.</para>
      </listitem>

      <listitem>
	<para>When linking programs that depend on these libraries
	<emphasis>before</emphasis> they are installed, preface
	the &man.cc.1; or &man.ld.1; line with <quote>${LIBTOOL}
	--mode=link</quote>, and it will find the correct
	libraries (static or shared), but please be aware that
	libtool will not allow you to specify a relative path in
	-L (such as <quote>-L../somelib</quote>), because it
	expects you to change that argument to be the
	<filename>.la</filename> file. e.g.</para>

	<programlisting>
${LIBTOOL} --mode=link ${CC} -o someprog -L../somelib -lsomelib
	</programlisting>

	<para>should be changed to:</para>

	<programlisting>
${LIBTOOL} --mode=link ${CC} -o <replaceable>someprog</replaceable> <replaceable>../somelib/somelib.la</replaceable>
	</programlisting>

	<para>and it will do the right thing with the libraries.</para>
      </listitem>

      <listitem>
	<para>When installing libraries, preface the &man.install.1;
	or &man.cp.1; command with <quote>${LIBTOOL}
	--mode=install</quote>, and change the library name to
	<filename>.la</filename>. e.g.</para>

	<programlisting>
${LIBTOOL} --mode=install ${BSD_INSTALL_LIB} ${SOMELIB:.a=.la} ${PREFIX}/lib
	</programlisting>

	<para>This will install the static <filename>.a</filename>,
	shared library, any needed symlinks, and run
	&man.ldconfig.8;.</para>
      </listitem>

      <listitem>
	<para>In your <filename>PLIST</filename>, include only
	the <filename>.la</filename>
	file (this is a change from previous behaviour).</para>
      </listitem>
    </orderedlist>
  </sect2>


  <sect2 id="using-libtool">
    <title>Using libtool on GNU packages that already support libtool</title>

    <para>Add <varname>USE_LIBTOOL=yes</varname> to the
    package Makefile. This will override the package's own libtool
    in most cases.  For older libtool using packages,  libtool is
    made by ltconfig script during the do-configure step; you can
    check the libtool script location by doing <command>make
    configure; find work*/ -name libtool</command>.</para>

    <para><varname>LIBTOOL_OVERRIDE</varname> specifies which libtool
    scripts, relative to <varname>WRKSRC</varname>, to override.  By
    default, it is set to <quote>libtool */libtool
    */*/libtool</quote>.  If this does not match the location of the
    package's libtool script(s), set it as appropriate.</para>

    <para>If you do not need <filename>*.a</filename> static
    libraries built and installed, then use
    <varname>SHLIBTOOL_OVERRIDE</varname> instead.</para>

    <para>If your package makes use of the platform-independent library
    for loading dynamic shared objects, that comes with libtool
    (libltdl), you should include devel/libltdl/buildlink3.mk.</para>

    <para>Some packages use libtool incorrectly so that the package
    may not work or build in some circumstances. Some of the more
    common errors are:</para>

    <itemizedlist>
      <listitem>
	<para>The inclusion of a shared object (-module) as a dependent library in an
	executable or library. This in itself isn't a problem if one of two things
	has been done:</para>

	<orderedlist>
	  <listitem>
	    <para>The shared object is named correctly, i.e.
	    <filename>libfoo.la</filename>, not
	    <filename>foo.la</filename></para>
	  </listitem>

	  <listitem>
	    <para>The -dlopen option is used when linking an executable.</para>
	  </listitem>
	</orderedlist>
      </listitem>

      <listitem>
	<para>The use of libltdl without the correct calls to initialisation routines.
	The function lt_dlinit() should be called and the macro
	<varname>LTDL_SET_PRELOADED_SYMBOLS</varname> included in
	executables.</para>
      </listitem>
    </itemizedlist>
  </sect2>


  <sect2 id="autoconf-automake">
    <title>GNU Autoconf/Automake</title>

    <para>If a package needs GNU autoconf or automake to be executed
    to regenerate the configure script and Makefile.in makefile
    templates, then they should be executed in a pre-configure
    target.</para>

    <para>For packages that need only autoconf:</para>

    <programlisting>
AUTOCONF_REQD=  2.50            # if default version is not good enough
USE_TOOLS+=     autoconf        # use "autoconf213" for autoconf-2.13
...

pre-configure:
        cd ${WRKSRC} &amp;&amp; autoconf

...
    </programlisting>

    <para>and for packages that need automake and autoconf:</para>

    <programlisting>
AUTOMAKE_REQD=  1.7.1           # if default version is not good enough
USE_TOOLS+=     automake        # use "automake14" for automake-1.4
...

pre-configure:
        set -e; cd ${WRKSRC}; \
        aclocal; autoheader; automake -a --foreign -i; autoconf

...
    </programlisting>

    <para>Packages which use GNU Automake will almost certainly
    require GNU Make.</para>

    <para>There are times when the configure process makes
    additional changes to the generated files, which then causes
    the build process to try to re-execute the automake sequence.
    This is prevented by touching various files in the configure
    stage. If this causes problems with your package you can set
    <varname>AUTOMAKE_OVERRIDE=NO</varname> in the package
    Makefile.</para>
  </sect2>
</sect1>

<sect1 id="programming-languages">
  <title>Programming languages</title>

  <sect2 id="basic-programming-languages">
    <title>C, C++, and Fortran</title>

    <para>Compilers for the C, C++, and Fortran languages comes with
    the NetBSD base system.  By default, pkgsrc assumes that a package
    is written in C and will hide all other compilers (via the wrapper
    framework, see <xref linkend="buildlink" />).</para>

    <para>To declare which language's compiler a package needs, set
    the <varname>USE_LANGUAGES</varname> variable. Allowed values
    currently are <quote>c</quote>, <quote>c++</quote>, and
    <quote>fortran</quote> (and any combination).  The default is
    <quote>c</quote>.  Packages using GNU configure scripts, even if
    written in C++, usually need a C compiler for the configure
    phase.</para>
  </sect2>

  <sect2 id="java-programming-language">
    <title>Java</title>

    <para>If a program is written in Java, use the Java framework in
    pkgsrc.  The package must include
    <filename>../../mk/java-vm.mk</filename>.  This Makefile fragment
    provides the following variables:</para>

    <itemizedlist>
      <listitem><para><varname>USE_JAVA</varname> defines if a build
      dependency on the JDK is added.  If
      <varname>USE_JAVA</varname> is set to <quote>run</quote>, then
      there is only a runtime dependency on the JDK.  The default is
      <quote>yes</quote>, which also adds a build dependency on the
      JDK.</para></listitem>

      <listitem><para>Set <varname>USE_JAVA2</varname> to declare that
      a package needs a Java2 implementation.  The supported values
      are <quote>yes</quote>, <quote>1.4</quote>, and
      <quote>1.5</quote>.  <quote>yes</quote> accepts any Java2
      implementation, <quote>1.4</quote> insists on versions 1.4 or
      above, and <quote>1.5</quote> only accepts versions 1.5 or
      above. This variable is not set by default.</para></listitem>

      <listitem><para><varname>PKG_JAVA_HOME</varname> is
      automatically set to the runtime location of the used Java
      implementation dependency. It may be used to set
      <varname>JAVA_HOME</varname> to a good value if the program
      needs this variable to be defined.
      </para></listitem>
      <!-- XXX: describe PKG_JVM_DEFAULT and PKG_JVMS_ACCEPTED, but
	   not here -->
    </itemizedlist>
  </sect2>

  <sect2 id="perl-scripts">
    <title>Packages containing perl scripts</title>

    <para>If your package contains interpreted perl scripts, add
    <quote>perl</quote> to the <varname>USE_TOOLS</varname> variable
    and set <varname>REPLACE_PERL</varname> to ensure that the proper
    interpreter path is set. <varname>REPLACE_PERL</varname> should
    contain a list of scripts, relative to <varname>WRKSRC</varname>,
    that you want adjusted.  Every occurrence of
    <filename>*/bin/perl</filename> will be replaced with the full
    path to the perl executable.</para>

    <para>If a particular version of perl is needed, set the
    <varname>PERL5_REQD</varname> variable to the version number.  The
    default is <quote>5.0</quote>.</para>

    <para>See <xref linkend="perl-modules" /> for information
    about handling perl modules.</para>
  </sect2>

  <sect2 id="shell-scripts">
    <title>Packages containing shell scripts</title>

    <para><varname>REPLACE_SH</varname>,
    <varname>REPLACE_BASH</varname>, <varname>REPLACE_CSH</varname>,
    and <varname>REPLACE_KSH</varname> can be used to replace shell
    hash bangs in files. Please use the appropriate one, prefering
    <varname>REPLACE_SH</varname> in case this shell is sufficient.
    When using <varname>REPLACE_BASH</varname>, don't forget to add
    <filename>bash</filename> to <varname>USE_TOOLS</varname>.</para>
  </sect2>

  <sect2 id="other-programming-languages">
    <title>Other programming languages</title>

    <para>Currently, there is no special handling for other languages
    in pkgsrc.  If a compiler package provides a
    <filename>buildlink3.mk</filename> file, include that, otherwise
    just add a (build) dependency on the appropriate compiler
    package.</para>
  </sect2>
</sect1>

<sect1 id="fixes.build">
  <title>Fixing problems in the <emphasis>build</emphasis> phase</title>

	<para>The most common failures when building a package are that
	some platforms do not provide certain header files, functions or
	libraries, or they provide the functions in a library that the
	original package author didn't know. To work around this, you
	can rewrite the source code in most cases so that it does not
	use the missing functions or provides a replacement function.</para>

<sect2 id="fixes.build.cpp">
<title>Compiling C and C++ code conditionally</title>

	<para>If a package already comes with a GNU configure script, the
	preferred way to fix the build failure is to change the
	configure script, not the code. In the other cases, you can
	utilize the C preprocessor, which defines certain macros
	depending on the operating system and hardware architecture it
	compiles for. These macros can be queried using for example
	<varname>#if defined(__i386)</varname>. Almost every operating
	system, hardware architecture and compiler has its own macro.
	For example, if the macros <varname>__GNUC__</varname>,
	<varname>__i386__</varname> and <varname>__NetBSD__</varname>
	are all defined, you know that you are using NetBSD on an i386
	compatible CPU, and your compiler is GCC.</para>

	<para>The list of the following macros for hardware and
	operating system depends on the compiler that is used. For
	example, if you want to conditionally compile code on Solaris,
	don't use <varname>__sun__</varname>, as the SunPro compiler
	does not define it. Use <varname>__sun</varname> instead.</para>

<sect3 id="fixes.build.cpp.os">
<title>C preprocessor macros to identify the operating system</title>

        <para>To distinguish between 4.4 BSD-derived systems and the
        rest of the world, you should use the following code.</para>

<programlisting>
#include &lt;sys/param.h&gt;
#if (defined(BSD) &amp;&amp; BSD &gt;= 199306)
/* BSD-specific code goes here */
#else
/* non-BSD-specific code goes here */
#endif
</programlisting>

        <para>If this distinction is not fine enough, you can also test
	for the following macros.</para>

<programlisting>
Cygwin      __CYGWIN__
DragonFly   __DragonFly__
FreeBSD     __FreeBSD__
Haiku       __HAIKU__
Interix     __INTERIX
IRIX        __sgi (TODO: get a definite source for this)
Linux       linux, __linux, __linux__
MirBSD      __MirBSD__ (__OpenBSD__ is also defined)
Minix3      __minix
NetBSD      __NetBSD__
OpenBSD     __OpenBSD__
Solaris     sun, __sun
</programlisting>

</sect3>
<sect3 id="fixes.build.cpp.arch">
<title>C preprocessor macros to identify the hardware architecture</title>

<programlisting>
i386        i386, __i386, __i386__
MIPS        __mips
SPARC       sparc, __sparc
</programlisting>

</sect3>
<sect3 id="fixes.build.cpp.compiler">
<title>C preprocessor macros to identify the compiler</title>

<programlisting>
GCC         __GNUC__ (major version), __GNUC_MINOR__
MIPSpro     _COMPILER_VERSION (0x741 for MIPSpro 7.41)
SunPro      __SUNPRO_C (0x570 for Sun C 5.7)
SunPro C++  __SUNPRO_CC (0x580 for Sun C++ 5.8)
</programlisting>

</sect3>
</sect2>
<sect2 id="compiler-bugs">
<title>How to handle compiler bugs</title>

	<para>Some source files trigger bugs in the compiler, based on
        combinations of compiler version and architecture and almost
        always relation to optimisation being enabled.  Common symptoms
        are gcc internal errors or never finishing compiling a
	file.</para>

	<para>Typically, a workaround involves testing the
        <varname>MACHINE_ARCH</varname> and compiler version, disabling
        optimisation for that combination of file,
	<varname>MACHINE_ARCH</varname> and compiler, and documenting it
	in <filename>pkgsrc/doc/HACKS</filename>. See that file for a
	number of examples.</para>

</sect2>

<sect2 id="undefined-reference">
<title>Undefined reference to <quote>...</quote></title>

	<para>This error message often means that a package did not
	link to a shared library it needs. The following functions are
	known to cause this error message over and over.</para>

    <informaltable id="undefined-reference-functions">
      <tgroup cols="3">
	<thead><row><entry>Function</entry><entry>Library</entry><entry>Affected platforms</entry></row></thead>
	<tbody>
	  <row><entry>accept, bind, connect</entry><entry>-lsocket</entry><entry>Solaris</entry></row>
	  <row><entry>crypt</entry><entry>-lcrypt</entry><entry>DragonFly, NetBSD</entry></row>
	  <row><entry>dlopen, dlsym</entry><entry>-ldl</entry><entry>Linux</entry></row>
	  <row><entry>gethost*</entry><entry>-lnsl</entry><entry>Solaris</entry></row>
	  <row><entry>inet_aton</entry><entry>-lresolv</entry><entry>Solaris</entry></row>
	  <row><entry>nanosleep, sem_*, timer_*</entry><entry>-lrt</entry><entry>Solaris</entry></row>
	  <row><entry>openpty</entry><entry>-lutil</entry><entry>Linux</entry></row>
	</tbody>
      </tgroup>
    </informaltable>

    <para>To fix these linker errors, it is often sufficient to say
    <literal>LIBS.<replaceable>OperatingSystem</replaceable>+=
    -l<replaceable>foo</replaceable></literal> to the package
    <filename>Makefile</filename> and then say <command>bmake clean;
    bmake</command>.</para>

<sect3 id="undefined-reference-sunpro">
<title>Special issue: The SunPro compiler</title>

<para>When you are using the SunPro compiler, there is another
possibility. That compiler cannot handle the following code:</para>

<programlisting>
extern int extern_func(int);

static inline int
inline_func(int x)
{
        return extern_func(x);
}

int main(void)
{
        return 0;
}
</programlisting>

<para>It generates the code for <function>inline_func</function> even if
that function is never used. This code then refers to
<function>extern_func</function>, which can usually not be resolved. To
solve this problem you can try to tell the package to disable inlining
of functions.</para>

</sect3>

  </sect2>

  <sect2 id="out-of-memory">
    <title>Running out of memory</title>

    <para>Sometimes packages fail to build because the compiler runs
    into an operating system specific soft limit.  With the
    <varname>UNLIMIT_RESOURCES</varname> variable pkgsrc can be told
    to unlimit the resources.  Currently, the allowed values are
    <quote>datasize</quote> and <quote>stacksize</quote> (or both).
    Setting this variable is similar to running the shell builtin
    <command>ulimit</command> command to raise the maximum data
    segment size or maximum stack size of a process, respectively, to
    their hard limits.</para>
  </sect2>
</sect1>

<sect1 id="fixes.install">
  <title>Fixing problems in the <emphasis>install</emphasis> phase</title>

  <sect2 id="install-scripts">
    <title>Creating needed directories</title>

    <para>The BSD-compatible <command>install</command> supplied
    with some operating systems cannot create more than one
    directory at a time. As such, you should call
    <literal>${INSTALL_*_DIR}</literal> like this:</para>

    <programlisting>
${INSTALL_DATA_DIR} ${PREFIX}/dir1
${INSTALL_DATA_DIR} ${PREFIX}/dir2
    </programlisting>

    <para>You can also just append <quote><literal>dir1
    dir2</literal></quote> to the
    <varname>INSTALLATION_DIRS</varname> variable, which will
    automatically do the right thing.</para>

  </sect2>
  <sect2 id="where-to-install-documentation">
    <title>Where to install documentation</title>

    <para>In general, documentation should be installed into
    <filename>${PREFIX}/share/doc/${PKGBASE}</filename> or
    <filename>${PREFIX}/share/doc/${PKGNAME}</filename> (the latter
    includes the version number of the package).</para>

    <para>Many modern packages using GNU autoconf allow to set the
    directory where HTML documentation is installed with the
    <quote>--with-html-dir</quote> option. Sometimes using this flag
    is needed because otherwise the documentation ends up in
    <filename>${PREFIX}/share/doc/html</filename> or other
    places.</para>

    <para>An exception to the above is that library API documentation
    generated with the <filename
    role="pkg">textproc/gtk-doc</filename> tools, for use by special
    browsers (devhelp) should be left at their default location, which
    is <filename>${PREFIX}/share/gtk-doc</filename>.  Such
    documentation can be recognized from files ending in
    <filename>.devhelp</filename> or <filename>.devhelp2</filename>.
    (It is also acceptable to install such files in
    <filename>${PREFIX}/share/doc/${PKGBASE}</filename> or
    <filename>${PREFIX}/share/doc/${PKGNAME}</filename>; the
    <filename>.devhelp*</filename> file must be directly in that
    directory then, no additional subdirectory level is allowed in
    this case. This is usually achieved by using
    <quote>--with-html-dir=${PREFIX}/share/doc</quote>.
    <filename>${PREFIX}/share/gtk-doc</filename> is preferred
    though.)</para>

  </sect2>

  <sect2 id="installing-score-files">
    <title>Installing highscore files</title>

    <para>Certain packages, most of them in the games category, install
    a score file that allows all users on the system to record their
    highscores.  In order for this to work, the binaries need to be
    installed setgid and the score files owned by the appropriate
    group and/or owner (traditionally the "games" user/group).  Set
    <varname>USE_GAMESGROUP</varname> to yes to support this. The
    following variables, documented in more detail in
    <filename>mk/defaults/mk.conf</filename>, control this
    behaviour: <varname>GAMEDATAMODE</varname>,
    <varname>GAMEDIRMODE</varname>, <varname>GAMES_GROUP</varname>,
    <varname>GAMEMODE</varname>, <varname>GAME_USER</varname>.</para>

    <para>A package should therefore never hard code file ownership or
    access permissions but rely on <varname>INSTALL_GAME</varname> and
    <varname>INSTALL_GAME_DATA</varname> to set these
    correctly.</para>
  </sect2>

  <sect2 id="destdir-support">
    <title>Adding DESTDIR support to packages</title>

    <para><varname>DESTDIR</varname> support means that a package
    installs into a staging directory, not the final location of the
    files. Then a binary package is created which can be used for
    installation as usual. There are two ways: Either the package must
    install as root (<quote>destdir</quote>) or the package can
    install as non-root user (<quote>user-destdir</quote>).</para>

    <itemizedlist>
      <listitem><para><varname>PKG_DESTDIR_SUPPORT</varname> has to be
      set to <quote>none</quote>, <quote>destdir</quote>, or
      <quote>user-destdir</quote>. By default <varname>PKG_DESTDIR_SUPPORT</varname>
      is set to <quote>user-destdir</quote> to help catching more
      potential packaging problems. If bsd.prefs.mk is included in the Makefile,
      <varname>PKG_DESTDIR_SUPPORT</varname> needs to be set before
      the inclusion.</para></listitem>

      <listitem><para>All installation operations have to be prefixed with
      <filename>${DESTDIR}</filename>.</para></listitem>

      <listitem><para>automake gets this DESTDIR mostly right
      automatically. Many manual rules and pre/post-install often are
      incorrect; fix them.</para></listitem>

      <listitem><para>If files are installed with special owner/group
      use <varname>SPECIAL_PERMS</varname>.</para></listitem>

      <listitem><para>In general, packages should support
      <varname>UNPRIVILEGED</varname> to be able to use
      DESTDIR.</para></listitem>

    </itemizedlist>
  </sect2>


  <sect2 id="hardcoded-paths">
    <title>Packages with hardcoded paths to other interpreters</title>

    <para>Your package may also contain scripts with hardcoded paths to
      other interpreters besides (or as well as) perl.  To correct the
      full pathname to the script interpreter, you need to set the
      following definitions in your <filename>Makefile</filename> (we
    shall use <command>tclsh</command> in this example):</para>

    <programlisting>
REPLACE_INTERPRETER+=   tcl
REPLACE.tcl.old=        .*/bin/tclsh
REPLACE.tcl.new=        ${PREFIX}/bin/tclsh
REPLACE_FILES.tcl=      # list of tcl scripts which need to be fixed,
# relative to ${WRKSRC}, just as in REPLACE_PERL
    </programlisting>

    <note><para>Before March 2006, these variables were called
    <varname>_REPLACE.*</varname> and
    <varname>_REPLACE_FILES.*</varname>.</para></note>

  </sect2>


  <sect2 id="perl-modules">
    <title>Packages installing perl modules</title>

    <para>Makefiles of packages providing perl5 modules should include
    the Makefile fragment
    <filename>../../lang/perl5/module.mk</filename>.  It provides a
    <command>do-configure</command> target for the standard perl
    configuration for such modules as well as various hooks to tune
    this configuration.  See comments in this file for
    details.</para>

    <para>Perl5 modules will install into different places depending
    on the version of perl used during the build process.  To
    address this, pkgsrc will append lines to the
    <filename>PLIST</filename> corresponding to the files listed in
    the installed <filename>.packlist</filename> file generated by
    most perl5 modules.  This is invoked by defining
    <varname>PERL5_PACKLIST</varname> to a space-separated list of
    packlist files relative to <varname>PERL5_PACKLIST_DIR</varname>
    (<varname>PERL5_INSTALLVENDORARCH</varname> by default),
    e.g.:</para>

    <programlisting>
PERL5_PACKLIST= auto/Pg/.packlist
    </programlisting>

    <para>The perl5 config variables
    <varname>installarchlib</varname>,
    <varname>installscript</varname>,
    <varname>installvendorbin</varname>,
    <varname>installvendorscript</varname>,
    <varname>installvendorarch</varname>,
    <varname>installvendorlib</varname>,
    <varname>installvendorman1dir</varname>, and
    <varname>installvendorman3dir</varname> represent those
    locations in which components of perl5 modules may be installed,
    provided as variable with uppercase and prefixed with
    <varname>PERL5_</varname>, e.g. <varname>PERL5_INSTALLARCHLIB</varname>
    and may be used by perl5 packages that don't have a packlist.
    These variables are also substituted for in the
    <filename>PLIST</filename> as uppercase prefixed with
    <varname>PERL5_SUB_</varname>.</para>
  </sect2>


  <sect2 id="faq.info-files">
    <title>Packages installing info files</title>

    <para>Some packages install info files or use the
    <quote>makeinfo</quote>  or <quote>install-info</quote>
    commands.  <varname>INFO_FILES</varname> should be defined in
    the package Makefile so that <filename>INSTALL</filename> and
    <filename>DEINSTALL</filename> scripts will be generated to
    handle registration of the info files in the Info directory
    file. The <quote>install-info</quote> command used for the info
    files registration is either provided by the system, or by a
    special purpose package automatically added as dependency if
    needed.</para>

    <para><varname>PKGINFODIR</varname> is the directory under
    <filename>${PREFIX}</filename> where info files are primarily
    located. <varname>PKGINFODIR</varname> defaults to
    <quote>info</quote> and can be overridden by the user.</para>

    <para>The info files for the package should be listed in the
    package <filename>PLIST</filename>; however any split info files
    need not be listed.</para>

    <para>A package which needs the <quote>makeinfo</quote> command
    at build time must add <quote>makeinfo</quote> to
    <varname>USE_TOOLS</varname> in its Makefile. If a minimum
    version of the <quote>makeinfo</quote> command is needed it
    should be noted with the <varname>TEXINFO_REQD</varname>
    variable in the package <filename>Makefile</filename>. By
    default, a minimum version of 3.12 is required. If the system
    does not provide a <command>makeinfo</command> command or if it
    does not match the required minimum, a build dependency on the
    <filename role="pkg">devel/gtexinfo</filename> package will
    be added automatically.</para>

    <para>The build and installation process of the software provided
    by the package should not use the
    <command>install-info</command> command as the registration of
    info files is the task of the package
    <filename>INSTALL</filename> script, and it must use the
    appropriate <command>makeinfo</command> command.</para>

    <para>To achieve this goal, the pkgsrc infrastructure creates
    overriding scripts for the <command>install-info</command> and
    <command>makeinfo</command> commands in a directory listed early
    in <varname>PATH</varname>.</para>

    <para>The script overriding <command>install-info</command> has
    no effect except the logging of a message. The script overriding
    <command>makeinfo</command> logs a message and according to the
    value of <varname>TEXINFO_REQD</varname> either runs the appropriate
    <command>makeinfo</command> command or exit on error.</para>
  </sect2>

  <sect2 id="manpages">
    <title>Packages installing man pages</title>

    <para>All packages that install manual pages should install them
    into the same directory, so that there is one common place to look
    for them. In pkgsrc, this place is
    <literal>${PREFIX}/${PKGMANDIR}</literal>, and this expression
    should be used in packages. The default for
    <varname>PKGMANDIR</varname> is
    <quote><filename>man</filename></quote>. Another often-used value
    is <quote><filename>share/man</filename></quote>.</para>

    <note><para>The support for a custom <varname>PKGMANDIR</varname>
    is far from complete.</para></note>

    <para>The <filename>PLIST</filename> files can just use
    <filename>man/</filename> as the top level directory for the man
    page file entries, and the pkgsrc framework will convert as
    needed. In all other places, the correct
    <varname>PKGMANDIR</varname> must be used.</para>

    <para>Packages that are
    configured with <varname>GNU_CONFIGURE</varname> set as
    <quote>yes</quote>, by default will use the
    <filename>./configure</filename>
    --mandir switch to set where the man pages should be installed.
    The path is <varname>GNU_CONFIGURE_MANDIR</varname> which defaults
    to <varname>${PREFIX}/${PKGMANDIR}</varname>.</para>

    <para>Packages that use <varname>GNU_CONFIGURE</varname> but do not
    use --mandir, can set <varname>CONFIGURE_HAS_MANDIR</varname>
    to <quote>no</quote>.
    Or if the <filename>./configure</filename> script uses
    a non-standard use of --mandir, you can set
    <varname>GNU_CONFIGURE_MANDIR</varname> as needed.</para>

    <para>See <xref linkend="manpage-compression"/> for
    information on installation of compressed manual pages.</para>

  </sect2>

  <sect2 id="gconf-data-files">
    <title>Packages installing GConf data files</title>

    <para>If a package installs <filename>.schemas</filename> or
    <filename>.entries</filename> files, used by GConf,
    you need to take some extra steps to make sure they get registered
    in the database:</para>

    <orderedlist>
      <listitem>
	<para>Include <filename>../../devel/GConf/schemas.mk</filename>
	instead of its <filename>buildlink3.mk</filename> file.  This
	takes care of rebuilding the GConf database at installation and
	deinstallation time, and tells the package where to install
	GConf data files using some standard configure arguments.  It
	also disallows any access to the database directly from the
	package.</para>
      </listitem>

      <listitem>
	<para>Ensure that the package installs its
	<filename>.schemas</filename> files under
	<filename>${PREFIX}/share/gconf/schemas</filename>.  If they get
	installed under <filename>${PREFIX}/etc</filename>, you will
	need to manually patch the package.</para>
      </listitem>

      <listitem>
	<para>Check the PLIST and remove any entries under the etc/gconf
	directory, as they will be handled automatically.  See
	<xref linkend="faq.conf"/> for more information.</para>
      </listitem>

      <listitem>
	<para>Define the <varname>GCONF_SCHEMAS</varname> variable in
	your <filename>Makefile</filename> with a list of all
	<filename>.schemas</filename> files installed by the package, if
	any.  Names must not contain any directories in them.</para>
      </listitem>

      <listitem>
	<para>Define the <varname>GCONF_ENTRIES</varname> variable in
	your <filename>Makefile</filename> with a
	list of all <filename>.entries</filename> files installed by the
	package, if any. Names must not contain any directories in
	them.</para>
      </listitem>
    </orderedlist>
  </sect2>


  <sect2 id="scrollkeeper-data-files">
    <title>Packages installing scrollkeeper/rarian data files</title>

    <para>If a package installs <filename>.omf</filename> files, used by
    scrollkeeper/rarian, you need to take some extra steps to make sure they
    get registered in the database:</para>

    <orderedlist>
      <listitem>
	<para>Include
	<filename>../../mk/omf-scrollkeeper.mk</filename>
	instead of rarian's <filename>buildlink3.mk</filename> file.  This
	takes care of rebuilding the scrollkeeper database at
	installation and deinstallation time, and disallows any access
	to it directly from the package.</para>
      </listitem>

      <listitem>
	<para>Check the PLIST and remove any entries under the
	<filename>libdata/scrollkeeper</filename> directory, as they
	will be handled automatically.</para>
      </listitem>

      <listitem>
	<para>Remove the <filename>share/omf</filename> directory from
	the PLIST.  It will be handled by rarian. (<command>make
	print-PLIST</command> does this automatically.)</para>
      </listitem>
    </orderedlist>
  </sect2>


  <sect2 id="x11-fonts">
    <title>Packages installing X11 fonts</title>

    <para>If a package installs font files, you will need to rebuild
    the fonts database in the directory where they get installed at
    installation and deinstallation time.  This can be automatically
    done by using the pkginstall framework.</para>

    <para>You can list the directories where fonts are installed in the
    <varname>FONTS_DIRS.<replaceable>type</replaceable></varname>
    variables, where <replaceable>type</replaceable> can be one of
    <quote>ttf</quote>, <quote>type1</quote> or <quote>x11</quote>.
    Also make sure that the database file
    <filename>fonts.dir</filename> is not listed in the PLIST.</para>

    <para>Note that you should not create new directories for fonts;
    instead use the standard ones to avoid that the user needs to
    manually configure his X server to find them.</para>
  </sect2>


  <sect2 id="gtk2-modules">
    <title>Packages installing GTK2 modules</title>

    <para>If a package installs GTK2 immodules or loaders, you need to
    take some extra steps to get them registered in the GTK2 database
    properly:</para>

    <orderedlist>
      <listitem><para>Include
      <filename>../../x11/gtk2/modules.mk</filename> instead of its
      <filename>buildlink3.mk</filename> file.  This takes care of
      rebuilding the database at installation and deinstallation time.</para>
      </listitem>

      <listitem><para>Set <varname>GTK2_IMMODULES=YES</varname> if
      your package installs GTK2 immodules.</para>
      </listitem>

      <listitem><para>Set <varname>GTK2_LOADERS=YES</varname> if your package installs
      GTK2 loaders.</para>
      </listitem>

      <listitem><para>Patch the package to not touch any of the GTK2
      databases directly.  These are:</para>

	<itemizedlist>
	  <listitem><para><filename>libdata/gtk-2.0/gdk-pixbuf.loaders</filename></para></listitem>
	  <listitem><para><filename>libdata/gtk-2.0/gtk.immodules</filename></para></listitem>
	</itemizedlist>

      </listitem>

      <listitem><para>Check the <filename>PLIST</filename> and remove
      any entries under the <filename>libdata/gtk-2.0</filename>
      directory, as they will be handled automatically.</para>
      </listitem>
    </orderedlist>
  </sect2>


  <sect2 id="sgml-xml-data">
    <title>Packages installing SGML or XML data</title>

    <para>If a package installs SGML or XML data files that need to be
    registered in system-wide catalogs (like DTDs, sub-catalogs,
    etc.), you need to take some extra steps:</para>

    <orderedlist>
      <listitem>
	<para>Include
	<filename>../../textproc/xmlcatmgr/catalogs.mk</filename> in
	your <filename>Makefile</filename>, which takes care of
	registering those files in system-wide catalogs at
	installation and deinstallation time.</para>
      </listitem>

      <listitem>
	<para>Set <varname>SGML_CATALOGS</varname> to the full path of
	any SGML catalogs installed by the package.</para>
      </listitem>

      <listitem>
	<para>Set <varname>XML_CATALOGS</varname> to the full path of
	any XML catalogs installed by the package.</para>
      </listitem>

      <listitem>
	<para>Set <varname>SGML_ENTRIES</varname> to individual entries
	to be added to the SGML catalog.  These come in groups of
	three strings; see xmlcatmgr(1) for more information
	(specifically, arguments recognized by the 'add' action).
	Note that you will normally not use this variable.</para>
      </listitem>

      <listitem>
	<para>Set <varname>XML_ENTRIES</varname> to individual entries
	to be added to the XML catalog.  These come in groups of three
	strings; see xmlcatmgr(1) for more information (specifically,
	arguments recognized by the 'add' action).  Note that you will
	normally not use this variable.</para>
      </listitem>
    </orderedlist>
  </sect2>


  <sect2 id="mime-database">
    <title>Packages installing extensions to the MIME database</title>

    <para>If a package provides extensions to the MIME database by
    installing <filename>.xml</filename> files inside
    <filename>${PREFIX}/share/mime/packages</filename>, you
    need to take some extra steps to ensure that the database is kept
    consistent with respect to these new files:</para>

    <orderedlist>
      <listitem>
	<para>Include
	<filename>../../databases/shared-mime-info/mimedb.mk</filename>
	(avoid using the <filename>buildlink3.mk</filename> file from
	this same directory, which is reserved for inclusion from
	other <filename>buildlink3.mk</filename> files).  It takes
	care of rebuilding the MIME database at installation and
	deinstallation time, and disallows any access to it directly
	from the package.</para>
      </listitem>

      <listitem>
	<para>Check the PLIST and remove any entries under the
	<filename>share/mime</filename> directory,
	<emphasis>except</emphasis> for files saved under
	<filename>share/mime/packages</filename>.  The former are
	handled automatically by
	the update-mime-database program, but the latter are
	package-dependent and must be removed by the package that
	installed them in the first place.</para>
      </listitem>

      <listitem>
	<para>Remove any <filename>share/mime/*</filename> directories
	from the PLIST.  They will be handled by the shared-mime-info
	package.</para>
      </listitem>
    </orderedlist>
  </sect2>


  <sect2 id="intltool">
    <title>Packages using intltool</title>

    <para>If a package uses intltool during its build, add
    <literal>intltool</literal> to the <varname>USE_TOOLS</varname>,
    which forces it to use the intltool package provided by pkgsrc,
    instead of the one bundled with the distribution file.</para>

    <para>This tracks intltool's build-time dependencies and uses the
    latest available version; this way, the package benefits of any
    bug fixes that may have appeared since it was released.</para>
  </sect2>


  <sect2 id="startup-scripts">
    <title>Packages installing startup scripts</title>
    <para>If a package contains a rc.d script, it won't be copied into
    the startup directory by default, but you can enable it, by adding
    the option <varname>PKG_RCD_SCRIPTS=YES</varname> in
    &mk.conf;. This option will copy the scripts
    into <filename>/etc/rc.d</filename> when a package is installed, and
    it will automatically remove the scripts when the package is
    deinstalled.</para>
  </sect2>

  <sect2 id="tex-packages">
    <title>Packages installing TeX modules</title>

    <para>If a package installs TeX packages into the texmf tree,
    the <filename>ls-R</filename> database of the tree needs to be
    updated.</para>
    <note><para>Except the main TeX packages such as kpathsea,
    packages should install files
    into <filename>${PREFIX}/share/texmf-dist</filename>,
    not <filename>${PREFIX}/share/texmf</filename>.</para></note>

    <orderedlist>
      <listitem><para>Include
      <filename>../../print/kpathsea/texmf.mk</filename>.  This
      takes care of rebuilding the <filename>ls-R</filename>
      database at installation and deinstallation time.</para>
      </listitem>

      <listitem><para>If your package installs files into a texmf
      tree other than the one
      at <filename>${PREFIX}/share/texmf-dist</filename>,
      set <varname>TEX_TEXMF_DIRS</varname> to the list of all texmf
      trees that need database update.</para>
      <para>If your package also installs font map files that need
      to be registered using <command>updmap</command>,
      include <filename>../../print/tex-tetex/map.mk</filename> and
      set <varname>TEX_MAP_FILES</varname> and/or
      <varname>TEX_MIXEDMAP_FILES</varname> to the list of all
      such font map files.  Then <command>updmap</command> will
      be run automatically at installation/deinstallation to
      enable/disable font map files for TeX output
      drivers.</para>
      </listitem>

      <listitem><para>Make sure that none of <filename>ls-R</filename>
      databases are included in <filename>PLIST</filename>, as
      they will be removed only by the kpathsea package.</para>
      </listitem>
    </orderedlist>
  </sect2>

  <sect2 id="emulation-packages">
    <title>Packages supporting running binaries in
    emulation</title>

    <para>There are some packages that provide libraries and
    executables for running binaries from a one operating system
    on a different one (if the latter supports it).  One example
    is running Linux binaries on NetBSD.</para>

    <para>The <filename role="pkg">pkgtools/rpm2pkg</filename>
    helps in extracting and packaging Linux rpm packages.</para>

    <para>The <varname>CHECK_SHLIBS</varname> can be set to no to
    avoid the <command>check-shlibs</command> target, which tests
    if all libraries for each installed executable can be found by
    the dynamic linker.  Since the standard dynamic linker is run,
    this fails for emulation packages, because the libraries used
    by the emulation are not in the standard directories.</para>
  </sect2>

  <sect2 id="hicolor-theme">
    <title>Packages installing hicolor theme icons</title>

    <para>If a package installs images under the
    <filename>share/icons/hicolor</filename> and/or updates the
    <filename>share/icons/hicolor/icon-theme.cache</filename>
    database, you need to take some extra steps to make sure that the
    shared theme directory is handled appropriately and that the cache
    database is rebuilt:</para>

    <orderedlist>
      <listitem>
	<para>Include
	<filename>../../graphics/hicolor-icon-theme/buildlink3.mk</filename>.</para>
      </listitem>

      <listitem>
	<para>Check the <filename>PLIST</filename> and remove the
	entry that refers to the theme cache.</para>
      </listitem>

        <listitem>
	  <para>Ensure that the PLIST does not remove the shared icon
	  directories from the <filename>share/icons/hicolor</filename>
	  hierarchy because they will be handled automatically.</para>
        </listitem>
      </orderedlist>

      <para>The best way to verify that the PLIST is correct with
      respect to the last two points is to regenerate it using
      <command>make print-PLIST</command>.</para>
    </sect2>


    <sect2 id="desktop-files">
      <title>Packages installing desktop files</title>

      <para>If a package installs <filename>.desktop</filename> files
      under <filename>share/applications</filename> and these include
      MIME information (MimeType key), you need to take extra steps to
      ensure that they are registered into the MIME database:</para>

      <orderedlist>
        <listitem>
	  <para>Include
	  <filename>../../sysutils/desktop-file-utils/desktopdb.mk</filename>.</para>
        </listitem>

        <listitem>
          <para>Check the PLIST and remove the entry that refers to the
	  <filename>share/applications/mimeinfo.cache</filename> file.
	  It will be handled automatically.</para>
        </listitem>
      </orderedlist>

      <para>The best way to verify that the PLIST is correct with
      respect to the last point is to regenerate it using <command>make
      print-PLIST</command>.</para>
    </sect2>
</sect1>

<sect1 id="punting">
  <title>Marking packages as having problems</title>

  <para>In some cases one does not have the time to solve a problem
  immediately. In this case, one can plainly mark a package as broken.  For
  this, one just sets the variable <varname>BROKEN</varname> to the
  reason why the package is broken (similar to the
  <varname>RESTRICTED</varname> variable).  A user trying to build
  the package will immediately be shown this message, and the build
  will not be even tried.</para>
  <para><varname>BROKEN</varname> packages are removed from pkgsrc in irregular
  intervals.</para>
</sect1>

</chapter>