Chapter 5. Configuring pkgsrc

Table of Contents

5.1. General configuration
5.2. Variables affecting the build process
5.3. Variables affecting the installation process
5.4. Selecting and configuring the compiler
5.4.1. Selecting the compiler
5.4.2. Additional flags to the compiler (CFLAGS)
5.4.3. Additional flags to the linker (LDFLAGS)
5.5. Developer/advanced settings
5.6. 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.

During the bootstrap, an example configuration file is created. To use that, you have to create the directory ${PREFIX}/etc and copy the example file there.

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, so you have to try it out to see if it works.

5.1. General configuration

In this section, you can find some variables that 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 /var/db/pkg.

  • 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 are ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/${DIST_SUBDIR}/ and ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/${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.

5.2. Variables affecting the build process

XXX

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

  • DEPENDS_TARGET: By default, dependencies are only installed, and no binary package is created for them. You can set this variable to package-install to automatically create binary packages after installing dependencies. Please note that the PKGSRC_KEEP_BIN_PKGS can be set to yes to preserve binary packages when using the install as well.

5.3. Variables affecting the installation process

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

DESTDIR support is now the default. To switch back to non-DESTDIR, you can set USE_DESTDIR=no; this setting will be deprecated though, so it's preferable to convert a package to DESTDIR instead.

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

5.4. Selecting and configuring the compiler

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

PKGSRC_COMPILER:

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 (Darwin/MacOSX)

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

GCC_REQD:

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.

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

5.4.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/x11.buildlink3.mk. As with CFLAGS, if you do not wish to override these settings, use the += operator:

LDFLAGS+=        -your -linkerflags

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

  • 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, and their actual execution progress with set -x will be displayed.

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

  3. PKG_DEFAULT_OPTIONS

  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.