pkgsrc/doc/guide/files/fixes.xml
2020-06-18 20:30:12 +00:00

2486 lines
96 KiB
XML

<!-- $NetBSD: fixes.xml,v 1.158 2020/06/18 20:30:12 wiz Exp $ -->
<chapter id="fixes"> <?dbhtml filename="fixes.html"?>
<title>Making your package work</title>
<sect1 id="general-operation">
<title>General operation</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 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 (the lines in
<filename>Makefile</filename> that are indented with a tab) this
is no problem, since variables 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>To check whether a variable can be used at load time,
run <command>pkglint -Wall</command> on your package.</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>A package can set the <varname>INTERACTIVE_STAGE</varname>
variable to define which stages need interaction. This should be
done in the package's <filename>Makefile</filename>, e.g.:</para>
<programlisting>
INTERACTIVE_STAGE= configure install
</programlisting>
<para>The user can then decide to skip this package by setting the
<varname>BATCH</varname> variable. Packages that require interaction
are also excluded from bulk builds.</para>
</sect2>
<sect2 id="handling-licenses">
<title>Handling licenses</title>
<para>Authors of software can choose the licence under which software
can be copied. The Free Software Foundation has declared some
licenses "Free", and the Open Source Initiative has a definition of
"Open Source".</para>
<para>By default, pkgsrc allows packages with Free or Open Source
licenses to be built. To allow packages with other licenses to be
built as well, the pkgsrc user needs to add these licenses to the
<varname>ACCEPTABLE_LICENSES</varname> variable in &mk.conf;. Note
that this variable only affects which packages may be
<emphasis>built</emphasis>, while the license terms often also
restrict the actual use of the package and its redistribution.</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 pkgsrc
user can override the default by setting the
<varname>ACCEPTABLE_LICENSES</varname> variable with "=" instead
of "+=". The licenses accepted by default are defined in the
<varname>DEFAULT_ACCEPTABLE_LICENSES</varname> variable in the file
<filename>pkgsrc/mk/license.mk</filename>.</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>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>
<sect3 id="new-license">
<title>Adding a package with a new license</title>
<para>When adding a package with a new license, the following steps
are required:</para>
<orderedlist>
<listitem>
<para>Check whether the license qualifies as Free or Open Source by
referencing <ulink
url="https://www.gnu.org/licenses/license-list.en.html">Various
Licenses and Comments about Them</ulink> and <ulink
url="https://opensource.org/licenses/alphabetical">Licenses by Name |
Open Source Initiative</ulink>. If this is the case, the filename in
<filename>pkgsrc/licenses/</filename> does not need the
<filename>-license</filename> suffix, and the license name should be
added 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>
</itemizedlist>
</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>
</sect3>
<sect3 id="change-license">
<title>Change to the license</title>
<para>When the license changes (in a way other than formatting),
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 (FSF or OSI).</para>
</sect3>
</sect2>
<sect2 id="restricted-packages">
<title>Restricted packages</title>
<para>Some licenses restrict how software may be re-distributed.
By declaring the restrictions, package tools can
automatically refrain from e.g. placing binary packages on FTP
sites.</para>
<para>There are four possible restrictions, 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.
"FTP" means making the source or binary file available over the
Internet at no charge.
"CD-ROM" means making the source or binary available on some kind of
media, together with other source and binary packages, 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 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>DEPENDS</varname>,
<varname>BUILD_DEPENDS</varname>,
<varname>TOOL_DEPENDS</varname>, and
<varname>TEST_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 is that 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>, <varname>TOOL_DEPENDS</varname>,
and <varname>TEST_DEPENDS</varname> definitions do not, marking a
dependency that is only needed for building or testing the resulting
package. See also <xref linkend="creating"/> for more information.</para>
<para>This means that if you only need a package present whilst
you are building or testing, it should be noted as a
<varname>TOOL_DEPENDS</varname>,
<varname>BUILD_DEPENDS</varname>, or
<varname>TEST_DEPENDS</varname>. When cross-compiling,
<varname>TOOL_DEPENDS</varname> are <emphasis>native</emphasis>
packages, i.e. packages for the architecture where the package
is built;
<varname>BUILD_DEPENDS</varname> are <emphasis>target</emphasis>
packages, i.e., packages for the architecture for which the package
is built.</para>
<para>The format for a <varname>DEPENDS</varname>,
<varname>BUILD_DEPENDS</varname>, <varname>TOOL_DEPENDS</varname>,
and <varname>TEST_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>TOOL_DEPENDS</varname> definition:</para>
<programlisting>
TOOL_DEPENDS+= itstool-[0-9]*:../../textproc/itstool
</programlisting>
</listitem>
<listitem>
<para>If your package needs static libraries to link against, header
files to include, etc. from another package to build,
use the <varname>BUILD_DEPENDS</varname> definition.</para>
<!--
<programlisting>
BUILD_DEPENDS+= TODO: find a good example
</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 tex-latex-bin package
when it runs, and that is specified:</para>
<programlisting>
DEPENDS+= tex-latex-bin-[0-9]*:../../print/tex-latex-bin
</programlisting>
</listitem>
<listitem>
<para>If your package includes a test suite that has extra
dependencies only required for this purpose (frequently this
can be run as a <quote>make test</quote> target), use the
<varname>TEST_DEPENDS</varname> variable.</para>
</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,
set
<varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
to the appropriate pattern before including its
<filename>buildlink3.mk</filename> file, e.g.</para>
<programlisting>
BUILDLINK_API_DEPENDS.jpeg+= jpeg>=9.0
.include "../../graphics/jpeg/buildlink3.mk"
</programlisting>
<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 or has the same <varname>PKGNAME</varname>.</para>
<para>For example, <filename role="pkg">x11/libXaw3d</filename>
and <filename role="pkg">x11/Xaw-Xpm</filename>
install the same shared library, thus you set in
<filename>pkgsrc/x11/libXaw3d/Makefile</filename>:</para>
<programlisting>
CONFLICTS= Xaw-Xpm-[0-9]*
</programlisting>
<para>and in <filename>pkgsrc/x11/Xaw-Xpm/Makefile</filename>:</para>
<programlisting>
CONFLICTS= libXaw3d-[0-9]*
</programlisting>
<para>&man.pkg.add.1 is able to detect attempts to install packages
that conflict with existing packages and abort. However, in many
situations this is too late in the process. Binary package managers
will not know about the conflict until they attempt to install the
package after already downloading it and all its dependencies.
Users may also waste time building a package and its dependencies
only to find out at the end that it conflicts with another package
they have installed.</para>
<para>To avoid these issues <varname>CONFLICTS</varname> entries
should be added in all cases where it is known that packages conflict
with each other. These <varname>CONFLICTS</varname> entries are
exported in &man.pkg.summary.5 files and consumed by binary package
managers to inform users that packages cannot be installed onto
the target system.</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>BROKEN_ON_PLATFORM</varname>. If
the package builds and runs on a small handful of platforms,
set <varname>BROKEN_EXCEPT_ON_PLATFORM</varname> instead.
Both <varname>BROKEN_ON_PLATFORM</varname> and
<varname>BROKEN_EXCEPT_ON_PLATFORM</varname> are OS triples
(OS-version-platform) that can use glob-style
wildcards.</para>
<para>If a package is not appropriate for some platforms (as
opposed to merely broken), a different set of variables should be
used as this affects failure reporting and statistics.
If the package is appropriate for most platforms, the exceptions
should be noted with <varname>NOT_FOR_PLATFORM</varname>. If
the package is appropriate for only a small handful of platforms
(often exactly one), 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
multiple times in the same file, it is cumbersome to maintain a patch
file for this. This is where the SUBST framework steps in. It provides an
easy-to-use interface for replacing text in files. It just needs the
following information:</para>
<itemizedlist>
<listitem><para>In which phase of the package build cycle should the
replacement happen?</para></listitem>
<listitem><para>In which files should the replacement
happen?</para></listitem>
<listitem><para>Which text should be replaced with
what?</para></listitem>
</itemizedlist>
<para>This information is encoded in a block of <varname>SUBST</varname>
variables. A minimal example is:</para>
<programlisting>
SUBST_CLASSES+= paths
SUBST_STAGE.paths= pre-configure
SUBST_FILES.paths= src/*.c
SUBST_SED.paths= -e 's,/usr/local,${PREFIX},g'
</programlisting>
<para>Translated into English, it means: In the pre-configure stage (that
is, after applying the patches from the patches/ directory and before
running the configure script and the portability check), replace the text
<literal>/usr/local</literal> with the content of the variable
<varname>PREFIX</varname>.</para>
<para>Each SUBST block starts by appending an identifier to
<varname>SUBST_CLASSES</varname> (note the <literal>+=</literal>). This
identifier can be chosen freely by the package. If there should ever be
duplicate identifiers, the pkgsrc infrastructure will catch this and fail
early, so don't worry about name collisions.</para>
<para>Except for <varname>SUBST_CLASSES</varname>, all variables in a
SUBST block are parameterized using this identifier. In the remainder of
this section, these parameterized variables are written as
<varname>SUBST_STAGE.*</varname>.</para>
<programlisting>
SUBST_CLASSES+= paths
SUBST_STAGE.paths= pre-configure
SUBST_MESSAGE.paths= Fixing absolute paths.
SUBST_FILES.paths= src/*.c
SUBST_FILES.paths+= scripts/*.sh
SUBST_SED.paths= -e 's,"/usr/local,"${PREFIX},g'
SUBST_SED.paths+= -e 's,"/var/log,"${VARBASE}/log,g'
SUBST_VARS.paths= LOCALBASE PREFIX PKGVERSION
</programlisting>
<para>To get a complete picture about the SUBST substitutions, run
<command>bmake show-all-subst</command>. If something doesn't work as
expected, run pkglint on the package, which detects several typical
mistakes surrounding the SUBST blocks. For any questions that might
remain after this, have a look at
<filename>mk/subst.mk</filename>.</para>
<sect3 id="fixes.subst.when">
<title>Choosing the time where the substitutions happen</title>
<para>The <varname>SUBST_STAGE.*</varname> is one of
{pre,do,post}-{extract,patch,configure,build,test,install}. Of these,
<literal>pre-configure</literal> is used most often, by far. The most
popular stages are, in chronological order:</para>
<variablelist>
<varlistentry><term><literal>post-extract</literal></term>
<listitem><para>The substitutions are applied immediately after the
distfiles are extracted. Running <command>bmake extract</command> on the
package will leave no traces of the original files.</para>
<para>When the substitution applies to files for which there is also a
patch in the <filename>patches/</filename> directory, this means that the
patches will be computed based on the result of the substitution. When
these patches are sent to the upstream maintainer later, to be fixed in
the upstream package, these patches may no longer match what the upstream
author is used to. Because of this, <literal>pre-configure</literal> is
often a better choice.</para></listitem></varlistentry>
<varlistentry><term><literal>pre-configure</literal></term>
<listitem><para>The substitutions are applied after the patches from the
<filename>patches/</filename> directory. This makes it possible to run
<command>bmake patch</command> on the package, after which the patches
can be edited using the tools pkgvi and mkpatches from the <filename
role="pkg">pkgtools/pkgdiff</filename> package.</para>
<para>When updating the patches, it is helpful to explicitly separate the
<command>bmake patch</command> from the <command>bmake
configure</command>, and to only edit the patches between these commands.
Otherwise the substitutions from the SUBST block will end up in the patch
file. When this happens in really obvious ways, pkglint will complain
about patches that contain a hard-coded <literal>/usr/pkg</literal>
instead of the correct and intended <literal>@PREFIX@</literal>, but it
can only detect these really obvious
cases.</para></listitem></varlistentry>
<varlistentry><term><literal>do-configure</literal></term>
<listitem><para>This stage should only be used if the package defines a
<literal>pre-configure</literal> action itself, and the substitution must
happen after that. Typical examples are packages that use the
<literal>pre-configure</literal> stage to regenerate the GNU configure
script from
<filename>configure.ac</filename>.</para></listitem></varlistentry>
<varlistentry><term><literal>post-configure</literal></term>
<listitem><para>This stage is used to fix up any mistakes by the
configure stage.</para></listitem></varlistentry>
<varlistentry><term><literal>pre-build</literal></term>
<listitem><para>This stage should only be used for substitutions that are
clearly related to building the package, not for fixing the
configuration. Substitutions for pathnames (such as replacing
<filename>/usr/local</filename> with <literal>${PREFIX}</literal>) or
user names (such as replacing <literal>@MY_USER@</literal> with the
actual username) belong in pre-configure or post-configure
instead.</para></listitem></varlistentry>
<varlistentry><term><literal>post-build</literal></term>
<listitem><para>Just as with pre-build, this stage should only be used
for substitutions that are clearly related to building the package, not
for fixing the configuration. Substitutions for pathnames (such as
replacing <filename>/usr/local</filename> with
<literal>${PREFIX}</literal>) or user names (such as replacing
<literal>@MY_USER@</literal> with the actual username) belong in
pre-configure or post-configure instead.</para>
<para>A typical use is to update pkg-config files to include the rpath
compiler options.</para></listitem></varlistentry>
<varlistentry><term><literal>pre-install</literal></term>
<listitem><para>In general, the install phase should be as simple as
possible. As with the pre-build and post-build stages, it should not be
used to fix pathnames or user names, these belong in pre-configure
instead. There are only few legitimate use cases for applying
substitutions in this stage.</para></listitem></varlistentry>
</variablelist>
</sect3>
<sect3 id="fixes.subst.where">
<title>Choosing the files where the substitutions happen</title>
<para>The <varname>SUBST_FILES.*</varname> variable contains a list of
filename patterns. These patterns are relative to
<varname>WRKSRC</varname> since that is where most substitutions happen.
A typical example is:</para>
<programlisting>
SUBST_FILES.path= Makefile */Makefile */*/Makefile *.[ch]
</programlisting>
<para>The above patterns, especially the last, are quite broad. The SUBST
implementation checks that each filename pattern that is mentioned here
has an effect. For example, if none of the
<filename>*/*/Makefile</filename> files contains the patterns to be found
and substituted, that filename pattern is redundant and should be left
out. By default, the SUBST framework will complain with an error message.
If the text to be substituted occurs in some of the files from a single
pattern, but not in all of them, that is totally ok, and the SUBST
framework will only print an INFO message for those files.</para>
<para>If there is a good reason for having redundant filename patterns,
set <varname>SUBST_NOOP_OK.*</varname> to <literal>yes</literal>.</para>
<para>Another popular way of choosing the files for the substitutions is
via a shell command, like this:</para>
<programlisting>
C_FILES_CMD= cd ${WRKSRC} &amp;&amp; ${FIND} . -name '*.c'
SUBST_FILES.path= ${C_FILES_CMD:sh}
</programlisting>
<para>The variable name <varname>C_FILES_CMD</varname> in this example is
freely chosen and independent of the SUBST framework.</para>
<para>In this variant, the <varname>SUBST_FILES.*</varname> variable
lists each file individually. Thereby chances are higher that there are
filename patterns in which no substitution happens. Since the SUBST
framework cannot know whether the filename patterns in
<varname>SUBST_FILES.*</varname> have been explicitly listed in the
Makefile (where any redundant filename pattern would be suspicious) or
been generated by a shell command (in which redundant filename patterns
are more likely and to be expected), it will complain about these
redundant filename patterns. Therefore, SUBST blocks that use a shell
command to generate the list of filename patterns often need to set
<varname>SUBST_NOOP_OK.*</varname> to <literal>yes</literal>.</para>
</sect3>
<sect3 id="fixes.subst.what">
<title>Choosing what to substitute</title>
<para>In most cases, the substitutions are given using one or more
&man.sed.1; commands, like this:</para>
<programlisting>
SUBST_SED.path= -e 's|/usr/local|${PREFIX}|g'
</programlisting>
<para>Each of the sed commands needs to be preceded by the
<literal>-e</literal> option and should be specified on a line of its
own, to avoid hiding short sed commands at the end of a line.</para>
<para>Since the sed commands often contain shell metacharacters as the
separator (the <literal>|</literal> in the above example), it is common
to enclose them in single quotes.</para>
<para>A common substitution is to replace placeholders of the form
<literal>@VARNAME@</literal> with their pkgsrc counterpart variable
<literal>${VARNAME}</literal>. A typical example is:</para>
<programlisting>
SUBST_VARS.path= PREFIX
</programlisting>
<para>This type of substitutions is typically done by the GNU configure
scripts during the do-configure stage, but in some cases these need to be
overridden. The same pattern is also used when a package defines patches
that replace previously hard-coded paths like
<literal>/usr/local</literal> with a <literal>@PREFIX@</literal>
placeholder first, which then gets substituted by the actual
<literal>${PREFIX}</literal> in the pre-configure stage. In many of these
cases, it works equally well to just use the SUBST framework to directly
replace <literal>/usr/local</literal> with <literal>${PREFIX}</literal>,
thereby omitting the intermediate patch file.</para>
<para>If the above is not flexible enough, it is possible to not use sed
at all for the substitution but to specify an entirely different command,
like this:</para>
<programlisting>
SUBST_FILTER_CMD.path= LC_ALL=C ${TR} -d '\r'
</programlisting>
<para>This is used for the few remaining packages in which the
distributed files use Windows-style line endings that need to be
converted to UNIX-style line endings.</para>
</sect3>
<sect3 id="fixes.subst.other">
<title>Other SUBST variables</title>
<para>When a SUBST block is applied during a package build, a message is
logged. The default message is fine for most purposes but can be
overridden by setting <literal>SUBST_MESSAGE.*</literal> to an individual
message.</para>
</sect3>
</sect2>
</sect1>
<sect1 id="fixes.fetch">
<title>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> (but take care with
python or ruby packages, where <varname>PKGNAME</varname> includes
a variable prefix). 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>
<sect2 id="build.fetch.github">
<title>Packages hosted on github.com</title>
<para>Helper methods exist for packages hosted on github.com which
will often have distfile names that clash with other packages, for
example <filename>1.0.tar.gz</filename>. Use one of the three recipes
from below:</para>
<sect3 id="build.fetch.github.tag">
<title>Fetch based on a tagged release</title>
<para>If your distfile URL looks similar to
<literal>https://github.com/username/exampleproject/archive/v1.0.zip</literal>,
then you are packaging a tagged release.</para>
<programlisting>
DISTNAME= exampleproject-1.0
MASTER_SITES= ${MASTER_SITE_GITHUB:=username/}
#GITHUB_PROJECT= # can be omitted if same as DISTNAME
GITHUB_TAG= v${PKGVERSION_NOREV}
EXTRACT_SUFX= .zip
</programlisting>
</sect3>
<sect3 id="build.fetch.github.commit">
<title>Fetch based on a specific commit</title>
<para>If your distfile URL looks similar to
<literal>https://github.com&#x200B;/example&#x200B;/example&#x200B;/archive&#x200B;/988881adc9fc3655077dc2d4d757d480b5ea0e11.tar.gz</literal>,
then you are packaging a specific commit not tied to a
release.</para>
<programlisting>
DISTNAME= example-1.0
MASTER_SITES= ${MASTER_SITE_GITHUB:=example/}
#GITHUB_PROJECT= # can be omitted if same as DISTNAME
GITHUB_TAG= 988881adc9fc3655077dc2d4d757d480b5ea0e11
</programlisting>
</sect3>
<sect3 id="build.fetch.github.release">
<title>Fetch based on release</title>
<para>If your distfile URL looks similar to
<literal>https://github.com&#x200B;/username/exampleproject&#x200B;/releases&#x200B;/download&#x200B;/rel-1.6&#x200B;/offensive-1.6.zip</literal>,
then you are packaging a release.</para>
<programlisting>
DISTNAME= offensive-1.6
PKGNAME= ${DISTNAME:S/offensive/proper/}
MASTER_SITES= ${MASTER_SITE_GITHUB:=username/}
GITHUB_PROJECT= exampleproject
GITHUB_RELEASE= rel-${PKGVERSION_NOREV} # usually just set this to ${DISTNAME}
EXTRACT_SUFX= .zip
</programlisting>
</sect3>
</sect2>
</sect1>
<sect1 id="fixes.configure">
<title>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> in a she-bang line 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.
Each should contain a list of scripts, relative to
<varname>WRKSRC</varname>, that you want adjusted. Every
occurrence of the matching shell in a she-bang line will be
replaced with the full path to the shell executable.
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>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__
Mac OS X __APPLE__
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.</para>
<para>This used to be a big problem in the past, but is rarely
needed now as compiler technology has matured. If you still need
to add a compiler specific workaround, please do so in the file
<filename>hacks.mk</filename> and describe the symptom and
compiler version as detailed as possible.</para>
</sect2>
<sect2 id="fixes.build.header">
<title>No such file or directory</title>
<para>Compilation sometimes fails with an error message like this:</para>
<programlisting>
.../x11/gtk3/work/gtk+-3.24.12/gdk/gdktypes.h:35:10:
fatal error: pango/pango.h: No such file or directory
</programlisting>
<para>The proper way to fix this problem depends on the type of the
header, which is described in the following sections.</para>
<sect3 id="fixes.build.header.bl3">
<title>Headers from other packages</title>
<para>If the header name looks like it comes from a different package,
that other package should be included via the buildlink3
framework.</para>
<para>First, look whether the header is somewhere in the buildlink3
directory below <varname>WRKDIR</varname>. In the above case of
the missing Pango header:</para>
<programlisting>
&uprompt; find work/.buildlink/ -print | grep -F pango/pango.h
</programlisting>
<para>In the case of Pango, the output is:</para>
<programlisting>
work/.buildlink/include/pango-1.0/pango/pango.h
</programlisting>
<para>If the <filename>pango/pango.h</filename> file were placed directly
in the <filename>.buildlink</filename> directory, it would have been
found automatically. There is an extra <filename>pango-1.0</filename>
path component though, which means that the compiler command line must
contain an option of the form
<literal>-I${BUILDLINK3_PREFIX.pango}/include/pango-1.0</literal>. In
most cases this option is generated by the configure script, which can be examined using:</para>
<programlisting>
&uprompt; $ grep -o '[-]I[^[:space:]]*/pango[^[:space:]]*' work/*/Makefile
-I/usr/pkg/include/pango-1.0
-I/usr/pkg/include/pango-1.0
-I/usr/pkg/include/pango-1.0
-I/usr/pkg/include/pango-1.0
-I/usr/pkg/include/pango-1.0
</programlisting>
<para>This looks good. These options are transformed by the buildlink
wrapper to refer to the correct path inside
<filename>work/.buildlink</filename>.</para>
<para>Since the compilation fails though, examine the compiler command
lines in <filename>work/.work.log</filename> to see whether the
<literal>-I</literal> option is included in the particular command
line.</para>
<para>To further analyze the situation, run <command>bmake
build-env</command>, which sets up an interactive, realistic environment
including all the pkgsrc wrapper commands and environment variables. From
there, try to compile some simple example programs that use the
header.</para>
</sect3>
<sect3 id="fixes.build.header.gen">
<title>Headers generated during the build</title>
<para>If the name of the header seems to come from the package itself,
and if the build is run with parallel jobs, the package may have some
undeclared dependencies between the <filename>.c</filename> and the
<filename>.h</filename> files, and a C file is compiled before its
required header is generated.</para>
<para>To see whether the build runs with parallel jobs, run
<command>bmake show-all-build | grep JOBS</command>. Its output looks
like this:</para>
<programlisting>
usr MAKE_JOBS= 7
pkg MAKE_JOBS_SAFE # undefined
def _MAKE_JOBS_N= 7
</programlisting>
<para>In this case the pkgsrc user has asked pkgsrc to build packages
with 7 jobs in parallel (<varname>MAKE_JOBS</varname>). The
package could have disabled parallel builds by setting
<varname>MAKE_JOBS_SAFE</varname> to <literal>no</literal>, but
in this case it hasn't.</para>
<para>To see whether the build failure is caused by parallel builds,
first save the exact error message and a bit of context, maybe you need
it later for reporting a bug. Next, run:</para>
<programlisting>
MAKE_JOBS_SAFE=no bmake clean build
</programlisting>
<para>If that succeeds, <ulink
url="https://www.NetBSD.org/cgi-bin/sendpr.cgi?gndb=netbsd">file a bug
report</ulink> against the pkgsrc package, including the exact error
message and the contents of your &mk.conf; file.</para>
</sect3>
<sect3 id="fixes.build.header.symlink">
<title>Symlinks</title>
<para>Pkgsrc does not work reliably if any of
<varname>LOCALBASE</varname>, <varname>VARBASE</varname> or
<varname>WRKDIR</varname> contains a symlink. Since 2019Q2, the pkgsrc
bootstrap program prevents installing pkgsrc in symlink-based
directories. Existing pkgsrc installations are not checked for symlinks
though.</para>
<para>The "No such file or directory" error messages are a typical
symptom of symlinks, and it's quite difficult to find out that this is
the actual cause.</para>
</sect3>
<sect3 id="fixes.build.header.stale">
<title>Stale working directories</title>
<para>When building a hierarchy of packages, it may happen that one
package is built and then pkgsrc is updated. This situation can provoke
various hard to diagnose build errors. To clean up the situation:</para>
<programlisting>
&uprompt; (cd ../../ && test -f mk/bsd.pkg.mk && rm -rf */*/work)
</programlisting>
<para>(The test for <filename>bsd.pkg.mk</filename> just prevents running
this command in the wrong directory.)</para>
<para>If you have set <varname>WRKOBJDIR</varname> in &mk.conf;, remove
that directory as well.</para>
</sect3>
<sect3 id="fixes.build.header.misc">
<title>Other possible reasons</title>
<para>On platforms other than BSD, third-party packages are installed in
<filename>/usr/include</filename>, together with the base system. This
means that pkgsrc cannot distinguish between headers provided by the base
system (which it needs) and headers from third-party packages (which are
often included in pkgsrc as well). This can lead to subtle version
mismatches.</para>
<para>In pkgsrc installations that have been active for several years, it
may happen that some files are manually deleted. To exclude this unlikely
reason, run <command>pkg_admin check</command>.</para>
<para>It may help to run <command>pkg_admin rebuild-tree</command> to
check/fix dependencies.</para>
<para>If all of the above doesn't help, see <xref linkend="help-user"/>
for contact information. Be prepared to describe what you have tried so
far and what any error messages were.</para>
</sect3>
</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 any combination of
<quote>cputime</quote>, <quote>datasize</quote>,
<quote>memorysize</quote>, and <quote>stacksize</quote>.
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>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>.
Other useful variables are: <varname>GAMEDIR_PERMS</varname>,
<varname>GAMEDATA_PERMS</varname> and
<varname>SETGID_GAMES_PERMS</varname>.</para>
<para>An example that illustrates some of the variables described above is
<filename>games/moon-buggy</filename>. <varname>OWN_DIRS_PERMS</varname> is
used to properly set directory permissions of the directory where the
scorefile is saved, <varname>REQD_FILES_PERMS</varname> is used to create a
dummy scorefile (<filename>mbscore</filename>) with the proper permissions
and <varname>SPECIAL_PERMS</varname> is used to install setgid the game
binary:</para>
<programlisting>
USE_GAMESGROUP= yes
BUILD_DEFS+= VARBASE
OWN_DIRS_PERMS+= ${VARBASE}/games/moon-buggy ${GAMEDIR_PERMS}
REQD_FILES_PERMS+= /dev/null ${VARBASE}/games/moon-buggy/mbscore ${GAMEDATA_PERMS}
SPECIAL_PERMS+= ${PREFIX}/bin/moon-buggy ${SETGID_GAMES_PERMS}
</programlisting>
<para>Various <varname>INSTALL_*</varname> variables are also available:
<varname>INSTALL_GAME</varname> to install setgid game binaries,
<varname>INSTALL_GAME_DIR</varname> to install game directories that are
needed to be accessed by setgid games and
<varname>INSTALL_GAME_DATA</varname> to install scorefiles.</para>
<para>A package should therefore never hard code file ownership or
access permissions but rely on <varname>*_PERMS</varname> as described above
or alternatively on <varname>INSTALL_GAME</varname>,
<varname>INSTALL_GAME_DATA</varname> and
<varname>INSTALL_GAME_DIR</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>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>PKG_FAIL_REASON</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>