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

<!-- $NetBSD: fixes.xml,v 1.49 2006/04/06 06:21:57 reed Exp $ -->

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

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

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

      <para>The problem with package-defined variables that can be
        overridden via <varname>MAKECONF</varname> or
        <filename>/etc/mk.conf</filename> is that &man.make.1; expands a
        variable as it is used, but evaluates preprocessor-like
        statements (.if, .ifdef and .ifndef) as they are read.  So, to
        use any variable (which may be set in
        <filename>/etc/mk.conf</filename>) in one of the .if*
        statements, the file <filename>/etc/mk.conf</filename> must be
        included before that .if* statement.</para>

      <para>Rather than having a number of ad-hoc ways of including
        <filename>/etc/mk.conf</filename>, should it exist, or
        <varname>MAKECONF</varname>, should it exist, include the
        <filename>pkgsrc/mk/bsd.prefs.mk</filename> file in the package
        Makefile before any preprocessor-like .if, .ifdef, or .ifndef
        statements:</para>

<programlisting>
    .include "../../mk/bsd.prefs.mk"

    .if defined(USE_MENUS)
    # ...
    .endif
</programlisting>

      <para>If you wish to set the <varname>CFLAGS</varname> variable
        in <filename>/etc/mk.conf</filename>, please make sure to use:

<programlisting>
    CFLAGS+=  -your -flags
</programlisting>

        Using <varname>CFLAGS=</varname> (i.e. without the
        <quote>+</quote>) may lead to problems with packages that need
        to add their own flags.  Also, you may want to take a look at
        the <filename role="pkg">devel/cpuflags</filename> package if
	you're interested in optimization for the current CPU.</para>
    </sect2>

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

      <para>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>
    </sect2>

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

      <para>Some licenses restrict how software may be re-distributed.
        In order to satisfy 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.</para>
        </listitem>

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

          <para>Binaries may not be placed on CD-ROM.  Set this
            variable to <varname>${RESTRICTED}</varname> whenever a
            binary package may not be included on a CD-ROM.</para>
        </listitem>

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

          <para>Binaries may not be placed on an FTP server.  Set
            this variable to <varname>${RESTRICTED}</varname>
            whenever a binary package may not not be made available
            on the Internet.</para>
        </listitem>

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

          <para>Distfiles may not be placed on CD-ROM.  Set this
            variable to <varname>${RESTRICTED}</varname> if
            re-distribution of the source code or other distfile(s) is
            not allowed on CD-ROMs.</para>
        </listitem>

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

          <para>Distfiles may not be placed on FTP.  Set this variable
            to <varname>${RESTRICTED}</varname> if re-distribution of
            the source code or other distfile(s) via the Internet is not
            allowed.</para>
        </listitem>
      </itemizedlist>

      <para>Please note that the use of <varname>NO_PACKAGE</varname>,
        <varname>IGNORE</varname>, <varname>NO_CDROM</varname>, or other
        generic make variables to denote restrictions is deprecated,
        because they unconditionally prevent users from generating
        binary packages!</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 or 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 to use another package to build
            itself and there is no <filename>buildlink3.mk</filename>
            file available, use the <varname>BUILD_DEPENDS</varname>
            definition:</para>

<programlisting>
    BUILD_DEPENDS+= autoconf-2.13:../../devel/autoconf
</programlisting>
        </listitem>

        <listitem>

	<para>If your package needs a library with which to link and
	again there is no <filename>buildlink3.mk</filename> file
        available, this is specified using the
        <varname>DEPENDS</varname> definition. For example:</para>

<programlisting>
    DEPENDS+=       xpm-3.4j:../../graphics/xpm
</programlisting>

          <para>You can also use wildcards in package dependences:</para>

<programlisting>
    DEPENDS+=       xpm-[0-9]*:../../graphics/xpm
</programlisting>

          <para>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+=       tiff>=3.5.4:../../graphics/tiff
</programlisting>

          <para>This means that the package will build against version
            3.5.4 of the tiff library or newer.  Such a dependency may
            be warranted if, for example, the API of the library has
            changed with version 3.5.4 and a package would not compile
            against an earlier version of tiff.</para>

          <para>Please note that such dependencies should only be
            updated if a package requires  a newer pre-requisite, but
            not to denote recommendations such as 
            ABI changes that do not prevent a package from building
            correctly.  Such recommendations can be expressed using
            <varname>ABI_DEPENDS</varname>:</para>

<programlisting>
    ABI_DEPENDS+=   tiff>=3.6.1:../../graphics/tiff
</programlisting>

          <para>In addition to the above <varname>DEPENDS</varname>
            line, this denotes that while a package will build against
            tiff&gt;=3.5.4, at least version 3.6.1 is recommended.
            <varname>ABI_DEPENDS</varname> entries will be turned into
            dependencies unless explicitly ignored (in which case a
            warning will be printed).</para>

          <para>To ignore these ABI dependency recommendations and just
            use the required <varname>DEPENDS</varname>, set
            <varname>USE_ABI_DEPENDS=NO</varname>.   This may make
            it easier and faster to update packages built using pkgsrc,
            since older compatible dependencies can continue to be
            used. This is useful for people who watch their rebuilds
            very carefully; it is not very good as a general-purpose
            hammer.  If you use it, you need to be mindful of possible
            ABI changes, including those from the underlying OS.
</para>

	  <para>Packages that are built with recommendations ignored
            may not be uploaded to ftp.NetBSD.org by developers and
            should not be used across different systems that may have
            different versions of binary packages installed.</para>

          <para>For security fixes, please update the package
            vulnerabilities file. See <xref
            linkend="security-handling"/> for more
            information.</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>

          <para>The comment about wildcard dependencies from previous
            paragraph  applies here, too.</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>

      <para>Please also note the <varname>BUILD_USES_MSGFMT</varname>
        and <varname>BUILD_USES_GETTEXT_M4</varname> definitions, which
        are provided as convenience definitions.  The former works out
        whether &man.msgfmt.1; is part of the base system, and, if it isn't,
        installs the <filename role="pkg">devel/gettext</filename> package.
	The latter adds a build dependency on either an installed
	version of an older gettext package, or if it isn't, installs the
        <filename role="pkg">devel/gettext-m4</filename> package.</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 like another package in our
        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>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, use <command>make upload</command>
	in the same directory 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).</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="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
        file/<varname>MACHINE_ARCH</varname>/compiler  combination, and
        documenting it in  <filename>pkgsrc/doc/HACKS</filename>.  See
        that file for a number of examples!</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 pkg 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>.</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>
    </sect2>


    <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. There are some particular
        details you should pay attention to while working on pkgsrc.</para>

      <sect3 id="install-scripts">
        <title>${INSTALL}, ${INSTALL_DATA_DIR}, ...</title>

        <para>The BSD-compatible <command>install</command> supplied with some
          operating systems will not perform more than one operation at a time.
          As such, you should call <quote>${INSTALL}</quote>, etc. like this:</para>

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

    </sect2>
  </sect1>


  <sect1 id="downloading-issues">
    <title>Possible downloading issues</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 macro which displays a
	message explaining the situation.
	<varname>_FETCH_MESSAGE</varname> must be executable shell
	commands, not just a message. (Generally, it executes
	<varname>${ECHO}</varname>). See one of the following packages
	for an example:
	<filename role="pkg">fonts/acroread-jpnfont</filename>,
	<filename role="pkg">sysutils/storage-manager</filename>.</para>

    </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.
	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>. 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>.
	Do not forget regenerating the <filename>distinfo</filename> file
	after that, since it contains the <varname>DIST_SUBDIR</varname>
	path in the filenames.
        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="configuration-gotchas">
    <title>Configuration gotchas</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 pkg 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_DATA} ${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}; 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:
            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="fixes-build">
    <title>Building the package</title>

    <sect2 id="cpp-defines">
      <title>CPP defines</title>

      <para>Sometimes you need to compile different code depending on
      the target platform. The C preprocessor has a set of predefined
      macros that can be queried by using <varname>#ifdef FOO</varname>
      or <varname>#if defined(FOO)</varname>. Among these macros are
      usually ones that describe the target CPU and operating system.
      Depending of which of the macros are defined, you can write code
      that uses features unique to a specific platform. Generally you
      should rather use the GNU autotools (automake, autoconf, etc.) to
      check for specific features (like the existence of a header file,
      a function or a library), but sometimes this is not possible or
      desired.</para>

      <para>In that case you can use the predefined macros
      below to configure your code to the platform it runs on. 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>

      <sect3 id="fixes-build-cpp-opsys">
        <title>CPP defines for operating systems</title>

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

<programlisting><![CDATA[
    #include <sys/param.h>
    #if (defined(BSD) && BSD >= 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 use
        the following defines.</para>

<programlisting>
    FreeBSD     __FreeBSD__
    DragonFly	__DragonFly__
    Interix	__INTERIX
    Linux       linux, __linux, __linux__
    NetBSD      __NetBSD__
    OpenBSD     __OpenBSD__
    Solaris     sun, __sun
</programlisting>

      </sect3><sect3 id="fixes-build-cpp-cpu">
        <title>CPP defines for CPUs</title>

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

      </sect3><sect3 id="fixes-build-cpp-compiler">
        <title>CPP defines for compilers</title>

<programlisting>
    GCC         __GNUC__ (major version), __GNUC_MINOR__
    SunPro	__SUNPRO_C (0x570 for version 5.7)
</programlisting>

      </sect3>
    </sect2>

    <sect2 id="cpp-list-examples">
      <title>Examples of CPP defines for some platforms</title>

      <para>The list of the CPP identification macros for hardware and
      operating system may depend on the compiler that is used. The
      following list contains some examples that may help you to choose
      the right ones. 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>

      <variablelist>
	<varlistentry><term>GCC 3.3.3 + SuSE Linux 9.1 + i386</term>
        <listitem><para>__ELF__, __gnu_linux__, __i386, __i386__,
        __linux, __linux__, __unix, __unix__, i386, linux,
        unix.</para></listitem></varlistentry>

	<varlistentry><term>GCC 2.95 + NetBSD 1.6.2 + i386</term>
        <listitem><para>__ELF__, __NetBSD__, __i386, __i386__,
        i386.</para></listitem></varlistentry>

	<varlistentry><term>GCC 3.3.3 + NetBSD 2.0 + i386</term>
        <listitem><para>__ELF__, __NetBSD__, __i386, __i386__,
        i386.</para></listitem></varlistentry>

	<varlistentry><term>GCC 4 + Solaris 8 + SPARC</term>
        <listitem><para>__ELF__, __sparc, __sparc__, __sun, __sun__,
        __SVR4, __svr4__, __unix, __unix__, sparc, sun,
        unix.</para></listitem></varlistentry>

	<varlistentry><term>SunPro 5.7 + Solaris 8 + SPARC</term>
        <listitem><para>__SVR4, __sparc, __sun, __unix, sparc, sun,
        unix.</para></listitem></varlistentry>

      </variablelist>
    </sect2>

    <sect2 id="cpp-list">
      <title>Getting a list of CPP defines</title>

      <para>If your system uses the GNU C Compiler, you can get a list
      of symbols that are defined by default, e.g. to identify  the
      platform, with the following command:</para>

<programlisting>
    <![CDATA[gcc -E -dM - < /dev/null ]]>
</programlisting>

      <para>On other systems you may get the list by using the system's
      syscall trace utility (ktrace, truss, strace) to have a look which
      arguments are passed to the actual compiler.</para>

    </sect2>
  </sect1>


  <sect1 id="package-specific-actions">
    <title>Package specific actions</title>

    <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>help in fetching the distfiles</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>
    </sect2>


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

      <para>A package may be covered by a license which the user has
        or has not agreed to accept.  For these cases, pkgsrc contains
        a mechanism to note that a package is covered by a particular
        license, and the package cannot be built unless the user has
        accepted the license.  (Installation of binary packages are
        not currently subject to this mechanism.)  Packages with
        licenses that are either Open Source according to the Open
        Source Initiative or Free according to the Free Software
        Foundation will not be marked with a license tag.  Packages
        with licenses that have not been determined to meet either
        definition will be marked with a license tag referring to the
        license.  This will prevent building unless pkgsrc is informed
        that the license is acceptable, and enables displaying the
        license.</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.).  However, the above
	definition of licenses for which tags are not needed implies
	that packages with redistribution restrictions should have
	tags.</para>

      <para>
        Denoting that a package is covered by 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
        accepted:</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 it is considered appropriate,
          the line printed above can be added to
          <filename>/etc/mk.conf</filename> to indicate acceptance of
          the particular license:</para>

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

	<para>When adding a package with a new license, the license
          text should be added to <filename>pkgsrc/licenses</filename>
          for displaying. A list of known licenses can be seen in this
          directory as well as by looking at the list of (commented
          out) <varname>ACCEPTABLE_LICENSES</varname> variable
          settings in
          <filename>pkgsrc/mk/defaults/mk.conf</filename>.</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 denote acceptance of
	  the license for a single package without accepting the same
	  license text for another package.  In particular, this can
	  be inappropriate when e.g. one accepts a particular license to
	  indicate to pkgsrc that a fee has been paid.</para>
    </sect2>

    <sect2 id="installing-score-files">
      <title>Installing score 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).  The
        following variables, documented in more detail in
        <filename>mk/defaults/mk.conf</filename>, control this
        behaviour: <varname>SETGIDGAME</varname>,
        <varname>GAMEDATAMODE</varname>, <varname>GAMEGRP</varname>,
        <varname>GAMEMODE</varname>, <varname>GAMEOWN</varname>.</para>

      <para>Note that per default, setgid installation of games is
        disabled;  setting <varname>SETGIDGAME=YES</varname> will set all
        the other variables accordingly.</para>

      <para>A package should therefor 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="perl-scripts">
      <title>Packages containing perl scripts</title>

      <para>
        If your package contains interpreted perl scripts, 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.</para>
    </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
        paths to packlist files, e.g.:</para>

<programlisting>
    PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist
</programlisting>

      <para>The variables <varname>PERL5_SITELIB</varname>,
        <varname>PERL5_SITEARCH</varname>, and
        <varname>PERL5_ARCHLIB</varname> represent the three locations
        in which perl5 modules may be installed, and may be used by
        perl5 packages that don't have a packlist.  These three
        variables are also substituted for in the
        <filename>PLIST</filename>.</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>There are two mutually exclusive ways to specify the info
	files for the package:</para>

      <itemizedlist>
	<listitem>
	  <para>list each of info files in the package
	    <filename>PLIST</filename>; however any split info files
	    need not be listed, or</para>
	</listitem>

	<listitem>
	  <para>list the filename of each info file in the
	    <varname>INFO_FILES</varname> variable; however any split
	    info file filenames need not be listed. In this case
	    each of the info files should be installed into the
	    directory <filename>${PREFIX}/${PKGINFODIR}</filename>.
	</listitem>
	
      </itemizedlist>

      <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>Many packages install manual pages. The man pages
	are installed under <varname>${PREFIX}/${PKGMANDIR}</varname>
	which is <filename>/usr/pkg/man</filename> by default.
	<varname>PKGMANDIR</varname> defaults to <quote>man</quote>.
	For example, you can set <varname>PKGMANDIR</varname> to
	<quote>share/man</quote> to have man pages install under
	<filename>/usr/pkg/share/man/</filename> by default.
      </para>

      <note><para>The support for a custom <varname>PKGMANDIR</varname>
	is not 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.
      </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="gconf2-data-files">
      <title>Packages installing GConf2 data files</title>

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

      <orderedlist>
      <listitem>
        <para>Include <filename>../../devel/GConf2/schemas.mk</filename>
          instead of its <filename>buildlink3.mk</filename> file.  This
          takes care of rebuilding the GConf2 database at installation and
          deinstallation time, and tells the package where to install
          GConf2 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>GCONF2_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>GCONF2_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 data files</title>

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

      <orderedlist>
        <listitem>
          <para>Include
            <filename>../../textproc/scrollkeeper/omf.mk</filename>
            instead of its <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 scrollkeeper.</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:

        <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>
</para>
      </listitem>

      <listitem> <para>
        Check the PLIST 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, include the
        <filename>../../textproc/intltool/buildlink3.mk</filename> file,
        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
        <filename>/etc/mk.conf</filename>. 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 teTeX-texmf,
	  packages should install files
	  into <varname>PKG_LOCALTEXMFPREFIX</varname>,
	  not <varname>PKG_TEXMFPREFIX</varname>.</para></note>

      <orderedlist>
	<listitem><para>Include
            <filename>../../print/teTeX/module.mk</filename> instead
            of <filename>../../mk/tex.buildlink3.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 <varname>PKG_LOCALTEXMFPREFIX</varname>,
            set <varname>TEXMFDIRS</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>,
	    set <varname>TEX_FONTMAPS</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 teTeX-bin package.</para>
	</listitem>
      </orderedlist>
    </sect2>

  </sect1>


  <sect1 id="feedback-to-author">
    <title>Feedback to the author</title>

    <para>If you have found any bugs in the package you make available,
      if you had to do special steps to make it run under NetBSD or
      if you enhanced the software in various other ways, be sure
      to report these changes back to the original author of the
      program! With that kind of support, the next release of the
      program can incorporate these fixes, and people not using the
      NetBSD packages system can win from your efforts.</para>

    <para>Support the idea of free software!</para>
  </sect1>
</chapter>