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 (the lines in Makefile 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 target: dependencies) the variables are expanded at load time.

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

A package can set the INTERACTIVE_STAGE variable to define which stages need interaction. This should be done in the package's Makefile, e.g.:

INTERACTIVE_STAGE=      configure install

The user can then decide to skip this package by setting the BATCH variable. Packages that require interaction are also excluded from bulk builds.

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

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 ACCEPTABLE_LICENSES variable in mk.conf. Note that this variable only affects which packages may be built, while the license terms often also restrict the actual use of the package and its redistribution.

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 pkgsrc user can override the default by setting the ACCEPTABLE_LICENSES variable with "=" instead of "+=". The licenses accepted by default are defined in the DEFAULT_ACCEPTABLE_LICENSES variable in the file pkgsrc/mk/license.mk.

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:

% make
===> 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

In case a package requires multiple licenses, you can add all of them to the LICENSE variable, connected with the upper-case keyword AND. If the user has a choice between multiple licenses, you can add them connected with the upper-case keyword OR, for example:

LICENSE=        isc AND apache-2.0
LICENSE=        2-clause-bsd OR ruby-license

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

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.

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.

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.

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

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.

Your package may depend on some other package being present, and there are various ways of expressing this dependency. pkgsrc supports the DEPENDS, BUILD_DEPENDS, TOOL_DEPENDS, and TEST_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 18, Buildlink methodology for more information.

The basic difference is that 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, TOOL_DEPENDS, and TEST_DEPENDS definitions do not, marking a dependency that is only needed for building or testing the resulting package. See also Chapter 14, Creating a new pkgsrc package from scratch for more information.

This means that if you only need a package present whilst you are building or testing, it should be noted as a TOOL_DEPENDS, BUILD_DEPENDS, or TEST_DEPENDS. When cross-compiling, TOOL_DEPENDS are native packages, i.e. packages for the architecture where the package is built; BUILD_DEPENDS are target packages, i.e., packages for the architecture for which the package is built.

The format for a DEPENDS, BUILD_DEPENDS, TOOL_DEPENDS, and TEST_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 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.)

Your package may conflict with other packages users might already have installed on their system, e.g., if your package installs the same set of files as another package in the pkgsrc tree.

For example, x11/libXaw3d and x11/Xaw-Xpm install the same shared library, thus you set in pkgsrc/x11/libXaw3d/Makefile:

CONFLICTS=      Xaw-Xpm-[0-9]*

and in pkgsrc/x11/Xaw-Xpm/Makefile:

CONFLICTS=      libXaw3d-[0-9]*

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.

To avoid these issues CONFLICTS entries should be added in all cases where it is known that packages conflict with each other. These CONFLICTS entries are exported in pkg_summary(5) files and consumed by binary package managers to inform users that packages cannot be installed onto the target system.

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

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.

When a vulnerability is found, this should be noted in pkgsrc/doc/pkg-vulnerabilities. Entries in that file consist of three parts:

For the package version pattern please always use `<' to mark an upper bound (not `<='!). This will avoid possible problems due unrelated PKGREVISION bumps not related to security fixes. Lower bounds can be added too, using '>' or '>='. For example, “foo>=1<1.2” would mark versions 1.0 (included) to 1.2 (excluded) of “foo” as affected by the security issue.

Entries should always be added at the bottom of the file.

When fixing packages, please modify the upper bound of the corresponding entry. To continue the previous example, if a fix was backported to version 1.1nb2, change the previous pattern to “foo>=1<1.1nb2”.

To locally test a package version pattern against a PKGNAME you can use the pkg_admin pmatch command.

The URL should be as permanent as possible and provide as much information about the issue as possible. CVE entries are preferred.

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.

In case a security issue is disputed, please contact pkgsrc-security@NetBSD.org.

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:

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

PKGREVISION must also be incremented when dependencies have ABI changes.

When you want to replace the same text in multiple files, or multiple times in the same file, it is cumbersome to maintain a patch file for this. This is where the SUBST framework steps in. It provides an easy-to-use interface for replacing text in files. It just needs the following information:

This information is encoded in a block of SUBST variables. A minimal example is:

SUBST_CLASSES+=         paths
SUBST_STAGE.paths=      pre-configure
SUBST_FILES.paths=      src/*.c
SUBST_SED.paths=        -e 's,/usr/local,${PREFIX},g'

Translated into English, it means: In the pre-configure stage (that is, after applying the patches from the patches/ directory and before running the configure script and the portability check), replace the text /usr/local with the content of the variable PREFIX.

Each SUBST block starts by appending an identifier to SUBST_CLASSES (note the +=). This identifier can be chosen freely by the package. If there should ever be duplicate identifiers, the pkgsrc infrastructure will catch this and fail early, so don't worry about name collisions.

Except for SUBST_CLASSES, all variables in a SUBST block are parameterized using this identifier. In the remainder of this section, these parameterized variables are written as SUBST_STAGE.*.

SUBST_CLASSES+=         paths
SUBST_STAGE.paths=      pre-configure
SUBST_MESSAGE.paths=    Fixing absolute paths.
SUBST_FILES.paths=      src/*.c
SUBST_FILES.paths+=     scripts/*.sh
SUBST_SED.paths=        -e 's,"/usr/local,"${PREFIX},g'
SUBST_SED.paths+=       -e 's,"/var/log,"${VARBASE}/log,g'
SUBST_VARS.paths=       LOCALBASE PREFIX PKGVERSION

To get a complete picture about the SUBST substitutions, run bmake show-all-subst. If something doesn't work as expected, run pkglint on the package, which detects several typical mistakes surrounding the SUBST blocks. For any questions that might remain after this, have a look at mk/subst.mk.

SUBST_FILES.path=       Makefile */Makefile */*/Makefile *.[ch]

C_FILES_CMD=            cd ${WRKSRC} && ${FIND} . -name '*.c'
SUBST_FILES.path=       ${C_FILES_CMD:sh}

SUBST_SED.path=         -e 's|/usr/local|${PREFIX}|g'

SUBST_VARS.path=        PREFIX

SUBST_FILTER_CMD.path=  LC_ALL=C ${TR} -d '\r'

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:

FETCH_MESSAGE=  "Please download the files"
FETCH_MESSAGE+= "    "${DISTFILES:Q}
FETCH_MESSAGE+= "manually from "${MASTER_SITES:Q}"."

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 (but take care with python or ruby packages, where PKGNAME includes a variable prefix). All DISTFILES and PATCHFILES for this package will be put in that subdirectory of the local distfiles directory. (See Section 21.1.10, “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.

Helper methods exist for packages hosted on github.com which will often have distfile names that clash with other packages, for example 1.0.tar.gz. Use one of the three recipes from below:

DISTNAME=       example-1.0
MASTER_SITES=   ${MASTER_SITE_GITHUB:=username/}
#GITHUB_PROJECT= example    # can be omitted if same as DISTNAME
GITHUB_TAG=     v${PKGVERSION_NOREV}
EXTRACT_SUFX=   .zip

DISTNAME=       example-0.0.0.347
MASTER_SITES=   ${MASTER_SITE_GITHUB:=username/}
#GITHUB_PROJECT= example    # can be omitted if same as DISTNAME
GITHUB_TAG=     988881adc9fc3655077dc2d4d757d480b5ea0e11

# git clone https://github.com/username/example
# cd example
# git describe --tags
1.2.3-5-g988881a

DISTNAME=       example-1.2.3.5
MASTER_SITES=   ${MASTER_SITE_GITHUB:=username/}
#GITHUB_PROJECT= example    # can be omitted if same as DISTNAME
GITHUB_TAG=     988881adc9fc3655077dc2d4d757d480b5ea0e11

DISTNAME=       offensive-1.6
PKGNAME=        ${DISTNAME:S/offensive/proper/}
MASTER_SITES=   ${MASTER_SITE_GITHUB:=username/}
GITHUB_PROJECT= example
GITHUB_RELEASE= rel-${PKGVERSION_NOREV} # usually just set this to ${DISTNAME}
EXTRACT_SUFX=   .zip

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

If a package needs GNU autoconf or automake to be executed to regenerate the configure script and Makefile.in makefile templates from configure.ac and Makefile.am, then they should be executed in a pre-configure target:

USE_TOOLS+=	autoconf automake autoreconf
GNU_CONFIGURE=	yes
...

pre-configure:
        set -e; cd ${WRKSRC} && autoreconf -fi
...

Packages which use GNU Automake will sometimes require GNU Make (gmake in USE_TOOLS), but not always. Note that autoreconf only needs to be executed if configure.ac or Makefiles are modified, or configure is not present.

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.

Packages using Meson to configure need to include:

.include "../../devel/meson/build.mk"

In nearly all cases (any program with dependencies), pkg-config needs to be added to USE_TOOLS. If the package installs translation files for non-English languages, also add msgfmt and xgettext:

USE_TOOLS+=	pkg-config msgfmt xgettext

If any options need to be passed to Meson, use MESON_ARGS instead of CONFIGURE_ARGS:

MESON_ARGS+=	-Dx11=false

To determine the endianness of the target platform, have a look at mk/endian.mk.

Compilers for the C and C++ languages come 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 18, Buildlink methodology).

To declare which languages should be made available through pkgsrc's compiler wrappers, use the USE_LANGUAGES variable. Allowed values currently are:

c, c++, fortran, fortran77, java, objc, obj-c++, and ada.

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

To declare which features a package requires from the compiler, set either USE_CC_FEATURES or USE_CXX_FEATURES. Allowed values for USE_CC_FEATURES are currently:

c11, c99, has_include

Allowed values for USE_CXX_FEATURES are currently:

c++11, c++14, c++17, c++20, has_include, regex, filesystem,
charconv, parallelism_ts, unique_ptr, put_time,
is_trivially_copy_constructible

Note at present these variables only affect use of GCC, not other compilers.

Language variants like gnu99 and c++11 can be specified in FORCE_C_STD and FORCE_CXX_STD if the package does not explicitly set -std=... when compiling (i.e. the package assumes the compiler defaults to C++11 or some other standard). This is a common bug in upstream build systems.

Allowed values for FORCE_C_STD are currently:

c90, c99, c11, gnu90, gnu99, gnu11

Allowed values for FORCE_CXX_STD are currently:

c++03, c++11, c++14, c++17, c++20,
gnu++03, gnu++11, gnu++14, gnu++17, gnu++20

Note at present these variables only affect use of GCC and Clang.

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:

If a program is written in Go and has any dependencies on other Go modules, have the package include ../../lang/go/go-module.mk.

If a program is written in Rust and uses Cargo to build, have the package include ../../lang/rust/cargo.mk.

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

See Section 21.6.6, “Packages installing Perl modules” for information about handling Perl modules.

There is also the REPLACE_PERL6 variable for the language now known as Raku.

REPLACE_SH, REPLACE_BASH, REPLACE_CSH, and REPLACE_KSH can be used to replace shell she-bangs in files. Please use the appropriate one, preferring REPLACE_SH when 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.

There are further similar REPLACE variables available, e.g., REPLACE_AWK for packages containing awk scripts, and REPLACE_R for R. These two, like the others noted above, have their actions defined centrally in mk/configure/replace-interpreter.mk. Other languages define the actions of these variables within their own dedicated part of the tree, e.g., REPLACE_PHP is actioned in lang/php/replace.mk, and REPLACE_PYTHON is actioned in lang/python/application.mk. For other languages, consult the mk files found within their specific directories (the naming convention varies), or check the list found in Appendix E, Help topics.

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

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.

#ifdef __NetBSD__
#include <sys/param.h>
#if __NetBSD_Prereq__(9,99,17)
/* use a newer feature */
#else
/* older code */
#endif
#endif

#ifndef _WIN32
/* Unix-like specific code */
#endif

#include <sys/param.h>
#if (defined(BSD) && BSD >= 199306)
/* BSD-specific code goes here */
#else
/* non-BSD-specific code goes here */
#endif

Cygwin      __CYGWIN__
DragonFly   __DragonFly__
FreeBSD     __FreeBSD__
Haiku       __HAIKU__
IRIX        __sgi (TODO: get a definite source for this)
Linux       __linux
Mac OS X    __APPLE__
Minix3      __minix
NetBSD      __NetBSD__
OpenBSD     __OpenBSD__
Solaris     sun, __sun

i386        i386, __i386, __i386__
x86-64      __amd64__, __x86_64__
ARM         __arm__
MIPS        __mips
SPARC       sparc, __sparc
PowerPC     __powerpc

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)

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.

Compilation sometimes fails with an error message like this:

.../x11/gtk3/work/gtk+-3.24.12/gdk/gdktypes.h:35:10:
    fatal error: pango/pango.h: No such file or directory

The proper way to fix this problem depends on the type of the header, which is described in the following sections.

$ find work/.buildlink/ -print | grep -F pango/pango.h

work/.buildlink/include/pango-1.0/pango/pango.h

$ $ grep -o '[-]I[^[:space:]]*/pango[^[:space:]]*' work/*/Makefile
-I/usr/pkg/include/pango-1.0
-I/usr/pkg/include/pango-1.0
-I/usr/pkg/include/pango-1.0
-I/usr/pkg/include/pango-1.0
-I/usr/pkg/include/pango-1.0

  usr   MAKE_JOBS=              7
  pkg   MAKE_JOBS_SAFE          # undefined
  def   _MAKE_JOBS_N=           7

MAKE_JOBS_SAFE=no bmake clean build

$ (cd ../../ && cat mk/bsd.pkg.mk >/dev/null && rm -rf */*/work)

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.

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

extern int extern_func(int);

static inline int
inline_func(int x)
{
        return extern_func(x);
}

int main(void)
{
        return 0;
}

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. The allowed values are any combination of “cputime”, “datasize”, “memorysize”, “stacksize” and “virtualsize”. 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.

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

Instead of running the install commands directly, you can also append “dir1 dir2” to the INSTALLATION_DIRS variable, which will automatically do the right thing.

In general, documentation should be installed into ${PREFIX}/share/doc/${PKGBASE} or ${PREFIX}/share/doc/${PKGNAME_NOREV} (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. In pkgsrc, the HTML documentation should go into the package-specific directory, just like any other documentation.

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

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. Other useful variables are: GAMEDIR_PERMS, GAMEDATA_PERMS and SETGID_GAMES_PERMS.

An example that illustrates some of the variables described above is games/moon-buggy. OWN_DIRS_PERMS is used to properly set directory permissions of the directory where the scorefile is saved, REQD_FILES_PERMS is used to create a dummy scorefile (mbscore) with the proper permissions and SPECIAL_PERMS is used to install setgid the game binary:

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}

Various INSTALL_* variables are also available: INSTALL_GAME to install setgid game binaries, INSTALL_GAME_DIR to install game directories that are needed to be accessed by setgid games and INSTALL_GAME_DATA to install scorefiles.

A package should therefore never hard code file ownership or access permissions but rely on *_PERMS as described above or alternatively on INSTALL_GAME, INSTALL_GAME_DATA and INSTALL_GAME_DIR to set these correctly.

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”).

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

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

Some packages, usually those providing libraries, install pkg-config files so that their headers and libraries can easily be found. The file names end with .pc.

Most of the time, these files only provide the linker flags for the library, but do not include the flags for setting the rpath so the libraries can also be found at runtime. Since this is so common, pkgsrc provides PKGCONFIG_OVERRIDE for this. Many packages generate the .pc from .pc.in, in that case add those files to the PKGCONFIG_OVERRIDE variable:

PKGCONFIG_OVERRIDE+=   foo.pc.in
    

For packages using meson, the files are generated during build and you also need to change the phase in which the replacement is done. For example:

PKGCONFIG_OVERRIDE+=            output/meson-private/foo.pc
PKGCONFIG_OVERRIDE_STAGE=       post-build
    

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.

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

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.

See Section 19.5, “Man page compression” for information on installation of compressed manual pages.

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.

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:

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:

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.

If a package contains an rc.d script, it won't be copied into the startup directory (/etc/rc.d) by default, but you can enable copying by setting the option PKG_RCD_SCRIPTS=YES in mk.conf. With PKG_RCD_SCRIPTS=YES, rc.d scripts will be copied into /etc/rc.d when a package is installed, but only if the target does not already exist. Copies in /etc/rc.d will be automatically removed only if they have not been modified.

Note that this alone does not enable the service: It must still be added to /etc/rc.conf.

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

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 pkgtools/rpm2pkg helps in extracting and packaging Linux rpm packages.

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.

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:

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.

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:

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