19.1. General operation

19.1.1. Portability of packages

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.

The pkgsrc user can configure pkgsrc by overriding several
variables in the file pointed to by MAKECONF,
which is mk.conf by default. When you
want to use those variables in the preprocessor directives of
make(1) (for example .if or
.for), you need to include the file
../../mk/bsd.prefs.mk before, which in turn
loads the user preferences.

But note that some variables may not be completely defined
after ../../mk/bsd.prefs.mk has been
included, as they may contain references to variables that are
not yet defined. In shell commands this is no problem, since
variables are actually macros, which are only expanded when they
are used. But in the preprocessor directives mentioned above and
in dependency lines (of the form target:
dependencies) the variables are expanded at load
time.

Note

Currently there is no exhaustive list of all
variables that tells you whether they can be used at load time
or only at run time, but it is in preparation.

19.1.3. User interaction

Occasionally, packages require interaction from the user,
and this can be in a number of ways:

When fetching the distfiles, some packages require user
interaction such as entering username/password or accepting a
license on a web page.

When extracting the distfiles, some packages may ask for
passwords.

help to configure the package before it is built

help during the build process

help during the installation of a package

The INTERACTIVE_STAGE definition is
provided to notify the pkgsrc mechanism of an interactive stage
which will be needed, and this should be set in the package's
Makefile, e.g.:

INTERACTIVE_STAGE= build

Multiple interactive stages can be specified:

INTERACTIVE_STAGE= configure install

The user can then decide to skip this package by setting the
BATCH variable.

19.1.4. Handling licenses

Authors of software can choose the licence under which
software can be copied. This is due to copyright law, and reasons
for license choices are outside the scope of pkgsrc. The pkgsrc
system recognizes that there are a number of licenses which some
users may find objectionable or difficult or impossible to comply
with. The Free Software Foundation has declared some licenses
"Free", and the Open Source Initiative has a definition of "Open
Source". The pkgsrc system, as a policy choice, does not label
packages which have licenses that are Free or Open Source.
However, packages without a license meeting either of those tests
are labeled with a license tag denoting the license. Note that a
package with no license to copy trivially does not meet either the
Free or Open Source test.

For packages which are not Free or Open Source, pkgsrc will
not build the package unless the user has indicated to pkgsrc that
packages with that particular license may be built. Note that
this documentation avoids the term "accepted the license". The
pkgsrc system is merely providing a mechanism to avoid
accidentally building a package with a non-free license;
judgement and responsibility remain with the user. (Installation
of binary packages are not currently subject to this mechanism;
this is a bug.)

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 ACCEPTABLE_LICENSES variable. The
user can override the default by setting the
ACCEPTABLE_LICENSES variable with "=" instead
of "+=". The licenses accepted by default are:

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
RESTRICTED and
NO_SRC_ON_FTP, etc.).
Packages with redistribution restrictions should set these
tags.

Denoting that a package may be copied according to a
particular license is done by placing the license in
pkgsrc/licenses and setting the
LICENSE variable to a string identifying the
license, e.g. in graphics/xv:

LICENSE= xv-license

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
ACCEPTABLE_LICENSES variable:

The license can be viewed with make
show-license, 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:

ACCEPTABLE_LICENSES+=xv-license

When adding a package with a new license, the following steps
are required:

default_acceptable_licenses in pkgsrc/pkgtools/pkg_install/files/lib/license.c

the ACCEPTABLE_LICENSES list in pkgsrc/doc/guide/files/fixes.xml

with the proper syntax as demonstrated in those files, respectively.

The license text should be added to pkgsrc/licenses for displaying. A list of known licenses can be seen in this directory.

When the license changes (in a way other than formatting),
please make sure that the new license has a different name (e.g.,
append the version number if it exists, or the date). Just
because a user told pkgsrc to build programs under a previous
version of a license does not mean that pkgsrc should build
programs under the new licenses. The higher-level point is that
pkgsrc does not evaluate licenses for reasonableness; the only
test is a mechanistic test of whether a particular text has been
approved by either of two bodies.

The use of LICENSE=shareware,
LICENSE=no-commercial-use, 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.

19.1.5. Restricted packages

Some licenses restrict how software may be re-distributed.
Because a license tag is required unless the package is Free or
Open Source, all packages with restrictions should have license
tags. By declaring the restrictions, package tools can
automatically refrain from e.g. placing binary packages on FTP
sites.

There are four restrictions that may be encoded, which are
the cross product of sources (distfiles) and binaries not being
placed on FTP sites and CD-ROMs. Because this is rarely the exact
language in any license, and because non-Free licenses tend to be
different from each other, pkgsrc adopts a definition of FTP and
CD-ROM. Pkgsrc uses "FTP" to mean that the source or binary file
should not be made available over the Internet at no charge.
Pkgsrc uses "CD-ROM" to mean that the source or binary may not be
made available on some kind of media, together with other source
and binary packages, and which is sold for a distribution charge.

In order to encode these restrictions, the package system
defines five make variables that can be set to note these
restrictions:

RESTRICTED

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.

NO_BIN_ON_CDROM

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
${RESTRICTED}.

NO_BIN_ON_FTP

Binaries may not made available on the Internet without
charge. In this case, set this variable to
${RESTRICTED}. If this variable is set,
binary packages will not be included on ftp.NetBSD.org.

NO_SRC_ON_CDROM

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 ${RESTRICTED}.

NO_SRC_ON_FTP

Distfiles may not made available via FTP at no charge.
In this case, set this variable to
${RESTRICTED}. If this variable is set,
the distfile(s) will not be mirrored on ftp.NetBSD.org.

Please note that packages will to 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.

19.1.6. Handling dependencies

Your package may depend on some other package being present
- and there are various ways of expressing this dependency.
pkgsrc supports the BUILD_DEPENDS and
DEPENDS definitions, the
USE_TOOLS definition, as well as dependencies
via buildlink3.mk, which is the preferred way
to handle dependencies, and which uses the variables named above.
See Chapter 14, Buildlink methodology for more information.

The basic difference between the two variables is as
follows: The DEPENDS definition registers
that pre-requisite in the binary package so it will be pulled in
when the binary package is later installed, whilst the
BUILD_DEPENDS definition does not, marking a
dependency that is only needed for building the package.

This means that if you only need a package present whilst
you are building, it should be noted as a
BUILD_DEPENDS.

The format for a BUILD_DEPENDS and a
DEPENDS definition is:

<pre-req-package-name>:../../<category>/<pre-req-package>

Please note that the “pre-req-package-name”
may include any of the wildcard version numbers recognized by
pkg_info(1).

If your package needs another package's binaries or
libraries to build and run, and if that package has a
buildlink3.mk file available, use it:

.include "../../graphics/jpeg/buildlink3.mk"

If your package needs another package's binaries or
libraries only for building, and if that package has a
buildlink3.mk file available, use it:

.include "../../graphics/jpeg/buildlink3.mk"

but set
BUILDLINK_DEPMETHOD.jpeg?=build
to make it a build dependency only. This case is rather
rare.

If your package needs binaries from another package to build,
use the BUILD_DEPENDS definition:

BUILD_DEPENDS+= scons-[0-9]*:../../devel/scons

If your package needs a library with which to link and
there is no buildlink3.mk file
available, create one. Using
DEPENDS won't be sufficient because the
include files and libraries will be hidden from the compiler.

If your package needs some executable to be able to run
correctly and if there's no
buildlink3.mk file, this is specified
using the DEPENDS variable. The
print/lyx package needs to
be able to execute the latex binary from the teTeX package
when it runs, and that is specified:

DEPENDS+= teTeX-[0-9]*:../../print/teTeX

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.

The “-[0-9]*” should be used instead of
“-*” to avoid potentially ambiguous matches
such as “tk-postgresql” matching a
“tk-*”DEPENDS.

Wildcards can also be used to specify that a package
will only build against a certain minimum version of a
pre-requisite:

DEPENDS+= ImageMagick>=6.0:../../graphics/ImageMagick

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.

If you need to depend on minimum versions of libraries,
see the buildlink section of the pkgsrc guide.

If the package depends on either one of two (or more)
packages, specify the “pre-req-package-name” as a
comma-separated list between curly braces.

As an example, take a package that depends on the Perl
“version” module, which has been part of Perl
itself since version 5.10.0. This either/or dependency is
expressed as:

DEPENDS+= {perl>=5.10.0,p5-version-[0-9]*}:../../devel/p5-version

If your package needs files from another package to build,
add the relevant distribution files to
DISTFILES, so they will be extracted
automatically. See the print/ghostscript package for an example.
(It relies on the jpeg sources being present in source form
during the build.)

19.1.7. Handling conflicts with other packages

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 PKGNAME.

These cases are handled automatically by the packaging tools
at package installation time and do not need to be handled
manually.

In case the conflicts can not be recognized automatically
(e.g., packages using the same config file location but no other
shared files), you can set CONFLICTS to a
space-separated list of packages (including version string) your
package conflicts with.

For example, if both foo/bar
and foo/baz
use the same config file, you would set in
foo/bar/Makefile:

CONFLICTS= baz-[0-9]*

and in pkgsrc/foo/baz/Makefile:

CONFLICTS= bar-[0-9]*

19.1.8. Packages that cannot or should not be built

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 BROKEN_ON_PLATFORM. If
the package builds and runs on a small handful of platforms,
set BROKEN_EXCEPT_ON_PLATFORM instead.
Both BROKEN_ON_PLATFORM and
BROKEN_EXCEPT_ON_PLATFORM are OS triples
(OS-version-platform) that can use glob-style
wildcards.

If a package is not appropriate for some platforms (as
oopposed 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 NOT_FOR_PLATFORM. If
the package is appropriate for only a small handful of platforms
(often exactly one), set ONLY_FOR_PLATFORM instead.
Both ONLY_FOR_PLATFORM and
NOT_FOR_PLATFORM are OS triples
(OS-version-platform) that can use glob-style
wildcards.

Some packages are tightly bound to a specific version of an
operating system, e.g. LKMs or sysutils/lsof. 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 OSVERSION_SPECIFIC to
“yes”. This variable is not currently used by any of
the package system internals, but may be used in the
future.

If the package should be skipped (for example, because it
provides functionality already provided by the system), set
PKG_SKIP_REASON to a descriptive message. If
the package should fail because some preconditions are not met,
set PKG_FAIL_REASON to a descriptive
message.

19.1.9. Packages which should not be deleted, once installed

To ensure that a package may not be deleted, once it has been
installed, the PKG_PRESERVE definition should
be set in the package Makefile. This will be carried into any
binary package that is made from this pkgsrc entry. A
“preserved” package will
not be deleted using pkg_delete(1) unless the
“-f” option is used.

19.1.10. Handling packages with security problems

When a vulnerability is found, this should be noted in
localsrc/security/advisories/pkg-vulnerabilities,
and after committing that file, ask pkgsrc-security@NetBSD.org to
update the file on ftp.NetBSD.org.

After fixing the vulnerability by a patch, its
PKGREVISION 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.

Also, if the fix should be applied to the stable pkgsrc
branch, be sure to submit a pullup request!

Binary packages already on ftp.NetBSD.org will be handled
semi-automatically by a weekly cron job.

19.1.11. How to handle incrementing versions when fixing an existing package

When making fixes to an existing package it can be useful
to change the version number in PKGNAME. To
avoid conflicting with future versions by the original author, a
“nb1”, “nb2”, ... suffix can be used
on package versions by setting PKGREVISION=1
(2, ...). The “nb” is treated like a
“.” by the package tools. e.g.

DISTNAME= foo-17.42
PKGREVISION= 9

will result in a PKGNAME of
“foo-17.42nb9”. If you want to use the original
value of PKGNAME without the “nbX”
suffix, e.g. for setting DIST_SUBDIR, use
PKGNAME_NOREV.

When a new release of the package is released, the
PKGREVISION should be removed, e.g. on a new
minor release of the above package, things should be like:

DISTNAME= foo-17.43

PKGREVISION should be incremented for any
non-trivial change in the resulting binary package. Without a
PKGREVISION bump, someone with the previous
version installed has no way of knowing that their package is out
of date. Thus, changes without increasing
PKGREVISION are essentially labeled "this is so
trivial that no reasonable person would want to upgrade", and this
is the rough test for when increasing
PKGREVISION is appropriate. Examples of
changes that do not merit increasing
PKGREVISION are:

Changing HOMEPAGE,
MAINTAINER, OWNER,
or comments in Makefile.

Changing build variables if the resulting binary package is the same.

Changing DESCR.

Adding PKG_OPTIONS if the default options don't change.

Examples of changes that do merit an increase to
PKGREVISION include:

Security fixes

Changes or additions to a patch file

Changes to the PLIST

A dependency is changed or renamed.

PKGREVISION must also be incremented when dependencies have ABI
changes.

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:

SUBST_CLASSES 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 += operator with
this variable. Otherwise some substitutions may be
skipped.

The remaining variables of each SUBST block are
parameterized with the identifier from the first line
(fix-paths in this case.) They can be seen as
parameters to a function call.

SUBST_STAGE.* specifies the stage at
which the replacement will take place. All combinations of
pre-, do- and
post- together with a phase name are
possible, though only few are actually used. Most commonly used
are post-patch and
pre-configure. Of these two,
pre-configure should be preferred because
then it is possible to run bmake patch 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,
post-build is preferred over
pre-install, because the install phase should
generally be kept as simple as possible. When you use
post-build, you have the same files in the
working directory that will be installed later, so you can check
if the substitution has succeeded.

SUBST_MESSAGE.* is an optional text
that is printed just before the substitution is done.

SUBST_FILES.* 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 WRKSRC directory.

SUBST_SED.* is a list of arguments to
sed(1) that specify the actual substitution. Every sed
command should be prefixed with -e, so that
all SUBST blocks look uniform.

There are some more variables, but they are so seldomly
used that they are only documented in the
mk/subst.mk file.

19.2. Fixing problems in the fetch phase

If you need to download from a dynamic URL you can set
DYNAMIC_MASTER_SITES and a make
fetch will call files/getsite.sh
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. graphics/ns-cult3d is an
example of this usage.

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
FETCH_MESSAGE to a list of lines that are
displayed to the user before aborting the build. Example:

19.2.2. How to handle modified distfiles with the 'old' name

Sometimes authors of a software package make some
modifications after the software was released, and they put up a
new distfile without changing the package's version number. If a
package is already in pkgsrc at that time, the checksum will
no longer match. The contents of the new distfile should be
compared against the old one before changing anything, to make
sure the distfile was really updated on purpose, and that
no trojan horse or so crept in.
Please mention that the distfiles were compared and what was found
in your commit message.

Then, the correct way to work around this is to
set DIST_SUBDIR to a unique directory name,
usually based on PKGNAME_NOREV. All
DISTFILES and
PATCHFILES for this package will be put in that
subdirectory of the local distfiles directory.
(See Section 19.1.11, “How to handle incrementing versions when fixing an existing package” for more details.)
In case this
happens more often, PKGNAME can be used (thus
including the nbX suffix) or a date stamp
can be appended, like ${PKGNAME_NOREV}-YYYYMMDD.

DIST_SUBDIR 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, DIST_SUBDIR might not be required. Additionally, DIST_SUBDIR must not be removed unless the distfile name changes, even if a package is being moved or renamed.

Do not forget regenerating the distinfo file
after that, since it contains the DIST_SUBDIR
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.

19.3. Fixing problems in the configure phase

19.3.1. Shared libraries - libtool

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
devel/libtool pkg
can help here, as it just “knows” how to build
both static and dynamic libraries from a set of source files,
thus being platform-independent.

Here's how to use libtool in a package in seven simple
steps:

Add USE_LIBTOOL=yes to the package
Makefile.

For library objects, use “${LIBTOOL} --mode=compile
${CC}” in place of “${CC}”. You could even
add it to the definition of CC, 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.

For the linking of the library, remove any
“ar”, “ranlib”, and “ld
-Bshareable” commands, and instead use:

Note that the library is changed to have a
.la extension, and the objects are
changed to have a .lo
extension. Change OBJS as
necessary. This automatically creates all of the
.a,
.so.major.minor, and ELF symlinks (if
necessary) in the build directory. Be sure to include
“-version-info”, especially when major and
minor are zero, as libtool will otherwise strip off the
shared library version.

From the libtool manual:

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.

The “-release” option will produce
different results for a.out and ELF (excluding symlinks)
in only one case. An ELF library of the form
“libfoo-release.so.x.y”
will have a symlink of
“libfoo.so.x.y”
on an a.out platform. This is handled
automatically.

The “-rpath argument” is the install
directory of the library being built.

In the PLIST, include only the
.la file, the other files will be
added automatically.

When linking shared object (.so)
files, i.e. files that are loaded via dlopen(3), NOT
shared libraries, use “-module
-avoid-version” to prevent them getting version
tacked on.

The PLIST file gets the
foo.so entry.

When linking programs that depend on these libraries
before they are installed, preface
the cc(1) or ld(1) line with “${LIBTOOL}
--mode=link”, 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 “-L../somelib”), because it
expects you to change that argument to be the
.la file. e.g.

${LIBTOOL} --mode=link ${CC} -o someprog -L../somelib -lsomelib

should be changed to:

${LIBTOOL} --mode=link ${CC} -o someprog../somelib/somelib.la

and it will do the right thing with the libraries.

When installing libraries, preface the install(1)
or cp(1) command with “${LIBTOOL}
--mode=install”, and change the library name to
.la. e.g.

This will install the static .a,
shared library, any needed symlinks, and run
ldconfig(8).

In your PLIST, include only
the .la
file (this is a change from previous behaviour).

19.3.2. Using libtool on GNU packages that already support libtool

Add USE_LIBTOOL=yes 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 make
configure; find work*/ -name libtool.

LIBTOOL_OVERRIDE specifies which libtool
scripts, relative to WRKSRC, to override. By
default, it is set to “libtool */libtool
*/*/libtool”. If this does not match the location of the
package's libtool script(s), set it as appropriate.

If you do not need *.a static
libraries built and installed, then use
SHLIBTOOL_OVERRIDE instead.

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.

Some packages use libtool incorrectly so that the package
may not work or build in some circumstances. Some of the more
common errors are:

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:

The shared object is named correctly, i.e.
libfoo.la, not
foo.la

The -dlopen option is used when linking an executable.

The use of libltdl without the correct calls to initialisation routines.
The function lt_dlinit() should be called and the macro
LTDL_SET_PRELOADED_SYMBOLS included in
executables.

19.3.3. GNU Autoconf/Automake

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.

Packages which use GNU Automake will almost certainly
require GNU Make.

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
AUTOMAKE_OVERRIDE=NO in the package
Makefile.

19.4. Programming languages

19.4.1. C, C++, and Fortran

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 Chapter 14, Buildlink methodology).

To declare which language's compiler a package needs, set
the USE_LANGUAGES variable. Allowed values
currently are “c”, “c++”, and
“fortran” (and any combination). The default is
“c”. Packages using GNU configure scripts, even if
written in C++, usually need a C compiler for the configure
phase.

19.4.2. Java

If a program is written in Java, use the Java framework in
pkgsrc. The package must include
../../mk/java-vm.mk. This Makefile fragment
provides the following variables:

USE_JAVA defines if a build
dependency on the JDK is added. If
USE_JAVA is set to “run”, then
there is only a runtime dependency on the JDK. The default is
“yes”, which also adds a build dependency on the
JDK.

Set USE_JAVA2 to declare that
a package needs a Java2 implementation. The supported values
are “yes”, “1.4”, and
“1.5”. “yes” accepts any Java2
implementation, “1.4” insists on versions 1.4 or
above, and “1.5” only accepts versions 1.5 or
above. This variable is not set by default.

PKG_JAVA_HOME is
automatically set to the runtime location of the used Java
implementation dependency. It may be used to set
JAVA_HOME to a good value if the program
needs this variable to be defined.

19.4.3. Packages containing perl scripts

If your package contains interpreted perl scripts, add
“perl” to the USE_TOOLS variable
and set REPLACE_PERL to ensure that the proper
interpreter path is set. REPLACE_PERL should
contain a list of scripts, relative to WRKSRC,
that you want adjusted. Every occurrence of
*/bin/perl in a she-bang line will be
replaced with the full path to the perl executable.

If a particular version of perl is needed, set the
PERL5_REQD variable to the version number. The
default is “5.0”.

19.4.4. Packages containing shell scripts

REPLACE_SH,
REPLACE_BASH, REPLACE_CSH,
and REPLACE_KSH can be used to replace shell
hash bangs in files. Please use the appropriate one, prefering
REPLACE_SH in case this shell is sufficient.
Each should contain a list of scripts, relative to
WRKSRC, 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 REPLACE_BASH, don't forget to add
bash to USE_TOOLS.

19.4.5. Other programming languages

Currently, there is no special handling for other languages
in pkgsrc. If a compiler package provides a
buildlink3.mk file, include that, otherwise
just add a (build) dependency on the appropriate compiler
package.

19.5. Fixing problems in the build phase

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.

19.5.1. Compiling C and C++ code conditionally

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
#if defined(__i386). Almost every operating
system, hardware architecture and compiler has its own macro.
For example, if the macros __GNUC__,
__i386__ and __NetBSD__
are all defined, you know that you are using NetBSD on an i386
compatible CPU, and your compiler is GCC.

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 __sun__, as the SunPro compiler
does not define it. Use __sun instead.

19.5.1.1. C preprocessor macros to identify the operating system

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

19.5.1.3. C preprocessor macros to identify the compiler

19.5.2. How to handle compiler bugs

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.

Typically, a workaround involves testing the
MACHINE_ARCH and compiler version, disabling
optimisation for that combination of file,
MACHINE_ARCH and compiler.

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
hacks.mk and describe the symptom and
compiler version as detailed as possible.

19.5.3. Undefined reference to “...”

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.

Function

Library

Affected platforms

accept, bind, connect

-lsocket

Solaris

crypt

-lcrypt

DragonFly, NetBSD

dlopen, dlsym

-ldl

Linux

gethost*

-lnsl

Solaris

inet_aton

-lresolv

Solaris

nanosleep, sem_*, timer_*

-lrt

Solaris

openpty

-lutil

Linux

To fix these linker errors, it is often sufficient to say
LIBS.OperatingSystem+=
-lfoo to the package
Makefile and then say bmake clean;
bmake.

19.5.3.1. Special issue: The SunPro compiler

When you are using the SunPro compiler, there is another
possibility. That compiler cannot handle the following code:

It generates the code for inline_func even if
that function is never used. This code then refers to
extern_func, which can usually not be resolved. To
solve this problem you can try to tell the package to disable inlining
of functions.

19.5.4. Running out of memory

Sometimes packages fail to build because the compiler runs
into an operating system specific soft limit. With the
UNLIMIT_RESOURCES variable pkgsrc can be told
to unlimit the resources. Currently, the allowed values are
“datasize” and “stacksize” (or both).
Setting this variable is similar to running the shell builtin
ulimit command to raise the maximum data
segment size or maximum stack size of a process, respectively, to
their hard limits.

19.6. Fixing problems in the install phase

19.6.1. Creating needed directories

The BSD-compatible install supplied
with some operating systems cannot create more than one
directory at a time. As such, you should call
${INSTALL_*_DIR} like this:

${INSTALL_DATA_DIR} ${PREFIX}/dir1
${INSTALL_DATA_DIR} ${PREFIX}/dir2

You can also just append “dir1
dir2” to the
INSTALLATION_DIRS variable, which will
automatically do the right thing.

19.6.2. Where to install documentation

In general, documentation should be installed into
${PREFIX}/share/doc/${PKGBASE} or
${PREFIX}/share/doc/${PKGNAME} (the latter
includes the version number of the package).

Many modern packages using GNU autoconf allow to set the
directory where HTML documentation is installed with the
“--with-html-dir” option. Sometimes using this flag
is needed because otherwise the documentation ends up in
${PREFIX}/share/doc/html or other
places.

An exception to the above is that library API documentation
generated with the textproc/gtk-doc tools, for use by special
browsers (devhelp) should be left at their default location, which
is ${PREFIX}/share/gtk-doc. Such
documentation can be recognized from files ending in
.devhelp or .devhelp2.
(It is also acceptable to install such files in
${PREFIX}/share/doc/${PKGBASE} or
${PREFIX}/share/doc/${PKGNAME}; the
.devhelp* file must be directly in that
directory then, no additional subdirectory level is allowed in
this case. This is usually achieved by using
“--with-html-dir=${PREFIX}/share/doc”.
${PREFIX}/share/gtk-doc is preferred
though.)

19.6.3. Installing highscore files

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
USE_GAMESGROUP to yes to support this. The
following variables, documented in more detail in
mk/defaults/mk.conf, control this
behaviour: GAMEDATAMODE,
GAMEDIRMODE, GAMES_GROUP,
GAMEMODE, GAME_USER.

A package should therefore never hard code file ownership or
access permissions but rely on INSTALL_GAME and
INSTALL_GAME_DATA to set these
correctly.

19.6.4. Adding DESTDIR support to packages

DESTDIR 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 (“destdir”) or the package can
install as non-root user (“user-destdir”).

PKG_DESTDIR_SUPPORT has to be
set to “none”, “destdir”, or
“user-destdir”. By default PKG_DESTDIR_SUPPORT
is set to “user-destdir” to help catching more
potential packaging problems. If bsd.prefs.mk is included in the Makefile,
PKG_DESTDIR_SUPPORT needs to be set before
the inclusion.

All installation operations have to be prefixed with
${DESTDIR}.

automake gets this DESTDIR mostly right
automatically. Many manual rules and pre/post-install often are
incorrect; fix them.

If files are installed with special owner/group
use SPECIAL_PERMS.

In general, packages should support
UNPRIVILEGED to be able to use
DESTDIR.

19.6.5. Packages with hardcoded paths to other interpreters

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 Makefile (we
shall use tclsh in this example):

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

Note

Before March 2006, these variables were called
_REPLACE.* and
_REPLACE_FILES.*.

19.6.6. Packages installing perl modules

Makefiles of packages providing perl5 modules should include
the Makefile fragment
../../lang/perl5/module.mk. It provides a
do-configure 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.

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
PLIST corresponding to the files listed in
the installed .packlist file generated by
most perl5 modules. This is invoked by defining
PERL5_PACKLIST to a space-separated list of
packlist files relative to PERL5_PACKLIST_DIR
(PERL5_INSTALLVENDORARCH by default),
e.g.:

PERL5_PACKLIST= auto/Pg/.packlist

The perl5 config variables
installarchlib,
installscript,
installvendorbin,
installvendorscript,
installvendorarch,
installvendorlib,
installvendorman1dir, and
installvendorman3dir represent those
locations in which components of perl5 modules may be installed,
provided as variable with uppercase and prefixed with
PERL5_, e.g. PERL5_INSTALLARCHLIB
and may be used by perl5 packages that don't have a packlist.
These variables are also substituted for in the
PLIST as uppercase prefixed with
PERL5_SUB_.

19.6.7. Packages installing info files

Some packages install info files or use the
“makeinfo” or “install-info”
commands. INFO_FILES should be defined in
the package Makefile so that INSTALL and
DEINSTALL scripts will be generated to
handle registration of the info files in the Info directory
file. The “install-info” 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.

PKGINFODIR is the directory under
${PREFIX} where info files are primarily
located. PKGINFODIR defaults to
“info” and can be overridden by the user.

The info files for the package should be listed in the
package PLIST; however any split info files
need not be listed.

A package which needs the “makeinfo” command
at build time must add “makeinfo” to
USE_TOOLS in its Makefile. If a minimum
version of the “makeinfo” command is needed it
should be noted with the TEXINFO_REQD
variable in the package Makefile. By
default, a minimum version of 3.12 is required. If the system
does not provide a makeinfo command or if it
does not match the required minimum, a build dependency on the
devel/gtexinfo package will
be added automatically.

The build and installation process of the software provided
by the package should not use the
install-info command as the registration of
info files is the task of the package
INSTALL script, and it must use the
appropriate makeinfo command.

To achieve this goal, the pkgsrc infrastructure creates
overriding scripts for the install-info and
makeinfo commands in a directory listed early
in PATH.

The script overriding install-info has
no effect except the logging of a message. The script overriding
makeinfo logs a message and according to the
value of TEXINFO_REQD either runs the appropriate
makeinfo command or exit on error.

19.6.8. Packages installing man pages

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
${PREFIX}/${PKGMANDIR}, and this expression
should be used in packages. The default for
PKGMANDIR is
“man”. Another often-used value
is “share/man”.

Note

The support for a custom PKGMANDIR
is far from complete.

The PLIST files can just use
man/ 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
PKGMANDIR must be used.

Packages that are
configured with GNU_CONFIGURE set as
“yes”, by default will use the
./configure
--mandir switch to set where the man pages should be installed.
The path is GNU_CONFIGURE_MANDIR which defaults
to ${PREFIX}/${PKGMANDIR}.

Packages that use GNU_CONFIGURE but do not
use --mandir, can set CONFIGURE_HAS_MANDIR
to “no”.
Or if the ./configure script uses
a non-standard use of --mandir, you can set
GNU_CONFIGURE_MANDIR as needed.

19.6.9. Packages installing GConf data files

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

Include ../../devel/GConf/schemas.mk
instead of its buildlink3.mk 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.

Ensure that the package installs its
.schemas files under
${PREFIX}/share/gconf/schemas. If they get
installed under ${PREFIX}/etc, you will
need to manually patch the package.

Define the GCONF_SCHEMAS variable in
your Makefile with a list of all
.schemas files installed by the package, if
any. Names must not contain any directories in them.

Define the GCONF_ENTRIES variable in
your Makefile with a
list of all .entries files installed by the
package, if any. Names must not contain any directories in
them.

19.6.10. Packages installing scrollkeeper/rarian data files

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

Include
../../mk/omf-scrollkeeper.mk
instead of rarian's buildlink3.mk file. This
takes care of rebuilding the scrollkeeper database at
installation and deinstallation time, and disallows any access
to it directly from the package.

Check the PLIST and remove any entries under the
libdata/scrollkeeper directory, as they
will be handled automatically.

Remove the share/omf directory from
the PLIST. It will be handled by rarian. (make
print-PLIST does this automatically.)

19.6.11. Packages installing X11 fonts

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.

You can list the directories where fonts are installed in the
FONTS_DIRS.type
variables, where type can be one of
“ttf”, “type1” or “x11”.
Also make sure that the database file
fonts.dir is not listed in the PLIST.

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.

19.6.12. Packages installing GTK2 modules

If a package installs GTK2 immodules or loaders, you need to
take some extra steps to get them registered in the GTK2 database
properly:

Include
../../x11/gtk2/modules.mk instead of its
buildlink3.mk file. This takes care of
rebuilding the database at installation and deinstallation time.

Set GTK2_IMMODULES=YES if
your package installs GTK2 immodules.

Set GTK2_LOADERS=YES if your package installs
GTK2 loaders.

Patch the package to not touch any of the GTK2
databases directly. These are:

libdata/gtk-2.0/gdk-pixbuf.loaders

libdata/gtk-2.0/gtk.immodules

Check the PLIST and remove
any entries under the libdata/gtk-2.0
directory, as they will be handled automatically.

19.6.13. Packages installing SGML or XML data

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:

Include
../../textproc/xmlcatmgr/catalogs.mk in
your Makefile, which takes care of
registering those files in system-wide catalogs at
installation and deinstallation time.

Set SGML_CATALOGS to the full path of
any SGML catalogs installed by the package.

Set XML_CATALOGS to the full path of
any XML catalogs installed by the package.

Set SGML_ENTRIES 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.

Set XML_ENTRIES 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.

19.6.14. Packages installing extensions to the MIME database

If a package provides extensions to the MIME database by
installing .xml files inside
${PREFIX}/share/mime/packages, you
need to take some extra steps to ensure that the database is kept
consistent with respect to these new files:

Include
../../databases/shared-mime-info/mimedb.mk
(avoid using the buildlink3.mk file from
this same directory, which is reserved for inclusion from
other buildlink3.mk files). It takes
care of rebuilding the MIME database at installation and
deinstallation time, and disallows any access to it directly
from the package.

Check the PLIST and remove any entries under the
share/mime directory,
except for files saved under
share/mime/packages. 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.

Remove any share/mime/* directories
from the PLIST. They will be handled by the shared-mime-info
package.

19.6.15. Packages using intltool

If a package uses intltool during its build, add
intltool to the USE_TOOLS,
which forces it to use the intltool package provided by pkgsrc,
instead of the one bundled with the distribution file.

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.

19.6.16. Packages installing startup scripts

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 PKG_RCD_SCRIPTS=YES in
mk.conf. This option will copy the scripts
into /etc/rc.d when a package is installed, and
it will automatically remove the scripts when the package is
deinstalled.

19.6.17. Packages installing TeX modules

If a package installs TeX packages into the texmf tree,
the ls-R database of the tree needs to be
updated.

Note

Except the main TeX packages such as kpathsea,
packages should install files
into ${PREFIX}/share/texmf-dist,
not ${PREFIX}/share/texmf.

Include
../../print/kpathsea/texmf.mk. This
takes care of rebuilding the ls-R
database at installation and deinstallation time.

If your package installs files into a texmf
tree other than the one
at ${PREFIX}/share/texmf-dist,
set TEX_TEXMF_DIRS to the list of all texmf
trees that need database update.

If your package also installs font map files that need
to be registered using updmap,
include ../../print/tex-tetex/map.mk and
set TEX_MAP_FILES and/or
TEX_MIXEDMAP_FILES to the list of all
such font map files. Then updmap will
be run automatically at installation/deinstallation to
enable/disable font map files for TeX output
drivers.

Make sure that none of ls-R
databases are included in PLIST, as
they will be removed only by the kpathsea package.

19.6.18. Packages supporting running binaries in
emulation

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.

The CHECK_SHLIBS can be set to no to
avoid the check-shlibs 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.

19.6.19. Packages installing hicolor theme icons

If a package installs images under the
share/icons/hicolor and/or updates the
share/icons/hicolor/icon-theme.cache
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:

Include
../../graphics/hicolor-icon-theme/buildlink3.mk.

Check the PLIST and remove the
entry that refers to the theme cache.

Ensure that the PLIST does not remove the shared icon
directories from the share/icons/hicolor
hierarchy because they will be handled automatically.

The best way to verify that the PLIST is correct with
respect to the last two points is to regenerate it using
make print-PLIST.

19.6.20. Packages installing desktop files

If a package installs .desktop files
under share/applications and these include
MIME information (MimeType key), you need to take extra steps to
ensure that they are registered into the MIME database:

Include
../../sysutils/desktop-file-utils/desktopdb.mk.

Check the PLIST and remove the entry that refers to the
share/applications/mimeinfo.cache file.
It will be handled automatically.

The best way to verify that the PLIST is correct with
respect to the last point is to regenerate it using make
print-PLIST.

19.7. Marking packages as having problems

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 BROKEN to the
reason why the package is broken (similar to the
RESTRICTED variable). A user trying to build
the package will immediately be shown this message, and the build
will not be even tried.