Chapter 6. Configuring pkgsrc

Table of Contents

6.1. General configuration
6.2. Variables affecting the build process
6.3. Preferences for native or pkgsrc software
6.4. Variables affecting the installation process
6.5. Selecting and configuring the compiler
6.5.1. Selecting the compiler
6.5.2. Additional flags to the compiler (CFLAGS)
6.5.3. Additional flags to the linker (LDFLAGS)
6.6. Developer/advanced settings
6.7. Selecting Build Options

The whole pkgsrc system is configured in a single file, usually called mk.conf. In which directory pkgsrc looks for that file depends on the installation. On NetBSD, when you use make(1) from the base system, it is in the directory /etc/. In all other cases the default location is ${PREFIX}/etc/, depending on where you told the bootstrap program to install the binary packages.

The format of the configuration file is that of the usual BSD-style Makefiles. The whole pkgsrc configuration is done by setting variables in this file. Note that you can define all kinds of variables, and no special error checking (for example for spelling mistakes) takes place.

6.1. General configuration

The following variables apply to all pkgsrc packages. A complete list of the variables that can be configured by the user is available in mk/defaults/mk.conf, together with some comments that describe each variable's intent.

  • LOCALBASE: Where packages will be installed. The default is /usr/pkg. Do not mix binary packages with different LOCALBASEs!

  • CROSSBASE: Where cross category packages will be installed. The default is ${LOCALBASE}/cross.

  • X11BASE: Where X11 is installed on the system. The default is /usr/X11R7.

  • DISTDIR: Where to store the downloaded copies of the original source distributions used for building pkgsrc packages. The default is ${PKGSRCDIR}/distfiles.

  • PKG_DBDIR: Where the database about installed packages is stored. The default is /usr/pkg/pkgdb.

  • MASTER_SITE_OVERRIDE: If set, override the packages' MASTER_SITES with this value.

  • MASTER_SITE_BACKUP: Backup location(s) for distribution files and patch files if not found locally or in ${MASTER_SITES} or ${PATCH_SITES} respectively. The defaults is${DIST_SUBDIR}/.

  • BINPKG_SITES: List of sites carrying binary pkgs. rel and arch are replaced with OS release (2.0, etc.) and architecture (mipsel, etc.).

  • ACCEPTABLE_LICENSES: List of acceptable licenses. License names are case-sensitive. Whenever you try to build a package whose license is not in this list, you will get an error message. If the license condition is simple enough, the error message will include specific instructions on how to change this variable.

6.2. Variables affecting the build process

  • PACKAGES: The top level directory for the binary packages. The default is ${PKGSRCDIR}/packages.

  • WRKOBJDIR: The top level directory where, if defined, the separate working directories will get created, and symbolically linked to from ${WRKDIR} (see below). This is useful for building packages on several architectures, then ${PKGSRCDIR} can be NFS-mounted while ${WRKOBJDIR} is local to every architecture. (It should be noted that PKGSRCDIR should not be set by the user — it is an internal definition which refers to the root of the pkgsrc tree. It is possible to have many pkgsrc tree instances.)

  • LOCALPATCHES: Directory for local patches that aren't part of pkgsrc. See Section 12.3, “patches/* for more information.

  • PKGMAKECONF: Location of the mk.conf file used by a package's BSD-style Makefile. If this is not set, MAKECONF is set to /dev/null to avoid picking up settings used by builds in /usr/src.

6.3. Preferences for native or pkgsrc software

Whenever a package depends on a package that has a file, the dependent package can either use the built-in (native) version from the base system or the pkgsrc-provided version. This only affects dependencies, so it is still possible to build the pkgsrc package devel/pcre++ even when other packages depend on the native pcre++ version instead.

To force using the pkgsrc-provided version for a particular package, define PREFER_PKGSRC = package-ID in mk.conf. To force using the native package, define PREFER_NATIVE = package-ID. In both cases, the package-ID is the one from the of the package. In most cases, this ID is the same as the directory name of the package, but for example, devel/pcre++ has the package ID pcrexx.

For the packages that are not listed by their package ID, pkgsrc uses the pkgsrc-provided version if PREFER_PKGSRC contains the word yes. Otherwise, if PREFER_NATIVE contains the word yes, pkgsrc uses the native version. For example, to require using the pkgsrc-provided versions for all but the most basic bits on a NetBSD system, you can set:

PREFER_NATIVE=  getopt skey tcp_wrappers

A package must have a file to be listed in PREFER_NATIVE, otherwise it is simply ignored in that list.

PREFER_PKGSRC and PREFER_NATIVE should be set during bootstrap to ensure that the bootstrap process does not use inapropriate native tools as dependencies for core packages.

# ./bootstrap --prefer-pkgsrc yes --prefer-native openssl

Switching between settings globally at a later date can introduce complications with dependency resolution. This is caused by packages built with the opposite preference being installed alongside each other. Hence, when changing any of these variables after bootstrap, you need to rebuild all packages depending on those whose preference has been changed. This is not trivial and should be avoided.

When using pkgsrc on Linux systems, there is high risk of leakage, where programs installed by pkgsrc may inadvertently use a command or library not installed by pkgsrc, e.g. those installed by yum or apt. Such foreign dependencies may be installed, removed, or upgraded to a version incompatible with the pkgsrc package at any time, causing pkgsrc packages to subsequently malfunction. Pkgsrc cannot prevent this, as it has no control over other package managers. Another potential problem is that under Redhat Enterprise and related Linux systems, yum packages are only patched and never upgraded, so eventually they may become too outdated for use by pkgsrc. Even intentionally using foreign dependencies, not considered leakage, can lead to these problems, so it is generally discouraged. In order to minimize such problems, PREFER_PKGSRC defaults to yes on Linux systems. This ensures that pkgsrc is aware of any changes to dependency packages and can rebuild or upgrade the entire dependency tree as needed. This default can be overridden by setting --prefer-pkgsrc to a list of packages and --prefer-native to yes.

6.4. Variables affecting the installation process

  • PKGSRC_KEEP_BIN_PKGS: By default, binary packages of built packages are preserved in ${PACKAGES}/All. Setting this variable to "no" prevents this.

Packages have to support installation into a subdirectory of WRKDIR. This allows a package to be built, before the actual filesystem is touched. DESTDIR support exists in two variations:

  • Basic DESTDIR support means that the package installation and packaging is still run as root.

  • Full DESTDIR support can run the complete build, installation and packaging as normal user. Root privileges are only needed to add packages.

With basic DESTDIR support, make clean needs to be run as root.

Considering the foo/bar package, DESTDIR full support can be tested using the following commands

$ id
uid=1000(myusername) gid=100(users) groups=100(users),0(wheel)
$ mkdir $HOME/packages
$ cd $PKGSRCDIR/foo/bar

Verify DESTDIR full support, no root privileges should be needed

$ make stage-install

Create a package without root privileges

$ make PACKAGES=$HOME/packages package

For the following command, you must be able to gain root privileges using su(1)

$ make PACKAGES=$HOME/packages install

Then, as a simple user

$ make clean

6.5. Selecting and configuring the compiler

6.5.1. Selecting the compiler

By default, pkgsrc will use GCC to build packages. This may be overridden by setting the following variables in /etc/mk.conf:


This is a list of values specifying the chain of compilers to invoke when building packages. Valid values are:

  • ccc: Compaq C Compilers (Tru64)

  • ccache: compiler cache (chainable)

  • clang: Clang C and Objective-C compiler

  • distcc: distributed C/C++ (chainable)

  • f2c: Fortran 77 to C compiler (chainable)

  • icc: Intel C++ Compiler (Linux)

  • ido: SGI IRIS Development Option cc (IRIX 5)

  • gcc: GNU C/C++ Compiler

  • hp: HP-UX C/aC++ compilers

  • mipspro: Silicon Graphics, Inc. MIPSpro (n32/n64)

  • mipspro-ucode: Silicon Graphics, Inc. MIPSpro (o32)

  • sunpro: Sun Microsystems, Inc. WorkShip/Forte/Sun ONE Studio

  • xlc: IBM's XL C/C++ compiler suite

The default is gcc. You can use ccache and/or distcc with an appropriate PKGSRC_COMPILER setting, e.g. ccache gcc. This variable should always be terminated with a value for a real compiler. Note that only one real compiler should be listed (e.g. sunpro gcc is not allowed).


This specifies the minimum version of GCC to use when building packages. If the system GCC doesn't satisfy this requirement, then pkgsrc will build and install one of the GCC packages to use instead.


Specifies which version of python to use when several options are available.


Specifies the Fortran compiler to use. The default is gfortran.


If PKGSRC_FORTRAN= gfortran is used, this option specifies which version to use.

6.5.2. Additional flags to the compiler (CFLAGS)

If you wish to set the CFLAGS variable, please make sure to use the += operator instead of the = operator:

CFLAGS+=        -your -flags

Using CFLAGS= (i.e. without the +) may lead to problems with packages that need to add their own flags. You may want to take a look at the devel/cpuflags package if you're interested in optimization specifically for the current CPU.

6.5.3. Additional flags to the linker (LDFLAGS)

If you want to pass flags to the linker, both in the configure step and the build step, you can do this in two ways. Either set LDFLAGS or LIBS. The difference between the two is that LIBS will be appended to the command line, while LDFLAGS come earlier. LDFLAGS is pre-loaded with rpath settings for ELF machines depending on the setting of USE_IMAKE or the inclusion of mk/ As with CFLAGS, if you do not wish to override these settings, use the += operator:

LDFLAGS+=        -your -linkerflags

6.6. Developer/advanced settings

  • PKG_DEVELOPER: Run some sanity checks that package developers want:

    • make sure patches apply with zero fuzz

    • run check-shlibs to see that all binaries will find their shared libs.

  • CHECK_FILES_STRICT: Also check VARBASE and PKG_SYSCONFDIR values in PLIST entries.

  • PKG_DEBUG_LEVEL: The level of debugging output which is displayed whilst making and installing the package. The default value for this is 0, which will not display the commands as they are executed (normal, default, quiet operation); the value 1 will display all shell commands before their invocation, and the value 2 will display both the shell commands before their invocation, as well as their actual execution progress with set -x.

6.7. Selecting Build Options

Some packages have build time options, usually to select between different dependencies, enable optional support for big dependencies or enable experimental features.

To see which options, if any, a package supports, and which options are mutually exclusive, run make show-options, for example:

    The following options are supported by this package:
        ssl      Enable SSL support.
    Exactly one of the following gecko options is required:
        firefox  Use firefox as gecko rendering engine.
        mozilla  Use mozilla as gecko rendering engine.
    At most one of the following database options may be selected:
        mysql    Enable support for MySQL database.
        pgsql    Enable support for PostgreSQL database.

    These options are enabled by default: firefox
    These options are currently enabled: mozilla ssl

The following variables can be defined in mk.conf to select which options to enable for a package: PKG_DEFAULT_OPTIONS, which can be used to select or disable options for all packages that support them, and PKG_OPTIONS.pkgbase, which can be used to select or disable options specifically for package pkgbase. Options listed in these variables are selected, options preceded by - are disabled. A few examples:

$ grep "PKG.*OPTION" mk.conf
PKG_DEFAULT_OPTIONS=    -arts -dvdread -esound
PKG_OPTIONS.kdebase=    debug -sasl
PKG_OPTIONS.apache=     suexec 

It is important to note that options that were specifically suggested by the package maintainer must be explicitly removed if you do not wish to include the option. If you are unsure you can view the current state with make show-options.

The following settings are consulted in the order given, and the last setting that selects or disables an option is used:

  1. the default options as suggested by the package maintainer

  2. the options implied by the settings of legacy variables (see below)


  4. PKG_OPTIONS.pkgbase

For groups of mutually exclusive options, the last option selected is used, all others are automatically disabled. If an option of the group is explicitly disabled, the previously selected option, if any, is used. It is an error if no option from a required group of options is selected, and building the package will fail.

Before the options framework was introduced, build options were selected by setting a variable (often named USE_FOO) in mk.conf for each option. To ease transition to the options framework for the user, these legacy variables are converted to the appropriate options setting (PKG_OPTIONS.pkgbase) automatically. A warning is issued to prompt the user to update mk.conf to use the options framework directly. Support for the legacy variables will be removed eventually.