4a08198baa
dependency of the package changes. I still have problems with some packages that depend on GConf2, which doesn't exist anymore. The dependency has silently changed to GConf, without increasing any PKGREVISION. Same for gnome-vfs2 and gnome-vfs.
1921 lines
75 KiB
XML
1921 lines
75 KiB
XML
<!-- $NetBSD: fixes.xml,v 1.92 2008/01/23 13:46:21 rillig Exp $ -->
|
|
|
|
<chapter id="fixes"> <?dbhtml filename="fixes.html"?>
|
|
<title>Making your package work</title>
|
|
|
|
<sect1 id="general-operation">
|
|
<title>General operation</title>
|
|
|
|
<sect2 id="portability-of-packages">
|
|
<title>Portability of packages</title>
|
|
|
|
<para>One appealing feature of pkgsrc is that it runs on many
|
|
different platforms. As a result, it is important to ensure,
|
|
where possible, that packages in pkgsrc are portable. This
|
|
chapter mentions some particular details you should pay
|
|
attention to while working on pkgsrc.</para>
|
|
</sect2>
|
|
|
|
<sect2 id="pulling-vars-from-etc-mk.conf">
|
|
<title>How to pull in user-settable variables from &mk.conf;</title>
|
|
|
|
<para>The pkgsrc user can configure pkgsrc by overriding several
|
|
variables in the file pointed to by <varname>MAKECONF</varname>,
|
|
which is &mk.conf; by default. When you
|
|
want to use those variables in the preprocessor directives of
|
|
&man.make.1; (for example <literal>.if</literal> or
|
|
<literal>.for</literal>), you need to include the file
|
|
<filename>../../mk/bsd.prefs.mk</filename> before, which in turn
|
|
loads the user preferences.</para>
|
|
|
|
<para>But note that some variables may not be completely defined
|
|
after <filename>../../mk/bsd.prefs.mk</filename> has been
|
|
included, as they may contain references to variables that are
|
|
not yet defined. In shell commands this is no problem, since
|
|
variables are actually macros, which are only expanded when they
|
|
are used. But in the preprocessor directives mentioned above and
|
|
in dependency lines (of the form <literal>target:
|
|
dependencies</literal>) the variables are expanded at load
|
|
time.</para>
|
|
|
|
<note><para>Currently there is no exhaustive list of all
|
|
variables that tells you whether they can be used at load time
|
|
or only at run time, but it is in preparation.</para></note>
|
|
</sect2>
|
|
|
|
<sect2 id="user-interaction">
|
|
<title>User interaction</title>
|
|
|
|
<para>Occasionally, packages require interaction from the user,
|
|
and this can be in a number of ways:</para>
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
<para>When fetching the distfiles, some packages require user
|
|
interaction such as entering username/password or accepting a
|
|
license on a web page.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>When extracting the distfiles, some packages may ask for
|
|
passwords.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>help to configure the package before it is built</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>help during the build process</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>help during the installation of a package</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>The <varname>INTERACTIVE_STAGE</varname> definition is
|
|
provided to notify the pkgsrc mechanism of an interactive stage
|
|
which will be needed, and this should be set in the package's
|
|
<filename>Makefile</filename>, e.g.:</para>
|
|
|
|
<programlisting>
|
|
INTERACTIVE_STAGE= build
|
|
</programlisting>
|
|
|
|
<para>Multiple interactive stages can be specified:</para>
|
|
|
|
<programlisting>
|
|
INTERACTIVE_STAGE= configure install
|
|
</programlisting>
|
|
|
|
<para>The user can then decide to skip this package by setting the
|
|
<varname>BATCH</varname> variable.</para>
|
|
</sect2>
|
|
|
|
<sect2 id="handling-licenses">
|
|
<title>Handling licenses</title>
|
|
|
|
<para>Authors of software can choose the licence under which
|
|
software can be copied. This is due to copyright law, and reasons
|
|
for license choices are outside the scope of pkgsrc. The pkgsrc
|
|
system recognizes that there are a number of licenses which some
|
|
users may find objectionable or difficult or impossible to comply
|
|
with. The Free Software Foundation has declared some licenses
|
|
"Free", and the Open Source Initiative has a definition of "Open
|
|
Source". The pkgsrc system, as a policy choice, does not label
|
|
packages which have licenses that are Free or Open Source.
|
|
However, packages without a license meeting either of those tests
|
|
are labeled with a license tag denoting the license. Note that a
|
|
package with no license to copy trivially does not meet either the
|
|
Free or Open Source test.</para>
|
|
|
|
<para>For packages which are not Free or Open Source, pkgsrc will
|
|
not build the package unless the user has indicated to pkgsrc that
|
|
packages with that particular license may be built. Note that
|
|
this documentation avoids the term "accepted the license". The
|
|
pkgsrc system is merely providing a mechanism to avoid
|
|
accidentally building a package with a non-free license;
|
|
judgement and responsibility remain with the user. (Installation
|
|
of binary packages are not currently subject to this mechanism;
|
|
this is a bug.)</para>
|
|
|
|
<para>One might want to only install packages with a BSD license,
|
|
or the GPL, and not the other. The pkgsrc license tag mechanism
|
|
does not provide a way to do this. It might be possible to put in
|
|
tags for free licenses, and have a default
|
|
<varname>ACCEPTABLE_LICENSES</varname> variable value, but this is
|
|
widely viewed as having a very poor ratio of benefit to
|
|
work.</para>
|
|
|
|
<para>The license tag mechanism is intended to address
|
|
copyright-related issues surrounding building, installing and
|
|
using a package, and not to address redistribution issues (see
|
|
<varname>RESTRICTED</varname> and
|
|
<varname>NO_SRC_ON_FTP</varname>, etc.). However, the above
|
|
definition of licenses for which tags are not needed implies
|
|
that packages with redistribution restrictions should have
|
|
tags, because Free or Open Source programs do not have
|
|
redistribution restrictions.</para>
|
|
|
|
<para>Denoting that a package may be copied according to a
|
|
particular license is done by placing the license in
|
|
<filename>pkgsrc/licenses</filename> and setting the
|
|
<varname>LICENSE</varname> variable to a string identifying the
|
|
license, e.g. in <filename
|
|
role="pkg">graphics/xv</filename>:</para>
|
|
|
|
<programlisting>
|
|
LICENSE= xv-license
|
|
</programlisting>
|
|
|
|
<para>When trying to build, the user will get a notice that the
|
|
package is covered by a license which has not been placed in the
|
|
<varname>ACCEPTABLE_LICENSES</varname> variable:</para>
|
|
|
|
<programlisting>
|
|
&cprompt; <userinput>make</userinput>
|
|
===> xv-3.10anb9 has an unacceptable license: xv-license.
|
|
===> To view the license, enter "/usr/bin/make show-license".
|
|
===> To indicate acceptance, add this line to your /etc/mk.conf:
|
|
===> ACCEPTABLE_LICENSES+=xv-license
|
|
*** Error code 1
|
|
</programlisting>
|
|
|
|
<para>The license can be viewed with <command>make
|
|
show-license</command>, and if the user so chooses, the line
|
|
printed above can be added to &mk.conf; to
|
|
convey to pkgsrc that it should not in the future fail because of
|
|
that license:</para>
|
|
|
|
<programlisting>
|
|
ACCEPTABLE_LICENSES+=xv-license
|
|
</programlisting>
|
|
|
|
<para>When adding a package with a new license, the license text
|
|
should be added to <filename>pkgsrc/licenses</filename> for
|
|
displaying. A list of known licenses can be seen in this
|
|
directory.</para>
|
|
|
|
<para>When the license changes (in a way other than formatting),
|
|
please make sure that the new license has a different name (e.g.,
|
|
append the version number if it exists, or the date). Just
|
|
because a user told pkgsrc to build programs under a previous
|
|
version of a license does not mean that pkgsrc should build
|
|
programs under the new licenses. The higher-level point is that
|
|
pkgsrc does not evaluate licenses for reasonableness; the only
|
|
test is a mechanistic test of whether a particular text has been
|
|
approved by either of two bodies.</para>
|
|
|
|
<para>The use of <varname>LICENSE=shareware</varname>,
|
|
<varname>LICENSE=no-commercial-use</varname>, and similar language
|
|
is deprecated because it does not crisply refer to a particular
|
|
license text. Another problem with such usage is that it does not
|
|
enable a user to tell pkgsrc to proceed for a single package
|
|
without also telling pkgsrc to proceed for all packages with that
|
|
tag.</para> </sect2>
|
|
|
|
<sect2 id="restricted-packages">
|
|
<title>Restricted packages</title>
|
|
|
|
<para>Some licenses restrict how software may be re-distributed.
|
|
Because a license tag is required unless the package is Free or
|
|
Open Source, all packages with restrictions should have license
|
|
tags. By declaring the restrictions, package tools can
|
|
automatically refrain from e.g. placing binary packages on FTP
|
|
sites.</para>
|
|
|
|
<para>There are four restrictions that may be encoded, which are
|
|
the cross product of sources (distfiles) and binaries not being
|
|
placed on FTP sites and CD-ROMs. Because this is rarely the exact
|
|
language in any license, and because non-Free licenses tend to be
|
|
different from each other, pkgsrc adopts a definition of FTP and
|
|
CD-ROM. Pkgsrc uses "FTP" to mean that the source or binary file
|
|
should not be made available over the Internet at no charge.
|
|
Pkgsrc uses "CD-ROM" to mean that the source or binary may not be
|
|
made available on some kind of media, together with other source
|
|
and binary packages, and which is sold for a distribution charge.
|
|
</para>
|
|
|
|
<para>In order to encode these restrictions, the package system
|
|
defines five make variables that can be set to note these
|
|
restrictions:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><varname>RESTRICTED</varname></para>
|
|
|
|
<para>This variable should be set whenever a restriction
|
|
exists (regardless of its kind). Set this variable to a
|
|
string containing the reason for the restriction. It should
|
|
be understood that those wanting to understand the restriction
|
|
will have to read the license, and perhaps seek advice of
|
|
counsel.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><varname>NO_BIN_ON_CDROM</varname></para>
|
|
|
|
<para>Binaries may not be placed on CD-ROM containing other
|
|
binary packages, for which a distribution charge may be made.
|
|
In this case, set this variable to
|
|
<varname>${RESTRICTED}</varname>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><varname>NO_BIN_ON_FTP</varname></para>
|
|
|
|
<para>Binaries may not made available on the Internet without
|
|
charge. In this case, set this variable to
|
|
<varname>${RESTRICTED}</varname>. If this variable is set,
|
|
binary packages will not be included on ftp.NetBSD.org.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><varname>NO_SRC_ON_CDROM</varname></para>
|
|
|
|
<para>Distfiles may not be placed on CD-ROM, together with
|
|
other distfiles, for which a fee may be charged. In this
|
|
case, set this variable to <varname>${RESTRICTED}</varname>.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><varname>NO_SRC_ON_FTP</varname></para>
|
|
|
|
<para>Distfiles may not made available via FTP at no charge.
|
|
In this case, set this variable to
|
|
<varname>${RESTRICTED}</varname>. If this variable is set,
|
|
the distfile(s) will not be mirrored on ftp.NetBSD.org.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Please note that the use of <varname>NO_PACKAGE</varname>,
|
|
<varname>IGNORE</varname>, <varname>NO_CDROM</varname>, or other
|
|
generic make variables to denote restrictions is deprecated,
|
|
because they unconditionally prevent users from generating
|
|
binary packages!</para>
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="dependencies">
|
|
<title>Handling dependencies</title>
|
|
|
|
<para>Your package may depend on some other package being present
|
|
- and there are various ways of expressing this dependency.
|
|
pkgsrc supports the <varname>BUILD_DEPENDS</varname> and
|
|
<varname>DEPENDS</varname> definitions, the
|
|
<varname>USE_TOOLS</varname> definition, as well as dependencies
|
|
via <filename>buildlink3.mk</filename>, which is the preferred way
|
|
to handle dependencies, and which uses the variables named above.
|
|
See <xref linkend="buildlink"/> for more information.</para>
|
|
|
|
<para>The basic difference between the two variables is as
|
|
follows: The <varname>DEPENDS</varname> definition registers
|
|
that pre-requisite in the binary package so it will be pulled in
|
|
when the binary package is later installed, whilst the
|
|
<varname>BUILD_DEPENDS</varname> definition does not, marking a
|
|
dependency that is only needed for building the package.</para>
|
|
|
|
<para>This means that if you only need a package present whilst
|
|
you are building, it should be noted as a
|
|
<varname>BUILD_DEPENDS</varname>.</para>
|
|
|
|
<para>The format for a <varname>BUILD_DEPENDS</varname> and a
|
|
<varname>DEPENDS</varname> definition is:</para>
|
|
|
|
<programlisting>
|
|
<pre-req-package-name>:../../<category>/<pre-req-package>
|
|
</programlisting>
|
|
|
|
<para>Please note that the <quote>pre-req-package-name</quote>
|
|
may include any of the wildcard version numbers recognized by
|
|
&man.pkg.info.1;.</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>If your package needs another package's binaries or
|
|
libraries to build or run, and if that package has a
|
|
<filename>buildlink3.mk</filename> file available, use it:</para>
|
|
|
|
<programlisting>
|
|
.include "../../graphics/jpeg/buildlink3.mk"
|
|
</programlisting>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If your package needs to use another package to build
|
|
itself and there is no <filename>buildlink3.mk</filename>
|
|
file available, use the <varname>BUILD_DEPENDS</varname>
|
|
definition:</para>
|
|
|
|
<programlisting>
|
|
BUILD_DEPENDS+= autoconf-2.13:../../devel/autoconf
|
|
</programlisting>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>If your package needs a library with which to link and
|
|
again there is no <filename>buildlink3.mk</filename> file
|
|
available, this is specified using the
|
|
<varname>DEPENDS</varname> definition. For example:</para>
|
|
|
|
<programlisting>
|
|
DEPENDS+= xpm-3.4j:../../graphics/xpm
|
|
</programlisting>
|
|
|
|
<para>You can also use wildcards in package dependencies:</para>
|
|
|
|
<programlisting>
|
|
DEPENDS+= xpm-[0-9]*:../../graphics/xpm
|
|
</programlisting>
|
|
|
|
<para>Note that such wildcard dependencies are retained when
|
|
creating binary packages. The dependency is checked when
|
|
installing the binary package and any package which matches
|
|
the pattern will be used. Wildcard dependencies should be
|
|
used with care.</para>
|
|
|
|
<para>The <quote>-[0-9]*</quote> should be used instead of
|
|
<quote>-*</quote> to avoid potentially ambiguous matches
|
|
such as <quote>tk-postgresql</quote> matching a
|
|
<quote>tk-*</quote> <varname>DEPENDS</varname>.</para>
|
|
|
|
<para>Wildcards can also be used to specify that a package
|
|
will only build against a certain minimum version of a
|
|
pre-requisite:</para>
|
|
|
|
<programlisting>
|
|
DEPENDS+= tiff>=3.5.4:../../graphics/tiff
|
|
</programlisting>
|
|
|
|
<para>This means that the package will build against version
|
|
3.5.4 of the tiff library or newer. Such a dependency may
|
|
be warranted if, for example, the API of the library has
|
|
changed with version 3.5.4 and a package would not compile
|
|
against an earlier version of tiff.</para>
|
|
|
|
<para>Please note that such dependencies should only be
|
|
updated if a package requires a newer pre-requisite, but
|
|
not to denote recommendations such as
|
|
ABI changes that do not prevent a package from building
|
|
correctly. Such recommendations can be expressed using
|
|
<varname>ABI_DEPENDS</varname>:</para>
|
|
|
|
<programlisting>
|
|
ABI_DEPENDS+= tiff>=3.6.1:../../graphics/tiff
|
|
</programlisting>
|
|
|
|
<para>In addition to the above <varname>DEPENDS</varname>
|
|
line, this denotes that while a package will build against
|
|
tiff>=3.5.4, at least version 3.6.1 is recommended.
|
|
<varname>ABI_DEPENDS</varname> entries will be turned into
|
|
dependencies unless explicitly ignored (in which case a
|
|
warning will be printed).</para>
|
|
|
|
<para>To ignore these ABI dependency recommendations and just
|
|
use the required <varname>DEPENDS</varname>, set
|
|
<varname>USE_ABI_DEPENDS=NO</varname>. This may make
|
|
it easier and faster to update packages built using pkgsrc,
|
|
since older compatible dependencies can continue to be
|
|
used. This is useful for people who watch their rebuilds
|
|
very carefully; it is not very good as a general-purpose
|
|
hammer. If you use it, you need to be mindful of possible
|
|
ABI changes, including those from the underlying OS.</para>
|
|
|
|
<para>Packages that are built with recommendations ignored
|
|
may not be uploaded to ftp.NetBSD.org by developers and
|
|
should not be used across different systems that may have
|
|
different versions of binary packages installed.</para>
|
|
|
|
<para>For security fixes, please update the package
|
|
vulnerabilities file. See <xref
|
|
linkend="security-handling"/> for more
|
|
information.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If your package needs some executable to be able to run
|
|
correctly and if there's no
|
|
<filename>buildlink3.mk</filename> file, this is specified
|
|
using the <varname>DEPENDS</varname> variable. The
|
|
<filename role="pkg">print/lyx</filename> package needs to
|
|
be able to execute the latex binary from the teTeX package
|
|
when it runs, and that is specified:</para>
|
|
|
|
<programlisting>
|
|
DEPENDS+= teTeX-[0-9]*:../../print/teTeX
|
|
</programlisting>
|
|
|
|
<para>The comment about wildcard dependencies from previous
|
|
paragraph applies here, too.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>If your package needs files from another package to build,
|
|
add the relevant distribution files to
|
|
<varname>DISTFILES</varname>, so they will be extracted
|
|
automatically. See the <filename
|
|
role="pkg">print/ghostscript</filename> package for an example.
|
|
(It relies on the jpeg sources being present in source form
|
|
during the build.)</para>
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="conflicts">
|
|
<title>Handling conflicts with other packages</title>
|
|
|
|
<para>Your package may conflict with other packages a user might
|
|
already have installed on his system, e.g. if your package
|
|
installs the same set of files as another package in the pkgsrc
|
|
tree.</para>
|
|
|
|
<para>In this case you can set <varname>CONFLICTS</varname> to a
|
|
space-separated list of packages (including version string) your
|
|
package conflicts with.</para>
|
|
|
|
<para>For example, <filename role="pkg">x11/Xaw3d</filename>
|
|
and <filename role="pkg">x11/Xaw-Xpm</filename>
|
|
install the same shared library, thus you set in
|
|
<filename>pkgsrc/x11/Xaw3d/Makefile</filename>:</para>
|
|
|
|
<programlisting>
|
|
CONFLICTS= Xaw-Xpm-[0-9]*
|
|
</programlisting>
|
|
|
|
<para>and in <filename>pkgsrc/x11/Xaw-Xpm/Makefile</filename>:</para>
|
|
|
|
<programlisting>
|
|
CONFLICTS= Xaw3d-[0-9]*
|
|
</programlisting>
|
|
|
|
<para>Packages will automatically conflict with other packages
|
|
with the name prefix and a different version
|
|
string. <quote>Xaw3d-1.5</quote> e.g. will automatically
|
|
conflict with the older version <quote>Xaw3d-1.3</quote>.</para>
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="not-building-packages">
|
|
<title>Packages that cannot or should not be built</title>
|
|
|
|
<para>There are several reasons why a package might be
|
|
instructed to not build under certain circumstances. If the
|
|
package builds and runs on most platforms, the exceptions
|
|
should be noted with <varname>NOT_FOR_PLATFORM</varname>. If
|
|
the package builds and runs on a small handful of platforms,
|
|
set <varname>ONLY_FOR_PLATFORM</varname> instead.
|
|
Both <varname>ONLY_FOR_PLATFORM</varname> and
|
|
<varname>NOT_FOR_PLATFORM</varname> are OS triples
|
|
(OS-version-platform) that can use glob-style
|
|
wildcards.</para>
|
|
<para>Some packages are tightly bound to a specific version of an
|
|
operating system, e.g. LKMs or <filename
|
|
role="pkg">sysutils/lsof</filename>. Such binary packages are not
|
|
backwards compatible with other versions of the OS, and should be
|
|
uploaded to a version specific directory on the FTP server. Mark
|
|
these packages by setting <varname>OSVERSION_SPECIFIC</varname> to
|
|
<quote>yes</quote>. This variable is not currently used by any of
|
|
the package system internals, but may be used in the
|
|
future.</para>
|
|
<para>If the package should be skipped (for example, because it
|
|
provides functionality already provided by the system), set
|
|
<varname>PKG_SKIP_REASON</varname> to a descriptive message. If
|
|
the package should fail because some preconditions are not met,
|
|
set <varname>PKG_FAIL_REASON</varname> to a descriptive
|
|
message.</para>
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="undeletable-packages">
|
|
<title>Packages which should not be deleted, once installed</title>
|
|
|
|
<para>To ensure that a package may not be deleted, once it has been
|
|
installed, the <varname>PKG_PRESERVE</varname> definition should
|
|
be set in the package Makefile. This will be carried into any
|
|
binary package that is made from this pkgsrc entry. A
|
|
<quote>preserved</quote> package will
|
|
not be deleted using &man.pkg.delete.1; unless the
|
|
<quote>-f</quote> option is used.</para>
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="security-handling">
|
|
<title>Handling packages with security problems</title>
|
|
|
|
<para>When a vulnerability is found, this should be noted in
|
|
<filename>localsrc/security/advisories/pkg-vulnerabilities</filename>,
|
|
and after committing that file, use <command>make upload</command>
|
|
in the same directory to update the file on ftp.NetBSD.org.</para>
|
|
|
|
<para>After fixing the vulnerability by a patch, its
|
|
<varname>PKGREVISION</varname> should be increased (this
|
|
is of course not necessary if the problem is fixed by using
|
|
a newer release of the software).</para>
|
|
|
|
<para>Also, if the fix should be applied to the stable pkgsrc
|
|
branch, be sure to submit a pullup request!</para>
|
|
|
|
<para>Binary packages already on ftp.NetBSD.org will be handled
|
|
semi-automatically by a weekly cron job.</para>
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="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>,
|
|
or comments in Makefile.</para></listitem><listitem><para>
|
|
Changing build variables if the resulting binary package is the same.</para></listitem><listitem><para>
|
|
Changing <filename>DESCR</filename>.</para></listitem><listitem><para>
|
|
Adding <varname>PKG_OPTIONS</varname> if the default options don't change.</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Examples of changes that do merit an increase to
|
|
<varname>PKGREVISION</varname> include:</para>
|
|
<itemizedlist><listitem><para>
|
|
Security fixes</para></listitem><listitem><para>
|
|
Changes or additions to a patch file</para></listitem><listitem><para>
|
|
Changes to the <filename>PLIST</filename></para></listitem>
|
|
<listitem><para>A dependency is changed or renamed.</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>PKGREVISION must also be incremented when dependencies have ABI
|
|
changes.</para>
|
|
</sect2>
|
|
|
|
<sect2 id="fixes.subst">
|
|
<title>Substituting variable text in the package files (the SUBST framework)</title>
|
|
|
|
<para>When you want to replace the same text in multiple files
|
|
or when the replacement text varies, patches alone cannot help.
|
|
This is where the SUBST framework comes in. It provides an
|
|
easy-to-use interface for replacing text in files.
|
|
Example:</para>
|
|
|
|
<programlisting>
|
|
SUBST_CLASSES+= fix-paths
|
|
SUBST_STAGE.fix-paths= pre-configure
|
|
SUBST_MESSAGE.fix-paths= Fixing absolute paths.
|
|
SUBST_FILES.fix-paths= src/*.c
|
|
SUBST_FILES.fix-paths+= scripts/*.sh
|
|
SUBST_SED.fix-paths= -e 's,"/usr/local,"${PREFIX},g'
|
|
SUBST_SED.fix-paths+= -e 's,"/var/log,"${VARBASE}/log,g'
|
|
</programlisting>
|
|
|
|
<para><varname>SUBST_CLASSES</varname> is a list of identifiers
|
|
that are used to identify the different SUBST blocks that are
|
|
defined. The SUBST framework is heavily used by pkgsrc, so it is
|
|
important to always use the <literal>+=</literal> operator with
|
|
this variable. Otherwise some substitutions may be
|
|
skipped.</para>
|
|
|
|
<para>The remaining variables of each SUBST block are
|
|
parameterized with the identifier from the first line
|
|
(<literal>fix-paths</literal> in this case.) They can be seen as
|
|
parameters to a function call.</para>
|
|
|
|
<para><varname>SUBST_STAGE.*</varname> specifies the stage at
|
|
which the replacement will take place. All combinations of
|
|
<literal>pre-</literal>, <literal>do-</literal> and
|
|
<literal>post-</literal> together with a phase name are
|
|
possible, though only few are actually used. Most commonly used
|
|
are <literal>post-patch</literal> and
|
|
<literal>pre-configure</literal>. Of these two,
|
|
<literal>pre-configure</literal> should be preferred because
|
|
then it is possible to run <command>bmake patch</command> and
|
|
have the state after applying the patches but before making any
|
|
other changes. This is especially useful when you are debugging
|
|
a package in order to create new patches for it. Similarly,
|
|
<literal>post-build</literal> is preferred over
|
|
<literal>pre-install</literal>, because the install phase should
|
|
generally be kept as simple as possible. When you use
|
|
<literal>post-build</literal>, you have the same files in the
|
|
working directory that will be installed later, so you can check
|
|
if the substitution has succeeded.</para>
|
|
|
|
<para><varname>SUBST_MESSAGE.*</varname> is an optional text
|
|
that is printed just before the substitution is done.</para>
|
|
|
|
<para><varname>SUBST_FILES.*</varname> is the list of shell
|
|
globbing patterns that specifies the files in which the
|
|
substitution will take place. The patterns are interpreted
|
|
relatively to the <varname>WRKSRC</varname> directory.</para>
|
|
|
|
<para><varname>SUBST_SED.*</varname> is a list of arguments to
|
|
&man.sed.1; that specify the actual substitution. Every sed
|
|
command should be prefixed with <literal>-e</literal>, so that
|
|
all SUBST blocks look uniform.</para>
|
|
|
|
<para>There are some more variables, but they are so seldomly
|
|
used that they are only documented in the
|
|
<filename>mk/subst.mk</filename> file.</para>
|
|
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="fixes.fetch">
|
|
<title>Fixing problems in the <emphasis>fetch</emphasis> phase</title>
|
|
|
|
<sect2 id="no-plain-download">
|
|
<title>Packages whose distfiles aren't available for plain downloading</title>
|
|
|
|
<para>If you need to download from a dynamic URL you can set
|
|
<varname>DYNAMIC_MASTER_SITES</varname> and a <command>make
|
|
fetch</command> will call <filename>files/getsite.sh</filename>
|
|
with the name of each file to download as an argument, expecting
|
|
it to output the URL of the directory from which to download
|
|
it. <filename role="pkg">graphics/ns-cult3d</filename> is an
|
|
example of this usage.</para>
|
|
|
|
<para>If the download can't be automated, because the user must
|
|
submit personal information to apply for a password, or must pay
|
|
for the source, or whatever, you can set
|
|
<varname>FETCH_MESSAGE</varname> to a list of lines that are
|
|
displayed to the user before aborting the build. Example:</para>
|
|
|
|
<programlisting>
|
|
FETCH_MESSAGE= "Please download the files"
|
|
FETCH_MESSAGE+= " "${DISTFILES:Q}
|
|
FETCH_MESSAGE+= "manually from "${MASTER_SITES:Q}"."
|
|
</programlisting>
|
|
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="modified-distfiles-same-name">
|
|
<title>How to handle modified distfiles with the 'old' name</title>
|
|
|
|
<para>Sometimes authors of a software package make some
|
|
modifications after the software was released, and they put up a
|
|
new distfile without changing the package's version number. If a
|
|
package is already in pkgsrc at that time, the checksum will
|
|
no longer match. The contents of the new distfile should be
|
|
compared against the old one before changing anything, to make
|
|
sure the distfile was really updated on purpose, and that
|
|
no trojan horse or so crept in.
|
|
Please mention that the distfiles were compared and what was found
|
|
in your commit message.
|
|
Then, the correct way to work around this is to
|
|
set <varname>DIST_SUBDIR</varname> to a unique directory name,
|
|
usually based on <varname>PKGNAME_NOREV</varname>. All
|
|
<varname>DISTFILES</varname> and
|
|
<varname>PATCHFILES</varname> for this package will be put in that
|
|
subdirectory of the local distfiles directory.
|
|
(See <xref linkend="bumping-pkgrevision"/> for more details.)
|
|
In case this
|
|
happens more often, <varname>PKGNAME</varname> can be used (thus
|
|
including the <filename>nbX</filename> suffix) or a date stamp
|
|
can be appended, like <varname>${PKGNAME_NOREV}-YYYYMMDD</varname>.
|
|
Do not forget regenerating the <filename>distinfo</filename> file
|
|
after that, since it contains the <varname>DIST_SUBDIR</varname>
|
|
path in the filenames.
|
|
Also increase the PKGREVISION if the installed package is different.
|
|
Furthermore, a mail to the package's authors seems appropriate
|
|
telling them that changing distfiles after releases without
|
|
changing the file names is not good practice.</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="fixes.configure">
|
|
<title>Fixing problems in the <emphasis>configure</emphasis> phase</title>
|
|
|
|
<sect2 id="fixes.libtool">
|
|
<title>Shared libraries - libtool</title>
|
|
|
|
<para>pkgsrc supports many different machines, with different
|
|
object formats like a.out and ELF, and varying abilities to do
|
|
shared library and dynamic loading at all. To accompany this,
|
|
varying commands and options have to be passed to the
|
|
compiler, linker, etc. to get the Right Thing, which can be
|
|
pretty annoying especially if you don't have all the machines
|
|
at your hand to test things. The
|
|
<filename role="pkg">devel/libtool</filename> pkg
|
|
can help here, as it just <quote>knows</quote> how to build
|
|
both static and dynamic libraries from a set of source files,
|
|
thus being platform-independent.</para>
|
|
|
|
<para>Here's how to use libtool in a package in seven simple
|
|
steps:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Add <varname>USE_LIBTOOL=yes</varname> to the package
|
|
Makefile.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>For library objects, use <quote>${LIBTOOL} --mode=compile
|
|
${CC}</quote> in place of <quote>${CC}</quote>. You could even
|
|
add it to the definition of <varname>CC</varname>, if only
|
|
libraries are being built in a given Makefile. This one command
|
|
will build both PIC and non-PIC library objects, so you need not
|
|
have separate shared and non-shared library rules.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>For the linking of the library, remove any
|
|
<quote>ar</quote>, <quote>ranlib</quote>, and <quote>ld
|
|
-Bshareable</quote> commands, and instead use:</para>
|
|
|
|
<programlisting>
|
|
${LIBTOOL} --mode=link \
|
|
${CC} -o ${.TARGET:.a=.la} \
|
|
${OBJS:.o=.lo} \
|
|
-rpath ${PREFIX}/lib \
|
|
-version-info major:minor
|
|
</programlisting>
|
|
|
|
<para>Note that the library is changed to have a
|
|
<filename>.la</filename> extension, and the objects are
|
|
changed to have a <filename>.lo</filename>
|
|
extension. Change <varname>OBJS</varname> as
|
|
necessary. This automatically creates all of the
|
|
<filename>.a</filename>,
|
|
<filename>.so.major.minor</filename>, and ELF symlinks (if
|
|
necessary) in the build directory. Be sure to include
|
|
<quote>-version-info</quote>, especially when major and
|
|
minor are zero, as libtool will otherwise strip off the
|
|
shared library version.</para>
|
|
|
|
<para>From the libtool manual:</para>
|
|
|
|
<programlisting>
|
|
So, libtool library versions are described by three integers:
|
|
|
|
CURRENT
|
|
The most recent interface number that this library implements.
|
|
|
|
REVISION
|
|
The implementation number of the CURRENT interface.
|
|
|
|
AGE
|
|
The difference between the newest and oldest interfaces that
|
|
this library implements. In other words, the library implements
|
|
all the interface numbers in the range from number `CURRENT -
|
|
AGE' to `CURRENT'.
|
|
|
|
If two libraries have identical CURRENT and AGE numbers, then the
|
|
dynamic linker chooses the library with the greater REVISION number.
|
|
</programlisting>
|
|
|
|
<para>The <quote>-release</quote> option will produce
|
|
different results for a.out and ELF (excluding symlinks)
|
|
in only one case. An ELF library of the form
|
|
<quote>libfoo-release.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote>
|
|
will have a symlink of
|
|
<quote>libfoo.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote>
|
|
on an a.out platform. This is handled
|
|
automatically.</para>
|
|
|
|
<para>The <quote>-rpath argument</quote> is the install
|
|
directory of the library being built.</para>
|
|
|
|
<para>In the <filename>PLIST</filename>, include only the
|
|
<filename>.la</filename> file, the other files will be
|
|
added automatically.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>When linking shared object (<filename>.so</filename>)
|
|
files, i.e. files that are loaded via &man.dlopen.3;, NOT
|
|
shared libraries, use <quote>-module
|
|
-avoid-version</quote> to prevent them getting version
|
|
tacked on.</para>
|
|
|
|
<para>The <filename>PLIST</filename> file gets the
|
|
<filename>foo.so</filename> entry.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>When linking programs that depend on these libraries
|
|
<emphasis>before</emphasis> they are installed, preface
|
|
the &man.cc.1; or &man.ld.1; line with <quote>${LIBTOOL}
|
|
--mode=link</quote>, and it will find the correct
|
|
libraries (static or shared), but please be aware that
|
|
libtool will not allow you to specify a relative path in
|
|
-L (such as <quote>-L../somelib</quote>), because it
|
|
expects you to change that argument to be the
|
|
<filename>.la</filename> file. e.g.</para>
|
|
|
|
<programlisting>
|
|
${LIBTOOL} --mode=link ${CC} -o someprog -L../somelib -lsomelib
|
|
</programlisting>
|
|
|
|
<para>should be changed to:</para>
|
|
|
|
<programlisting>
|
|
${LIBTOOL} --mode=link ${CC} -o <replaceable>someprog</replaceable> <replaceable>../somelib/somelib.la</replaceable>
|
|
</programlisting>
|
|
|
|
<para>and it will do the right thing with the libraries.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>When installing libraries, preface the &man.install.1;
|
|
or &man.cp.1; command with <quote>${LIBTOOL}
|
|
--mode=install</quote>, and change the library name to
|
|
<filename>.la</filename>. e.g.</para>
|
|
|
|
<programlisting>
|
|
${LIBTOOL} --mode=install ${BSD_INSTALL_DATA} ${SOMELIB:.a=.la} ${PREFIX}/lib
|
|
</programlisting>
|
|
|
|
<para>This will install the static <filename>.a</filename>,
|
|
shared library, any needed symlinks, and run
|
|
&man.ldconfig.8;.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>In your <filename>PLIST</filename>, include only
|
|
the <filename>.la</filename>
|
|
file (this is a change from previous behaviour).</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="using-libtool">
|
|
<title>Using libtool on GNU packages that already support libtool</title>
|
|
|
|
<para>Add <varname>USE_LIBTOOL=yes</varname> to the
|
|
package Makefile. This will override the package's own libtool
|
|
in most cases. For older libtool using packages, libtool is
|
|
made by ltconfig script during the do-configure step; you can
|
|
check the libtool script location by doing <command>make
|
|
configure; find work*/ -name libtool</command>.</para>
|
|
|
|
<para><varname>LIBTOOL_OVERRIDE</varname> specifies which libtool
|
|
scripts, relative to <varname>WRKSRC</varname>, to override. By
|
|
default, it is set to <quote>libtool */libtool
|
|
*/*/libtool</quote>. If this does not match the location of the
|
|
package's libtool script(s), set it as appropriate.</para>
|
|
|
|
<para>If you do not need <filename>*.a</filename> static
|
|
libraries built and installed, then use
|
|
<varname>SHLIBTOOL_OVERRIDE</varname> instead.</para>
|
|
|
|
<para>If your package makes use of the platform-independent library
|
|
for loading dynamic shared objects, that comes with libtool
|
|
(libltdl), you should include devel/libltdl/buildlink3.mk.</para>
|
|
|
|
<para>Some packages use libtool incorrectly so that the package
|
|
may not work or build in some circumstances. Some of the more
|
|
common errors are:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The inclusion of a shared object (-module) as a dependent library in an
|
|
executable or library. This in itself isn't a problem if one of two things
|
|
has been done:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>The shared object is named correctly, i.e.
|
|
<filename>libfoo.la</filename>, not
|
|
<filename>foo.la</filename></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The -dlopen option is used when linking an executable.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The use of libltdl without the correct calls to initialisation routines.
|
|
The function lt_dlinit() should be called and the macro
|
|
<varname>LTDL_SET_PRELOADED_SYMBOLS</varname> included in
|
|
executables.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="autoconf-automake">
|
|
<title>GNU Autoconf/Automake</title>
|
|
|
|
<para>If a package needs GNU autoconf or automake to be executed
|
|
to regenerate the configure script and Makefile.in makefile
|
|
templates, then they should be executed in a pre-configure
|
|
target.</para>
|
|
|
|
<para>For packages that need only autoconf:</para>
|
|
|
|
<programlisting>
|
|
AUTOCONF_REQD= 2.50 # if default version is not good enough
|
|
USE_TOOLS+= autoconf # use "autoconf213" for autoconf-2.13
|
|
...
|
|
|
|
pre-configure:
|
|
cd ${WRKSRC} && autoconf
|
|
|
|
...
|
|
</programlisting>
|
|
|
|
<para>and for packages that need automake and autoconf:</para>
|
|
|
|
<programlisting>
|
|
AUTOMAKE_REQD= 1.7.1 # if default version is not good enough
|
|
USE_TOOLS+= automake # use "automake14" for automake-1.4
|
|
...
|
|
|
|
pre-configure:
|
|
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>
|
|
<!-- XXX: describe PKG_JVM_DEFAULT and PKG_JVMS_ACCEPTED, but
|
|
not here -->
|
|
</itemizedlist>
|
|
</sect2>
|
|
|
|
<sect2 id="perl-scripts">
|
|
<title>Packages containing perl scripts</title>
|
|
|
|
<para>If your package contains interpreted perl scripts, add
|
|
<quote>perl</quote> to the <varname>USE_TOOLS</varname> variable
|
|
and set <varname>REPLACE_PERL</varname> to ensure that the proper
|
|
interpreter path is set. <varname>REPLACE_PERL</varname> should
|
|
contain a list of scripts, relative to <varname>WRKSRC</varname>,
|
|
that you want adjusted. Every occurrence of
|
|
<filename>*/bin/perl</filename> will be replaced with the full
|
|
path to the perl executable.</para>
|
|
|
|
<para>If a particular version of perl is needed, set the
|
|
<varname>PERL5_REQD</varname> variable to the version number. The
|
|
default is <quote>5.0</quote>.</para>
|
|
|
|
<para>See <xref linkend="perl-modules" /> for information
|
|
about handling perl modules.</para>
|
|
</sect2>
|
|
|
|
<sect2 id="other-programming-languages">
|
|
<title>Other programming languages</title>
|
|
|
|
<para>Currently, there is no special handling for other languages
|
|
in pkgsrc. If a compiler package provides a
|
|
<filename>buildlink3.mk</filename> file, include that, otherwise
|
|
just add a (build) dependency on the appropriate compiler
|
|
package.</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="fixes.build">
|
|
<title>Fixing problems in the <emphasis>build</emphasis> phase</title>
|
|
|
|
<para>The most common failures when building a package are that
|
|
some platforms do not provide certain header files, functions or
|
|
libraries, or they provide the functions in a library that the
|
|
original package author didn't know. To work around this, you
|
|
can rewrite the source code in most cases so that it does not
|
|
use the missing functions or provides a replacement function.</para>
|
|
|
|
<sect2 id="fixes.build.cpp">
|
|
<title>Compiling C and C++ code conditionally</title>
|
|
|
|
<para>If a package already comes with a GNU configure script, the
|
|
preferred way to fix the build failure is to change the
|
|
configure script, not the code. In the other cases, you can
|
|
utilize the C preprocessor, which defines certain macros
|
|
depending on the operating system and hardware architecture it
|
|
compiles for. These macros can be queried using for example
|
|
<varname>#if defined(__i386)</varname>. Almost every operating
|
|
system, hardware architecture and compiler has its own macro.
|
|
For example, if the macros <varname>__GNUC__</varname>,
|
|
<varname>__i386__</varname> and <varname>__NetBSD__</varname>
|
|
are all defined, you know that you are using NetBSD on an i386
|
|
compatible CPU, and your compiler is GCC.</para>
|
|
|
|
<para>The list of the following macros for hardware and
|
|
operating system depends on the compiler that is used. For
|
|
example, if you want to conditionally compile code on Solaris,
|
|
don't use <varname>__sun__</varname>, as the SunPro compiler
|
|
does not define it. Use <varname>__sun</varname> instead.</para>
|
|
|
|
<sect3 id="fixes.build.cpp.os">
|
|
<title>C preprocessor macros to identify the operating system</title>
|
|
|
|
<para>To distinguish between 4.4 BSD-derived systems and the
|
|
rest of the world, you should use the following code.</para>
|
|
|
|
<programlisting>
|
|
#include <sys/param.h>
|
|
#if (defined(BSD) && BSD >= 199306)
|
|
/* BSD-specific code goes here */
|
|
#else
|
|
/* non-BSD-specific code goes here */
|
|
#endif
|
|
</programlisting>
|
|
|
|
<para>If this distinction is not fine enough, you can also test
|
|
for the following macros.</para>
|
|
|
|
<programlisting>
|
|
FreeBSD __FreeBSD__
|
|
DragonFly __DragonFly__
|
|
Interix __INTERIX
|
|
IRIX __sgi (TODO: get a definite source for this)
|
|
Linux linux, __linux, __linux__
|
|
NetBSD __NetBSD__
|
|
OpenBSD __OpenBSD__
|
|
Solaris sun, __sun
|
|
</programlisting>
|
|
|
|
</sect3>
|
|
<sect3 id="fixes.build.cpp.arch">
|
|
<title>C preprocessor macros to identify the hardware architecture</title>
|
|
|
|
<programlisting>
|
|
i386 i386, __i386, __i386__
|
|
MIPS __mips
|
|
SPARC sparc, __sparc
|
|
</programlisting>
|
|
|
|
</sect3>
|
|
<sect3 id="fixes.build.cpp.compiler">
|
|
<title>C preprocessor macros to identify the compiler</title>
|
|
|
|
<programlisting>
|
|
GCC __GNUC__ (major version), __GNUC_MINOR__
|
|
MIPSpro _COMPILER_VERSION (0x741 for MIPSpro 7.41)
|
|
SunPro __SUNPRO_C (0x570 for Sun C 5.7)
|
|
SunPro C++ __SUNPRO_CC (0x580 for Sun C++ 5.8)
|
|
</programlisting>
|
|
|
|
</sect3>
|
|
</sect2>
|
|
<sect2 id="compiler-bugs">
|
|
<title>How to handle compiler bugs</title>
|
|
|
|
<para>Some source files trigger bugs in the compiler, based on
|
|
combinations of compiler version and architecture and almost
|
|
always relation to optimisation being enabled. Common symptoms
|
|
are gcc internal errors or never finishing compiling a
|
|
file.</para>
|
|
|
|
<para>Typically, a workaround involves testing the
|
|
<varname>MACHINE_ARCH</varname> and compiler version, disabling
|
|
optimisation for that combination of file,
|
|
<varname>MACHINE_ARCH</varname> and compiler, and documenting it
|
|
in <filename>pkgsrc/doc/HACKS</filename>. See that file for a
|
|
number of examples.</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="undefined-reference">
|
|
<title>Undefined reference to <quote>...</quote></title>
|
|
|
|
<para>This error message often means that a package did not
|
|
link to a shared library it needs. The following functions are
|
|
known to cause this error message over and over.</para>
|
|
|
|
<informaltable id="undefined-reference-functions">
|
|
<tgroup cols="3">
|
|
<thead><row><entry>Function</entry><entry>Library</entry><entry>Affected platforms</entry></row></thead>
|
|
<tbody>
|
|
<row><entry>accept, bind, connect</entry><entry>-lsocket</entry><entry>Solaris</entry></row>
|
|
<row><entry>crypt</entry><entry>-lcrypt</entry><entry>DragonFly, NetBSD</entry></row>
|
|
<row><entry>dlopen, dlsym</entry><entry>-ldl</entry><entry>Linux</entry></row>
|
|
<row><entry>gethost*</entry><entry>-lnsl</entry><entry>Solaris</entry></row>
|
|
<row><entry>inet_aton</entry><entry>-lresolv</entry><entry>Solaris</entry></row>
|
|
<row><entry>nanosleep, sem_*, timer_*</entry><entry>-lrt</entry><entry>Solaris</entry></row>
|
|
<row><entry>openpty</entry><entry>-lutil</entry><entry>Linux</entry></row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>To fix these linker errors, it is often sufficient to say
|
|
<literal>LIBS.<replaceable>OperatingSystem</replaceable>+=
|
|
-l<replaceable>foo</replaceable></literal> to the package
|
|
<filename>Makefile</filename> and then say <command>bmake clean;
|
|
bmake</command>.</para>
|
|
|
|
<sect3 id="undefined-reference-sunpro">
|
|
<title>Special issue: The SunPro compiler</title>
|
|
|
|
<para>When you are using the SunPro compiler, there is another
|
|
possibility. That compiler cannot handle the following code:</para>
|
|
|
|
<programlisting>
|
|
extern int extern_func(int);
|
|
|
|
static inline int
|
|
inline_func(int x)
|
|
{
|
|
return extern_func(x);
|
|
}
|
|
|
|
int main(void)
|
|
{
|
|
return 0;
|
|
}
|
|
</programlisting>
|
|
|
|
<para>It generates the code for <function>inline_func</function> even if
|
|
that function is never used. This code then refers to
|
|
<function>extern_func</function>, which can usually not be resolved. To
|
|
solve this problem you can try to tell the package to disable inlining
|
|
of functions.</para>
|
|
|
|
</sect3>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="out-of-memory">
|
|
<title>Running out of memory</title>
|
|
|
|
<para>Sometimes packages fail to build because the compiler runs
|
|
into an operating system specific soft limit. With the
|
|
<varname>UNLIMIT_RESOURCES</varname> variable pkgsrc can be told
|
|
to unlimit the resources. Currently, the allowed values are
|
|
<quote>datasize</quote> and <quote>stacksize</quote> (or both).
|
|
Setting this variable is similar to running the shell builtin
|
|
<command>ulimit</command> command to raise the maximum data
|
|
segment size or maximum stack size of a process, respectively, to
|
|
their hard limits.</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="fixes.install">
|
|
<title>Fixing problems in the <emphasis>install</emphasis> phase</title>
|
|
|
|
<sect2 id="install-scripts">
|
|
<title>Creating needed directories</title>
|
|
|
|
<para>The BSD-compatible <command>install</command> supplied
|
|
with some operating systems cannot create more than one
|
|
directory at a time. As such, you should call
|
|
<literal>${INSTALL_*_DIR}</literal> like this:</para>
|
|
|
|
<programlisting>
|
|
${INSTALL_DATA_DIR} ${PREFIX}/dir1
|
|
${INSTALL_DATA_DIR} ${PREFIX}/dir2
|
|
</programlisting>
|
|
|
|
<para>You can also just append <quote><literal>dir1
|
|
dir2</literal></quote> to the
|
|
<varname>INSTALLATION_DIRS</varname> variable, which will
|
|
automatically do the right thing.</para>
|
|
|
|
</sect2>
|
|
<sect2 id="where-to-install-documentation">
|
|
<title>Where to install documentation</title>
|
|
|
|
<para>In general, documentation should be installed into
|
|
<filename>${PREFIX}/share/doc/${PKGBASE}</filename> or
|
|
<filename>${PREFIX}/share/doc/${PKGNAME}</filename> (the latter
|
|
includes the version number of the package).</para>
|
|
|
|
<para>Many modern packages using GNU autoconf allow to set the
|
|
directory where HTML documentation is installed with the
|
|
<quote>--with-html-dir</quote> option. Sometimes using this flag
|
|
is needed because otherwise the documentation ends up in
|
|
<filename>${PREFIX}/share/doc/html</filename> or other
|
|
places.</para>
|
|
|
|
<para>An exception to the above is that library API documentation
|
|
generated with the <filename
|
|
role="pkg">textproc/gtk-doc</filename> tools, for use by special
|
|
browsers (devhelp) should be left at their default location, which
|
|
is <filename>${PREFIX}/share/gtk-doc</filename>. Such
|
|
documentation can be recognized from files ending in
|
|
<filename>.devhelp</filename> or <filename>.devhelp2</filename>.
|
|
(It is also acceptable to install such files in
|
|
<filename>${PREFIX}/share/doc/${PKGBASE}</filename> or
|
|
<filename>${PREFIX}/share/doc/${PKGNAME}</filename>; the
|
|
<filename>.devhelp*</filename> file must be directly in that
|
|
directory then, no additional subdirectory level is allowed in
|
|
this case. This is usually achieved by using
|
|
<quote>--with-html-dir=${PREFIX}/share/doc</quote>.
|
|
<filename>${PREFIX}/share/gtk-doc</filename> is preferred
|
|
though.)</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="installing-score-files">
|
|
<title>Installing highscore files</title>
|
|
|
|
<para>Certain packages, most of them in the games category, install
|
|
a score file that allows all users on the system to record their
|
|
highscores. In order for this to work, the binaries need to be
|
|
installed setgid and the score files owned by the appropriate
|
|
group and/or owner (traditionally the "games" user/group). The
|
|
following variables, documented in more detail in
|
|
<filename>mk/defaults/mk.conf</filename>, control this
|
|
behaviour: <varname>SETGIDGAME</varname>,
|
|
<varname>GAMEDATAMODE</varname>, <varname>GAMEGRP</varname>,
|
|
<varname>GAMEMODE</varname>, <varname>GAMEOWN</varname>.</para>
|
|
|
|
<para>Note that per default, setgid installation of games is
|
|
disabled; setting <varname>SETGIDGAME=YES</varname> will set all
|
|
the other variables accordingly.</para>
|
|
|
|
<para>A package should therefor never hard code file ownership or
|
|
access permissions but rely on <varname>INSTALL_GAME</varname> and
|
|
<varname>INSTALL_GAME_DATA</varname> to set these
|
|
correctly.</para>
|
|
</sect2>
|
|
|
|
<sect2 id="destdir-support">
|
|
<title>Adding DESTDIR support to packages</title>
|
|
|
|
<itemizedlist>
|
|
<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
|
|
either use @owner/@group in the <filename>PLIST</filename>
|
|
(preferred) or use <varname>SPECIAL_PERMS</varname>
|
|
(discouraged). Note that @owner/@group are sticky during
|
|
install, keep this in mind.</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
|
|
paths to packlist files, e.g.:</para>
|
|
|
|
<programlisting>
|
|
PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist
|
|
</programlisting>
|
|
|
|
<para>The variables <varname>PERL5_SITELIB</varname>,
|
|
<varname>PERL5_SITEARCH</varname>, and
|
|
<varname>PERL5_ARCHLIB</varname> represent the three locations
|
|
in which perl5 modules may be installed, and may be used by
|
|
perl5 packages that don't have a packlist. These three
|
|
variables are also substituted for in the
|
|
<filename>PLIST</filename>.</para>
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="faq.info-files">
|
|
<title>Packages installing info files</title>
|
|
|
|
<para>Some packages install info files or use the
|
|
<quote>makeinfo</quote> or <quote>install-info</quote>
|
|
commands. <varname>INFO_FILES</varname> should be defined in
|
|
the package Makefile so that <filename>INSTALL</filename> and
|
|
<filename>DEINSTALL</filename> scripts will be generated to
|
|
handle registration of the info files in the Info directory
|
|
file. The <quote>install-info</quote> command used for the info
|
|
files registration is either provided by the system, or by a
|
|
special purpose package automatically added as dependency if
|
|
needed.</para>
|
|
|
|
<para><varname>PKGINFODIR</varname> is the directory under
|
|
<filename>${PREFIX}</filename> where info files are primarily
|
|
located. <varname>PKGINFODIR</varname> defaults to
|
|
<quote>info</quote> and can be overridden by the user.</para>
|
|
|
|
<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 data files</title>
|
|
|
|
<para>If a package installs <filename>.omf</filename> files, used by
|
|
scrollkeeper, you need to take some extra steps to make sure they
|
|
get registered in the database:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Include
|
|
<filename>../../textproc/scrollkeeper/omf.mk</filename>
|
|
instead of its <filename>buildlink3.mk</filename> file. This
|
|
takes care of rebuilding the scrollkeeper database at
|
|
installation and deinstallation time, and disallows any access
|
|
to it directly from the package.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Check the PLIST and remove any entries under the
|
|
<filename>libdata/scrollkeeper</filename> directory, as they
|
|
will be handled automatically.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Remove the <filename>share/omf</filename> directory from
|
|
the PLIST. It will be handled by scrollkeeper.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="x11-fonts">
|
|
<title>Packages installing X11 fonts</title>
|
|
|
|
<para>If a package installs font files, you will need to rebuild
|
|
the fonts database in the directory where they get installed at
|
|
installation and deinstallation time. This can be automatically
|
|
done by using the pkginstall framework.</para>
|
|
|
|
<para>You can list the directories where fonts are installed in the
|
|
<varname>FONTS_DIRS.<replaceable>type</replaceable></varname>
|
|
variables, where <replaceable>type</replaceable> can be one of
|
|
<quote>ttf</quote>, <quote>type1</quote> or <quote>x11</quote>.
|
|
Also make sure that the database file
|
|
<filename>fonts.dir</filename> is not listed in the PLIST.</para>
|
|
|
|
<para>Note that you should not create new directories for fonts;
|
|
instead use the standard ones to avoid that the user needs to
|
|
manually configure his X server to find them.</para>
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="gtk2-modules">
|
|
<title>Packages installing GTK2 modules</title>
|
|
|
|
<para>If a package installs GTK2 immodules or loaders, you need to
|
|
take some extra steps to get them registered in the GTK2 database
|
|
properly:</para>
|
|
|
|
<orderedlist>
|
|
<listitem><para>Include
|
|
<filename>../../x11/gtk2/modules.mk</filename> instead of its
|
|
<filename>buildlink3.mk</filename> file. This takes care of
|
|
rebuilding the database at installation and deinstallation time.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>Set <varname>GTK2_IMMODULES=YES</varname> if
|
|
your package installs GTK2 immodules.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>Set <varname>GTK2_LOADERS=YES</varname> if your package installs
|
|
GTK2 loaders.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>Patch the package to not touch any of the GTK2
|
|
databases directly. These are:</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 teTeX-texmf,
|
|
packages should install files
|
|
into <varname>PKG_LOCALTEXMFPREFIX</varname>,
|
|
not <varname>PKG_TEXMFPREFIX</varname>.</para></note>
|
|
|
|
<orderedlist>
|
|
<listitem><para>Include
|
|
<filename>../../print/teTeX/module.mk</filename> instead
|
|
of <filename>../../mk/tex.buildlink3.mk</filename>. This
|
|
takes care of rebuilding the <filename>ls-R</filename>
|
|
database at installation and deinstallation time.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>If your package installs files into a texmf
|
|
tree other than the one
|
|
at <varname>PKG_LOCALTEXMFPREFIX</varname>,
|
|
set <varname>TEXMFDIRS</varname> to the list of all texmf
|
|
trees that need database update.</para>
|
|
<para>If your package also installs font map files that need
|
|
to be registered using <command>updmap</command>,
|
|
set <varname>TEX_FONTMAPS</varname> to the list of all
|
|
such font map files. Then <command>updmap</command> will
|
|
be run automatically at installation/deinstallation to
|
|
enable/disable font map files for TeX output
|
|
drivers.</para>
|
|
</listitem>
|
|
|
|
<listitem><para>Make sure that none of <filename>ls-R</filename>
|
|
databases are included in <filename>PLIST</filename>, as
|
|
they will be removed only by the teTeX-bin package.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
|
|
<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, 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. There are currently two ways to declare that one knows
|
|
that a package has problems.</para>
|
|
<itemizedlist>
|
|
<listitem><para>The first way is to plainly mark it as broken. For
|
|
this, one just sets the variable <varname>BROKEN</varname> to the
|
|
reason why the package is broken (similar to the
|
|
<varname>RESTRICTED</varname> variable). A user trying to build
|
|
the package will immediately be shown this message, and the build
|
|
will not be even tried.</para></listitem>
|
|
|
|
<listitem><para>After each pkgsrc freeze period (a time when the
|
|
tree is stabilized and a new pkgsrc branch is cut), the packages
|
|
that were not building in the official branch build on the latest
|
|
NetBSD release will be marked as broken on that branch. This is
|
|
done by setting the <varname>BROKEN_IN</varname> variable to the
|
|
branch name (or appending the branch name to it). If a user tries
|
|
to build such a package and the build fails, the user gets a
|
|
message that says that the package was broken on the respective
|
|
branch(es).</para></listitem>
|
|
</itemizedlist>
|
|
<para>Both types of packages are removed from pkgsrc in irregular
|
|
intervals.</para>
|
|
</sect1>
|
|
|
|
</chapter>
|