bfb67ed7be
comments from rillig@.
2486 lines
96 KiB
XML
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>
|
|
<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 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} && ${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​/example​/example​/archive​/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​/username/exampleproject​/releases​/download​/rel-1.6​/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} && 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 <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>
|
|
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>
|