Chapter 6. Configuring pkgsrc
Prev | Part I. The pkgsrc user's guide | Next

## Chapter 6. Configuring pkgsrc

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 `Makefile`s. 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 `LOCALBASE`s!

- `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 `ftp://ftp.NetBSD.org/pub/pkgsrc/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.

## 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. 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.4. Selecting and configuring the compiler

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

  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.

`PYTHON_VERSION_DEFAULT`:

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

`PKGSRC_FORTRAN`:

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

`GFORTRAN_VERSION`:

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

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

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

## 6.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, as well as their actual execution progress with set -x.

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

Prev | Up | Next
Chapter 5. Using pkgsrc | Home | Chapter 7. Creating binary packages