0688b82cb6
This keeps the font size on mobile devices more consistent by splitting long preformatted lines. Also, replace some http URLs with their https counterparts.
2104 lines
82 KiB
XML
2104 lines
82 KiB
XML
<!-- $NetBSD: fixes.xml,v 1.150 2020/01/19 14:12:27 rillig 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>BUILD_DEPENDS</varname> and
|
|
<varname>DEPENDS</varname> and
|
|
<varname>TOOL_DEPENDS</varname> definitions, the
|
|
<varname>USE_TOOLS</varname> definition, as well as dependencies
|
|
via <filename>buildlink3.mk</filename>, which is the preferred way
|
|
to handle dependencies, and which uses the variables named above.
|
|
See <xref linkend="buildlink"/> for more information.</para>
|
|
|
|
<para>The basic difference between the two variables is as
|
|
follows: The <varname>DEPENDS</varname> definition registers
|
|
that pre-requisite in the binary package so it will be pulled in
|
|
when the binary package is later installed, whilst the
|
|
<varname>BUILD_DEPENDS</varname> and <varname>TOOL_DEPENDS</varname>
|
|
definitions does not, marking a dependency that is only needed for
|
|
building the package.</para>
|
|
|
|
<para>This means that if you only need a package present whilst
|
|
you are building, it should be noted as a
|
|
<varname>TOOL_DEPENDS</varname> or
|
|
<varname>BUILD_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 <varname>BUILD_DEPENDS</varname>,
|
|
<varname>DEPENDS</varname> and <varname>TOOL_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>You can use wildcards in package dependencies. Note that
|
|
such wildcard dependencies are retained when creating binary
|
|
packages. The dependency is checked when installing the binary
|
|
package and any package which matches the pattern will be
|
|
used. Wildcard dependencies should be used with care.</para>
|
|
|
|
<para>The <quote>-[0-9]*</quote> should be used instead of
|
|
<quote>-*</quote> to avoid potentially ambiguous matches
|
|
such as <quote>tk-postgresql</quote> matching a
|
|
<quote>tk-*</quote> <varname>DEPENDS</varname>.</para>
|
|
|
|
<para>Wildcards can also be used to specify that a package
|
|
will only build against a certain minimum version of a
|
|
pre-requisite:</para>
|
|
|
|
<programlisting>
|
|
DEPENDS+= ImageMagick>=6.0:../../graphics/ImageMagick
|
|
</programlisting>
|
|
|
|
<para>This means that the package will build using version 6.0
|
|
of ImageMagick or newer. Such a dependency may be warranted
|
|
if, for example, the command line options of an executable
|
|
have changed.</para>
|
|
|
|
<para>If you need to depend on minimum versions of libraries,
|
|
see the buildlink section of the pkgsrc guide.</para>
|
|
|
|
<para>For security fixes, please update the package
|
|
vulnerabilities file. See <xref
|
|
linkend="security-handling"/> for more
|
|
information.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>If your package needs files from another package to build,
|
|
add the relevant distribution files to
|
|
<varname>DISTFILES</varname>, so they will be extracted
|
|
automatically. See the <filename
|
|
role="pkg">print/ghostscript</filename> package for an example.
|
|
(It relies on the jpeg sources being present in source form
|
|
during the build.)</para>
|
|
</sect2>
|
|
|
|
|
|
<sect2 id="conflicts">
|
|
<title>Handling conflicts with other packages</title>
|
|
|
|
<para>Your package may conflict with other packages a user might
|
|
already have installed on his system, e.g. if your package
|
|
installs the same set of files as another package in the pkgsrc
|
|
tree 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 when the replacement text varies, patches alone cannot help.
|
|
This is where the SUBST framework comes in. It provides an
|
|
easy-to-use interface for replacing text in files.
|
|
Example:</para>
|
|
|
|
<programlisting>
|
|
SUBST_CLASSES+= fix-paths
|
|
SUBST_STAGE.fix-paths= pre-configure
|
|
SUBST_MESSAGE.fix-paths= Fixing absolute paths.
|
|
SUBST_FILES.fix-paths= src/*.c
|
|
SUBST_FILES.fix-paths+= scripts/*.sh
|
|
SUBST_SED.fix-paths= -e 's,"/usr/local,"${PREFIX},g'
|
|
SUBST_SED.fix-paths+= -e 's,"/var/log,"${VARBASE}/log,g'
|
|
</programlisting>
|
|
|
|
<para><varname>SUBST_CLASSES</varname> is a list of identifiers
|
|
that are used to identify the different SUBST blocks that are
|
|
defined. The SUBST framework is heavily used by pkgsrc, so it is
|
|
important to always use the <literal>+=</literal> operator with
|
|
this variable. Otherwise some substitutions may be
|
|
skipped.</para>
|
|
|
|
<para>The remaining variables of each SUBST block are
|
|
parameterized with the identifier from the first line
|
|
(<literal>fix-paths</literal> in this case.) They can be seen as
|
|
parameters to a function call.</para>
|
|
|
|
<para><varname>SUBST_STAGE.*</varname> specifies the stage at
|
|
which the replacement will take place. All combinations of
|
|
<literal>pre-</literal>, <literal>do-</literal> and
|
|
<literal>post-</literal> together with a phase name are
|
|
possible, though only few are actually used. Most commonly used
|
|
are <literal>post-patch</literal> and
|
|
<literal>pre-configure</literal>. Of these two,
|
|
<literal>pre-configure</literal> should be preferred because
|
|
then it is possible to run <command>bmake patch</command> and
|
|
have the state after applying the patches but before making any
|
|
other changes. This is especially useful when you are debugging
|
|
a package in order to create new patches for it. Similarly,
|
|
<literal>post-build</literal> is preferred over
|
|
<literal>pre-install</literal>, because the install phase should
|
|
generally be kept as simple as possible. When you use
|
|
<literal>post-build</literal>, you have the same files in the
|
|
working directory that will be installed later, so you can check
|
|
if the substitution has succeeded.</para>
|
|
|
|
<para><varname>SUBST_MESSAGE.*</varname> is an optional text
|
|
that is printed just before the substitution is done.</para>
|
|
|
|
<para><varname>SUBST_FILES.*</varname> is the list of shell
|
|
globbing patterns that specifies the files in which the
|
|
substitution will take place. The patterns are interpreted
|
|
relatively to the <varname>WRKSRC</varname> directory.</para>
|
|
|
|
<para><varname>SUBST_SED.*</varname> is a list of arguments to
|
|
&man.sed.1; that specify the actual substitution. Every sed
|
|
command should be prefixed with <literal>-e</literal>, so that
|
|
all SUBST blocks look uniform.</para>
|
|
|
|
<para>There are some more variables, but they are so seldomly
|
|
used that they are only documented in the
|
|
<filename>mk/subst.mk</filename> file.</para>
|
|
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="fixes.fetch">
|
|
<title>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>http://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>http://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>http://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="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>
|