Before you download any pkgsrc files, you should decide whether you want the current branch or the stable branch. The latter is forked on a quarterly basis from the current branch and only gets modified for security updates. The names of the stable branches are built from the year and the quarter, for example 2006Q1.

The second step is to decide how you want to download pkgsrc. You can get it as a tar file, via SUP, or via CVS. All three ways are described here.

    release=pkgsrc

    % setenv CVSROOT anoncvs@anoncvs.NetBSD.org:/cvsroot
    % setenv CVS_RSH ssh

    $ CVSROOT="anoncvs@anoncvs.NetBSD.org:/cvsroot"
    $ CVS_RSH="ssh"
    $ export CVSROOT CVS_RSH

The preferred way to keep pkgsrc up-to-date is via CVS (which also works if you have first installed it via a tar file). It saves bandwidth and hard disk activity, compared to downloading the tar file again.

We provide a bootstrap kit in both source and binary form for other platforms than NetBSD, consisting of the pkg administration tools and other tools required to use pkgsrc and build packages.

Simply download the binary kit for your platform, and extract it into / e.g.

# cd /
# gzip -c -d /tmp/bootstrap-pkgsrc-SunOS-5.9-sparc-20031023.tar.gz \
  | tar -xpf -

Of course, as with any binary distributions, you should verify the checksum against the SUM or CKSUM file and inspect the contents before extracting it.

Installing the bootstrap kit from source should be as simple as:

# env CVS_RSH=ssh cvs -d anoncvs@anoncvs.NetBSD.org:/cvsroot checkout pkgsrc
# cd pkgsrc/bootstrap
# ./bootstrap
    

See Chapter 2, Where to get pkgsrc and how to keep it up-to-date for other ways to get pkgsrc before bootstrapping. The given bootstrap command will use the defaults of /usr/pkg for the prefix where programs will be installed in, and /var/db/pkg for the package database directory where pkgsrc will do its internal bookkeeping. However, these can also be set using command-line arguments.

Binary packages for the pkgsrc tools and an initial set of packages is available for supported platforms. An up-to-date list of these can be found on www.pkgsrc.org. Note that this only works for privileged builds that install into /usr/pkg.

Here are some platform-specific notes you should be aware of.

# cd pkgsrc/bootstrap
# ./darwindiskimage create ~/Documents/NetBSD 512 # megabytes - season to taste
# ./darwindiskimage mount ~/Documents/NetBSD
# sudo chown `id -u`:`id -g` /Volumes/NetBSD

# sudo mount -u -o suid,sync /Volumes/NetBSD

# ./bootstrap --pkgdbdir /usr/pkg/pkgdb

	  interix:kP=\E[S:kN=\E[T:kH=\E[U:dc@:DC@:tc=pcansi:
	

# chmod -R g+w $PKG_DBDIR
	

	PKGSRC_COMPILER=        mipspro
      

	env CC=/opt/intel_cc_80/bin/icc LDFLAGS=-static-libcxa \
	ac_cv___attribute__=yes ./bootstrap
      

	PKGSRC_COMPILER=        icc
      

	ICCBASE=                /opt/icc
      

	  CC=     cc
	  CXX=    CC
	  CPP=    /usr/ccs/lib/cpp
	

	  #! /bin/sh
	  exec /opt/SUNWspro/bin/cc -xtarget=ultra -xarch=v9 ${1+"$@"}
	

	  $ cd bootstrap
	  $ CC=cc64 ./bootstrap
	

	  CC=                     cc64
	  CXX=                    CC64
	  PKGSRC_COMPILER=        sunpro
	

	  CC=                     cc
	  CXX=                    CC
	  PKGSRC_COMPILER=        sunpro
	  CFLAGS=                 -xtarget=ultra -xarch=v9
	  CXXFLAGS=               -xtarget=ultra -xarch=v9
	  LDFLAGS=                -xtarget=ultra -xarch=v9
	

	CONFIG_SHELL=   ${LOCALBASE}/bin/bash
	WRAPPER_SHELL=  ${LOCALBASE}/bin/bash
      

To use binary packages, you need some tools to manage them. On NetBSD, these tools are already installed. On all other operating systems, you need to install them first. For the following platforms, prebuilt versions of the package tools are available and can simply be downloaded and unpacked in the / directory:

These pre-built package tools use /usr/pkg for the base directory, and /var/db/pkg for the database of installed packages. If you cannot use these directories for whatever reasons (maybe because you're not root), you have to build the package tools yourself, which is explained in Section 3.2, “Bootstrapping pkgsrc”.

# pkg_add /path/to/package.tgz

# pkg_add ftp://ftp.NetBSD.org/pub/NetBSD/packages/<OSVERSION>/<ARCH>/All/package

    # pkg_delete -r jpeg

Package samba-2.0.9 has a local-root-shell vulnerability, see
http://www.samba.org/samba/whatsnew/macroexploit.html

% lintpkgsrc -i
...
Version mismatch: 'tcsh' 6.09.00 vs 6.10.00

After obtaining pkgsrc, the pkgsrc directory now contains a set of packages, organized into categories. You can browse the online index of packages, or run make readme from the pkgsrc directory to build local README.html files for all packages, viewable with any web browser such as www/lynx or www/firefox.

The default prefix for installed packages is /usr/pkg. If you wish to change this, you should do so by setting LOCALBASE in mk.conf. You should not try to use multiple different LOCALBASE definitions on the same system (inside a chroot is an exception).

The rest of this chapter assumes that the package is already in pkgsrc. If it is not, see Part II, “The pkgsrc developer's guide” for instructions how to create your own packages.

DISTDIR=/cdrom/pkgsrc/distfiles

% make fetch-list | sh

% cd misc/figlet
% make

    % make install

    % make clean

    % make clean-depends

In this section, you can find some variables that apply to all pkgsrc packages. The preferred method of setting these variables is by setting them in /etc/mk.conf. 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 the variable's intent.

XXX

XXX

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 /etc/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" /etc/mk.conf
PKG_DEFAULT_OPTIONS=    -arts -dvdread -esound
PKG_OPTIONS.kdebase=    debug -sasl
PKG_OPTIONS.apache=     suexec 

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

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 /etc/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 /etc/mk.conf to use the options framework directly. Support for the legacy variables will be removed eventually.

Once you have built and installed a package, you can create a binary package which can be installed on another system with pkg_add(1). This saves having to build the same package on a group of hosts and wasting CPU time. It also provides a simple means for others to install your package, should you distribute it.

To create a binary package, change into the appropriate directory in pkgsrc, and run make package:

# cd misc/figlet
# make package
    

This will build and install your package (if not already done), and then build a binary package from what was installed. You can then use the pkg_* tools to manipulate it. Binary packages are created by default in /usr/pkgsrc/packages, in the form of a gzipped tar file. See Section B.2, “Packaging figlet” for a continuation of the above misc/figlet example.

See Chapter 19, Submitting and Committing for information on how to submit such a binary package.

See Section 15.16, “Other helpful targets”.

If you want to get a full set of precompiled binary packages, this section describes how to get them. Beware that the bulk build will remove all currently installed packages from your system!

Having an FTP server configured either on the machine doing the bulk builds or on a nearby NFS server can help to make the packages available to other machines that can then save time by installing only the binary packages. See ftpd(8) for more information. If you use a remote NFS server's storage, be sure to not actually compile on NFS storage, as this slows things down a lot.

	  PACKAGES?=      ${_PKGSRCDIR}/packages/${MACHINE_ARCH}
	  WRKOBJDIR?=     /usr/tmp/pkgsrc   # build here instead of in pkgsrc
	  BSDSRCDIR=      /usr/src
	  BSDXSRCDIR=     /usr/xsrc         # for x11/xservers
	  OBJHOSTNAME?=   yes               # use work.`hostname`
	  FAILOVER_FETCH= yes               # insist on the correct checksum
	  PKG_DEVELOPER?= yes
	  _ACCEPTABLE=    yes
	

echo "I do not have enough disk space to build this pig." \
	> misc/openoffice/$BROKENF

	( cd /usr/pkgsrc/security/ssh ; make bulk-install )
	if [ -f /usr/pkg/etc/rc.d/sshd ]; then
	/usr/pkg/etc/rc.d/sshd
	fi
      

# cd /usr/pkgsrc
# sh mk/bulk/build
      

# sh mk/bulk/build restart

# cd /usr/sandbox/usr/pkgsrc
# sh mk/bulk/do-sandbox-build
      

RSYNC_DST=ftp.NetBSD.org:/pub/NetBSD/packages/pkgsrc-200xQy/NetBSD-a.b.c/arch/upload 

RSYNC_DST=hubertf@ftp.NetBSD.org:/pub/NetBSD/packages/pkgsrc-200xQy/NetBSD-a.b.c/arch/upload

nbftp% mkdir -p -m 750 /pub/NetBSD/packages/pkgsrc-200xQy/NetBSD-a.b.c/arch/upload

# chroot /usr/sandbox
chroot-# rm $HOME/.ssh/id-dsa*
chroot-# ssh-keygen -t dsa
chroot-# cat $HOME/.ssh/id-dsa.pub
      

chroot-# ssh ftp.NetBSD.org date 

chroot-# exit
# cd /usr/sandbox/usr/pkgsrc
# sh mk/bulk/do-sandbox-upload
      

nbftp% vi ~/.ssh/authorized_keys
      Gdd:x! 

nbftp% cd /pub/NetBSD/packages/pkgsrc-200xQy/NetBSD-a.b.c/arch
nbftp% mv upload/* .
nbftp% rmdir upload
nbftp% chmod 755 .
      

After your pkgsrc bulk-build has completed, you may wish to create a CD-ROM set of the resulting binary packages to assist in installing packages on other machines. The pkgtools/cdpack package provides a simple tool for creating the ISO 9660 images. cdpack arranges the packages on the CD-ROMs in a way that keeps all the dependencies for a given package on the same CD as that package.

# mkdir /u2/images
# pkg_add /usr/pkgsrc/packages/All/cdpack
# cdpack /usr/pkgsrc/packages/All /u2/images
      

# mkdir /tmp/common
# echo "This is a README" > /tmp/common/README
# echo "Another file" > /tmp/common/COPYING
# mkdir /tmp/common/bin
# echo "#!/bin/sh" > /tmp/common/bin/myscript
# echo "echo Hello world" >> /tmp/common/bin/myscript
# chmod 755 /tmp/common/bin/myscript
      

# cdpack -x /tmp/common /usr/pkgsrc/packages/All /u2/images

The following mailing lists may be of interest to pkgsrc users:

To subscribe, do:

    % echo subscribe listname | mail majordomo@NetBSD.org

Archives for all these mailing lists are available from http://mail-index.NetBSD.org/.

Pkgviews is tightly integrated with buildlink. You can find a pkgviews User's guide in pkgsrc/mk/buildlink3/PKGVIEWS_UG.

The directory pkgsrc/pkgtools contains a number of useful utilities for both users and developers of pkgsrc. This section attempts only to make the reader aware of the utilities and when they might be useful, and not to duplicate the documentation that comes with each package.

Utilities used by pkgsrc (automatically installed when needed):

OS tool augmentation (automatically installed when needed):

Utilities used by pkgsrc (not automatically installed):

Utilities for keeping track of installed packages, being up to date, etc:

Utilities for people maintaining or creating individual packages:

Utilities for people maintaining pkgsrc (or: more obscure pkg utilities)

If you want to use pkgsrc as non-root user, you can set some variables to make pkgsrc work under these conditions. At the very least, you need to set UNPRIVILEGED to “yes”; this will turn on unprivileged mode and set multiple related variables to allow installation of packages as non-root.

In case the defaults are not enough, you may want to tune some other variables used. For example, if the automatic user/group detection leads to incorrect values (or not the ones you would like to use), you can change them by setting UNPRIVILEGED_USER and UNPRIVILEGED_GROUP respectively.

As regards bootstrapping, please note that the bootstrap script will ease non-root configuration when given the “--ignore-user-check” flag, as it will choose and use multiple default directories under ~/pkg as the installation targets. These directories can be overriden by the “--prefix” flag provided by the script, as well as some others that allow finer tuning of the tree layout.

By default, resuming transfers in pkgsrc is disabled, but you can enable this feature by adding the option PKG_RESUME_TRANSFERS=YES into /etc/mk.conf. If, during a fetch step, an incomplete distfile is found, pkgsrc will try to resume it.

You can also use a different program than the default ftp(1) by changing the FETCH_CMD variable. Don't forget to set FETCH_RESUME_ARGS and FETCH_OUTPUT_ARGS if you are not using default values.

For example, if you want to use wget to resume downloads, you'll have to use something like:

    FETCH_CMD=             wget
    FETCH_BEFORE_ARGS=     --passive-ftp
    FETCH_RESUME_ARGS=     -c
    FETCH_OUTPUT_ARGS=     -O

If you want to use XFree86 from pkgsrc instead of your system's own X11 (/usr/X11R6, /usr/openwin, ...), you will have to add the following line into /etc/mk.conf:

    X11_TYPE=XFree86

If you want to use X.org from pkgsrc instead of your system's own X11 (/usr/X11R6, /usr/openwin, ...) you will have to add the following line into /etc/mk.conf:

    X11_TYPE=xorg

If you are sitting behind a firewall which does not allow direct connections to Internet hosts (i.e. non-NAT), you may specify the relevant proxy hosts. This is done using an environment variable in the form of a URL, e.g. in Amdahl, the machine “orpheus.amdahl.com” is one of the firewalls, and it uses port 80 as the proxy port number. So the proxy environment variables are:

    ftp_proxy=ftp://orpheus.amdahl.com:80/
    http_proxy=http://orpheus.amdahl.com:80/

This depends on which utility is used to retrieve distfiles. From bsd.pkg.mk, FETCH_CMD is assigned the first available command from the following list:

On a default NetBSD installation, this will be /usr/bin/ftp, which automatically tries passive connections first, and falls back to active connections if the server refuses to do passive. For the other tools, add the following to your /etc/mk.conf file: PASSIVE_FETCH=1.

Having that option present will prevent /usr/bin/ftp from falling back to active transfers.

You would like to download all the distfiles in a single batch from work or university, where you can't run a make fetch. There is an archive of distfiles on ftp.NetBSD.org, but downloading the entire directory may not be appropriate.

The answer here is to do a make fetch-list in /usr/pkgsrc or one of its subdirectories, carry the resulting list to your machine at work/school and use it there. If you don't have a NetBSD-compatible ftp(1) (like tnftp) at work, don't forget to set FETCH_CMD to something that fetches a URL:

At home:

% cd /usr/pkgsrc
% make fetch-list FETCH_CMD=wget DISTDIR=/tmp/distfiles >/tmp/fetch.sh
% scp /tmp/fetch.sh work:/tmp

At work:

% sh /tmp/fetch.sh

then tar up /tmp/distfiles and take it home.

If you have a machine running NetBSD, and you want to get all distfiles (even ones that aren't for your machine architecture), you can do so by using the above-mentioned make fetch-list approach, or fetch the distfiles directly by running:

% make mirror-distfiles

If you even decide to ignore NO_{SRC,BIN}_ON_{FTP,CDROM}, then you can get everything by running:

% make fetch NO_SKIP=yes

When compiling the pkgtools/pkg_install package, you get the error from make that it doesn't know how to make /usr/share/tmac/tmac.andoc? This indicates that you don't have installed the “text” set (nroff, ...) from the NetBSD base distribution on your machine. It is recommended to do that to format man pages.

In the case of the pkgtools/pkg_install package, you can get away with setting NOMAN=YES either in the environment or in /etc/mk.conf.

You didn't install the compiler set, comp.tgz, when you installed your NetBSD machine. Please get and install it, by extracting it in /:

# cd /
# tar --unlink -zxvpf .../comp.tgz

comp.tgz is part of every NetBSD release. Get the one that corresponds to your release (determine via uname -r).

When installing packages as non-root user and using the just-in-time su(1) feature of pkgsrc, it can become annoying to type in the root password for each required package installed. To avoid this, the sudo package can be used, which does password caching over a limited time. To use it, install sudo (either as binary package or from security/sudo) and then put the following into your /etc/mk.conf:

    .if exists(${LOCALBASE}/bin/sudo)
    SU_CMD=        ${LOCALBASE}/bin/sudo /bin/sh -c
    .endif

As the system administrator, you can choose where configuration files are installed. The default settings make all these files go into ${PREFIX}/etc or some of its subdirectories; this may be suboptimal depending on your expectations (e.g., a read-only, NFS-exported PREFIX with a need of per-machine configuration of the provided packages).

In order to change the defaults, you can modify the PKG_SYSCONFBASE variable (in /etc/mk.conf) to point to your preferred configuration directory; some common examples include /etc or /etc/pkg.

Furthermore, you can change this value on a per-package basis by setting the PKG_SYSCONFDIR.${PKG_SYSCONFVAR} variable. PKG_SYSCONFVAR's value usually matches the name of the package you would like to modify, that is, the contents of PKGBASE.

Note that after changing these settings, you must rebuild and reinstall any affected packages.

Please be aware that there can often be bugs in third-party software, and some of these bugs can leave a machine vulnerable to exploitation by attackers. In an effort to lessen the exposure, the NetBSD packages team maintains a database of known-exploits to packages which have at one time been included in pkgsrc. The database can be downloaded automatically, and a security audit of all packages installed on a system can take place. To do this, install the security/audit-packages package. It has two components:

Use of the security/audit-packages package is strongly recommended! After “audit-packages” is installed, please read the package's message, which you can get by running pkg_info -D audit-packages.

If this package is installed, pkgsrc builds will use it to perform a security check before building any package. See Section 5.2, “Variables affecting the build process” for ways to control this check.

When you add your own preferences to the CFLAGS variable in your mk.conf, these flags are passed in environment variables to the ./configure scripts and to make(1). Some package authors ignore the CFLAGS from the environment variable by overriding them in the Makefiles of their package.

Currently there is no solution to this problem. If you really need the package to use your CFLAGS you should run make patch in the package directory and then inspect any Makefile and Makefile.in for whether they define CFLAGS explicitly. Usually you can remove these lines. But be aware that some “smart” programmers write so bad code that it only works for the specific combination of CFLAGS they have chosen.

Building, installation and creation of a binary package are all controlled by the package's Makefile. The Makefile describes various things about a package, for example from where to get it, how to configure, build, and install it.

A package Makefile contains several sections that describe the package.

In the first section there are the following variables, which should appear exactly in the order given here. The order and grouping of the variables is mostly historical and has no further meaning.

The second section contains information about separately downloaded patches, if any.

The third section contains the following variables.

Other variables that affect the build:

Please pay attention to the following gotchas:

The distinfo file contains the message digest, or checksum, of each distfile needed for the package. This ensures that the distfiles retrieved from the Internet have not been corrupted during transfer or altered by a malign force to introduce a security hole. Due to recent rumor about weaknesses of digest algorithms, all distfiles are protected using both SHA1 and RMD160 message digests, as well as the file size.

The distinfo file also contains the checksums for all the patches found in the patches directory (see Section 9.3, “patches/*”).

To regenerate the distinfo file, use the make makedistinfo or make mdi command.

Some packages have different sets of distfiles depending on the platform, for example www/navigator). These are kept in the same distinfo file and care should be taken when upgrading such a package to ensure distfile information is not lost.

This directory contains files that are used by the patch(1) command to modify the sources as distributed in the distribution file into a form that will compile and run perfectly on NetBSD. The files are applied successively in alphabetic order (as returned by a shell “patches/patch-*” glob expansion), so patch-aa is applied before patch-ab, etc.

The patch-* files should be in diff -bu format, and apply without a fuzz to avoid problems. (To force patches to apply with fuzz you can set PATCH_FUZZ_FACTOR=-F2). Furthermore, do not put changes for more than one file into a single patch file, as this will make future modifications more difficult.

Similar, a file should be patched at most once, not several times by several different patches. If a file needs several patches, they should be combined into one file.

One important thing to mention is to pay attention that no RCS IDs get stored in the patch files, as these will cause problems when later checked into the NetBSD CVS tree. Use the pkgdiff from the pkgtools/pkgdiff package to avoid these problems.

For even more automation, we recommend using mkpatches from the same package to make a whole set of patches. You just have to backup files before you edit them to filename.orig, e.g. with cp -p filename filename.orig or, easier, by using pkgvi again from the same package. If you upgrade a package this way, you can easily compare the new set of patches with the previously existing one with patchdiff. Copy the patches you want to use or update from the work/.newpatches directory to patches/.

When you have finished a package, remember to generate the checksums for the patch files by using the make makepatchsum command, see Section 9.2, “distinfo”.

When adding a patch that corrects a problem in the distfile (rather than e.g. enforcing pkgsrc's view of where man pages should go), send the patch as a bug report to the maintainer. This benefits non-pkgsrc users of the package, and usually makes it possible to remove the patch in future version.

If you want to share patches between multiple packages in pkgsrc, e.g. because they use the same distfiles, set PATCHDIR to the path where the patch files can be found, e.g.:

    PATCHDIR= ${.CURDIR}/../xemacs/patches
  

Patch files that are distributed by the author or other maintainers can be listed in PATCHFILES.

If it is desired to store any patches that should not be committed into pkgsrc, they can be kept outside the pkgsrc tree in the $LOCALPATCHES directory. The directory tree there is expected to have the same “category/package” structure as pkgsrc, and patches are expected to be stored inside these dirs (also known as $LOCALPATCHES/$PKGPATH). For example, if you want to keep a private patch for pkgsrc/graphics/png, keep it in $LOCALPATCHES/graphics/png/mypatch. All files in the named directory are expected to be patch files, and they are applied after pkgsrc patches are applied.

case ${target_os} in
		netbsd*) have_kvm=yes ;;
		*)       have_kvm=no  ;;
		esac

AC_CHECK_LIB(kvm, kvm_open, have_kvm=yes, have_kvm=no)

#if defined(__NetBSD__)
		#  include <sys/event.h>
		#endif

#if defined(HAVE_SYS_EVENT_H)
		#  include <sys/event.h>
		#endif

int
	      monitor_file(...)
	      {
	      #if defined(__NetBSD__)
	      int fd = kqueue();
	      ...
	      #else
	      ...
	      #endif
	      }

int
		monitor_file(...)
		{
		#if defined(HAVE_KQUEUE)
		int fd = kqueue();
		...
		#else
		...
		#endif
		}

When you type make, the distribution files are unpacked into the directory denoted by WRKDIR. It can be removed by running make clean. Besides the sources, this directory is also used to keep various timestamp files. The directory gets removed completely on clean. The default is ${.CURDIR}/work or ${.CURDIR}/work.${MACHINE_ARCH} if OBJMACHINE is set.

If you have any files that you wish to be placed in the package prior to configuration or building, you could place these files here and use a ${CP} command in the “pre-configure” target to achieve this. Alternatively, you could simply diff the file against /dev/null and use the patch mechanism to manage the creation of this file.

If you want to share files in this way with other packages, set the FILESDIR variable to point to the other package's files directory, e.g.:

      FILESDIR=${.CURDIR}/../xemacs/files
    

Makefile variables contain strings that can be processed using the five operators ``='', ``+='', ``?='', ``:='', and ``!='', which are described in the make(1) man page.

When a variable's value is parsed from a Makefile, the hash character ``#'' and the backslash character ``\'' are handled specially. If a backslash is followed by a newline, any whitespace immediately in front of the backslash, the backslash, the newline, and any whitespace immediately behind the newline are replaced with a single space. A backslash character and an immediately following hash character are replaced with a single hash character. Otherwise, the backslash is passed as is. In a variable assignment, any hash character that is not preceded by a backslash starts a comment that continues upto the end of the logical line.

Note: Because of this parsing algorithm the only way to create a variable consisting of a single backslash is using the ``!='' operator, for example: BACKSLASH!=echo "\\".

So far for defining variables. The other thing you can do with variables is evaluating them. A variable is evaluated when it is part of the right side of the ``:='' or the ``!='' operator, or directly before executing a shell command which the variable is part of. In all other cases, make(1) performs lazy evaluation, that is, variables are not evaluated until there's no other way. The ``modifiers'' mentioned in the man page also evaluate the variable.

Some of the modifiers split the string into words and then operate on the words, others operate on the string as a whole. When a string is split into words, it is split as you would expect it from sh(1).

No rule without exception—the .for loop does not follow the shell quoting rules but splits at sequences of whitespace.

There are several types of variables that should be handled differently. Strings and two types of lists.

This section presents you with some code snippets you should use in your own code. If you don't find anything appropriate here, you should test your code and add it here.

    STRING=                 foo * bar `date`
    INT_LIST=               # empty
    ANOTHER_INT_LIST=       apache-[0-9]*:../../www/apache
    EXT_LIST=               # empty
    ANOTHER_EXT_LIST=       a=b c=d

    INT_LIST+=              ${STRING}               # 1
    INT_LIST+=              ${ANOTHER_INT_LIST}     # 2
    EXT_LIST+=              ${STRING:Q}             # 3
    EXT_LIST+=              ${ANOTHER_EXT_LIST}     # 4

    EXT_LIST=       # empty
    .for i in ${INT_LIST}
    EXT_LIST+=      ${i:Q}""
    .endfor

    STRING=         foo bar <    > * `date` $$HOME ' "
    EXT_LIST=       string=${STRING:Q} x=second\ item

    all:
            echo ${STRING}                  # 1
            echo "${STRING}"                # 2
            echo "${STRING:Q}"              # 3
            echo ${STRING:Q}                # 4
            echo x${STRING:Q} | sed 1s,.,,  # 5
            printf "%s\\n" ${STRING:Q}""    # 6
            env ${EXT_LIST} /bin/sh -c 'echo "$$string"; echo "$$x"'

    VAR:=   ${VAR:N${_othervar_:C/-//}}

Be sure to add a RCS ID line as the first thing in any PLIST file you write:

      @comment $NetBSD$
    

You can use the make print-PLIST command to output a PLIST that matches any new files since the package was extracted. See Section 15.16, “Other helpful targets” for more information on this target.

If you have used any of the *-dirs packages, as explained in Section 11.8, “Sharing directories between packages”, you may have noticed that make print-PLIST outputs a set of @comments instead of real @dirrm lines. You can also do this for specific directories and files, so that the results of that command are very close to reality. This helps a lot during the update of packages.

The PRINT_PLIST_AWK variable takes a set of AWK patterns and actions that are used to filter the output of print-PLIST. You can append any chunk of AWK scripting you like to it, but be careful with quoting.

For example, to get all files inside the libdata/foo directory removed from the resulting PLIST:

      PRINT_PLIST_AWK+=       /^libdata\/foo/ { next; }
    

And to get all the @dirrm lines referring to a specific (shared) directory converted to @comments:

      PRINT_PLIST_AWK+=       /^@dirrm share\/specific/ { print "@comment " $$0; next; }
    

A number of variables are substituted automatically in PLISTs when a package is installed on a system. This includes the following variables:

For a complete list of values which are replaced by default, please look in bsd.pkg.mk (and search for PLIST_SUBST).

If you want to change other variables not listed above, you can add variables and their expansions to this variable in the following way, similar to MESSAGE_SUBST (see Section 9.5, “Optional files”):

      PLIST_SUBST+=   SOMEVAR="somevalue"
    

This replaces all occurrences of “${SOMEVAR}” in the PLIST with “somevalue”.

Man pages should be installed in compressed form if MANZ is set (in bsd.own.mk), and uncompressed otherwise. To handle this in the PLIST file, the suffix “.gz” is appended/removed automatically for man pages according to MANZ and MANCOMPRESSED being set or not, see above for details. This modification of the PLIST file is done on a copy of it, not PLIST itself.

To use one or more files as source for the PLIST used in generating the binary package, set the variable PLIST_SRC to the names of that file(s). The files are later concatenated using cat(1), and the order of things is important. The default for PLIST_SRC is ${PKGDIR}/PLIST.

Some packages decide to install a different set of files based on the operating system being used. These differences can be automatically handled by using the following files:

A “shared directory” is a directory where multiple (and unrelated) packages install files. These directories are problematic because you have to add special tricks in the PLIST to conditionally remove them, or have some centralized package handle them.

Within pkgsrc, you'll find both approaches. If a directory is shared by a few unrelated packages, it's often not worth to add an extra package to remove it. Therefore, one simply does:

      @unexec ${RMDIR} %D/path/to/shared/directory 2>/dev/null || ${TRUE}
    

in the PLISTs of all affected packages, instead of the regular "@dirrm" line.

However, if the directory is shared across many packages, two different solutions are available:

From now on, we'll discuss the second solution. To get an idea of the *-dirs packages available, issue:

      % cd .../pkgsrc
      % ls -d */*-dirs
    

Their use from other packages is very simple. The USE_DIRS variable takes a list of package names (without the “-dirs” part) together with the required version number (always pick the latest one when writing new packages).

For example, if a package installs files under share/applications, it should have the following line in it:

      USE_DIRS+=      xdg-1.1
    

After regenerating the PLIST using make print-PLIST, you should get the right (commented out) lines.

Note that even if your package is using $X11BASE, it must not depend on the *-x11-dirs packages. Just specify the name without that part and pkgsrc (in particular, mk/dirs.mk) will take care of it.

The process of converting packages to use the buildlink3 framework (“bl3ifying”) is fairly straightforward. The things to keep in mind are:

If a dependency on a particular package is required for its libraries and headers, then we replace:

      DEPENDS+=   foo>=1.1.0:../../category/foo
    

with

      .include "../../category/foo/buildlink3.mk"
    

The buildlink3.mk files usually define the required dependencies. If you need a newer version of the dependency when using buildlink3.mk files, then you can define it in your Makefile; for example:

      BUILDLINK_API_DEPENDS.foo+=   foo>=1.1.0
      .include "../../category/foo/buildlink3.mk"
    

There are several buildlink3.mk files in pkgsrc/mk that handle special package issues:

The comments in those buildlink3.mk files provide a more complete description of how to use them properly.

A package's buildlink3.mk file is included by Makefiles to indicate the need to compile and link against header files and libraries provided by the package. A buildlink3.mk file should always provide enough information to add the correct type of dependency relationship and include any other buildlink3.mk files that it needs to find headers and libraries that it needs in turn.

To generate an initial buildlink3.mk file for further editing, Rene Hexel's pkgtools/createbuildlink package is highly recommended. For most packages, the following command will generate a good starting point for buildlink3.mk files:

% cd pkgsrc/category/pkgdir
% createbuildlink >buildlink3.mk
    

	# $NetBSD: buildlink3.mk,v 1.7 2004/03/18 09:12:12 jlam Exp $

	BUILDLINK_DEPTH:=       ${BUILDLINK_DEPTH}+
	TIFF_BUILDLINK3_MK:=    ${TIFF_BUILDLINK3_MK}+

	.if !empty(BUILDLINK_DEPTH:M+)
	BUILDLINK_DEPENDS+=     tiff
	.endif

	BUILDLINK_PACKAGES:=    ${BUILDLINK_PACKAGES:Ntiff}
	BUILDLINK_PACKAGES+=    tiff

	.if !empty(TIFF_BUILDLINK3_MK:M+)
	BUILDLINK_API_DEPENDS.tiff+=        tiff>=3.6.1
	BUILDLINK_PKGSRCDIR.tiff?=      ../../graphics/tiff
	.endif  # TIFF_BUILDLINK3_MK

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

	BUILDLINK_DEPTH:=       ${BUILDLINK_DEPTH:S/+$//}
      

Some packages in pkgsrc install headers and libraries that coincide with headers and libraries present in the base system. Aside from a buildlink3.mk file, these packages should also include a builtin.mk file that includes the necessary checks to decide whether using the built-in software or the pkgsrc software is appropriate.

The only requirements of a builtin.mk file for pkg are:

	.if !defined(IS_BUILTIN.foo)
	#
	# IS_BUILTIN.foo is set to "yes" or "no" depending on whether "foo"
	# genuinely exists in the system or not.
	#
	IS_BUILTIN.foo?=        no

	# BUILTIN_PKG.foo should be set here if "foo" is built-in and its package
	# version can be determined.
	#
	.  if !empty(IS_BUILTIN.foo:M[yY][eE][sS])
	BUILTIN_PKG.foo?=       foo-1.0
	.  endif
	.endif  # IS_BUILTIN.foo

	.if !defined(USE_BUILTIN.foo)
	USE_BUILTIN.foo?=       ${IS_BUILTIN.foo}
	.  if defined(BUILTIN_PKG.foo)
	.    for _depend_ in ${BUILDLINK_API_DEPENDS.foo}
	.      if !empty(USE_BUILTIN.foo:M[yY][eE][sS])
	USE_BUILTIN.foo!=                                                       \
	if ${PKG_ADMIN} pmatch '${_depend_}' ${BUILTIN_PKG.foo}; then     \
	${ECHO} "yes";                                            \
	else                                                              \
	${ECHO} "no";                                             \
	fi
	.      endif
	.    endfor
	.  endif
	.endif  # USE_BUILTIN.foo

	CHECK_BUILTIN.foo?=     no
	.if !empty(CHECK_BUILTIN.foo:M[nN][oO])
	#
	# Here we place code that depends on whether USE_BUILTIN.foo is set to
	# "yes" or "no".
	#
	.endif  # CHECK_BUILTIN.foo
      

	PREFER_PKGSRC=  yes
	PREFER_NATIVE=  getopt skey tcp_wrappers
      

As you already know, the PLIST file holds a list of files and directories that belong to a package. The names used in it are relative to the installation prefix (${PREFIX}), which means that it cannot register files outside this directory (absolute path names are not allowed). Despite this restriction, some packages need to install files outside this location; e.g., under ${VARBASE} or ${PKG_SYSCONFDIR}. The only way to achieve this is to create such files during installation time by using installation scripts.

The generic installation scripts are shell scripts that can contain arbitrary code. The list of scripts to execute is taken from the INSTALL_FILE variable, which defaults to INSTALL. A similar variable exists for package removal (DEINSTALL_FILE, whose default is DEINSTALL). These scripts can run arbitrary commands, so they have the potential to create and manage files anywhere in the file system.

Using these general installation files is not recommended, but may be needed in some special cases. One reason for avoiding them is that the user has to trust the packager that there is no unwanted or simply erroneous code included in the installation script. Also, previously there were many similar scripts for the same functionality, and fixing a common error involved finding and changing all of them.

The pkginstall framework offers another, standardized way. It provides generic scripts to abstract the manipulation of such files and directories based on variables set in the package's Makefile. The rest of this section describes these variables.

Configuration files are special in the sense that they are installed in their own specific directory, PKG_SYSCONFDIR, and need special treatment during installation (most of which is automated by pkginstall). The main concept you must bear in mind is that files marked as configuration files are automatically copied to the right place (somewhere inside PKG_SYSCONFDIR) during installation if and only if they didn't exist before. Similarly, they will not be removed if they have local modifications. This ensures that administrators never lose any custom changes they may have made.

    CONFIGURE_ARGS+= --sysconfdir=${PKG_SYSCONFDIR}

    EGDIR=        ${PREFIX}/share/doc/mutt/samples
    CONF_FILES=   ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc

System startup scripts are special files because they must be installed in a place known by the underlying OS, usually outside the installation prefix. Therefore, the same rules described in Section 13.1, “Files and directories outside the installation prefix” apply, and the same solutions can be used. However, pkginstall provides a special mechanism to handle these files.

In order to provide system startup scripts, the package has to:

Once this is done, pkginstall will do the following steps for each script in an automated fashion:

If a package needs to create special users and/or groups during installation, it can do so by using the pkginstall framework.

Users can be created by adding entries to the PKG_USERS variable. Each entry has the following syntax:

    user:group

Further specification of user details may be done by setting per-user variables. PKG_UID.user is the numeric UID for the user. PKG_GECOS.user is the user's description or comment. PKG_HOME.user is the user's home directory, and defaults to /nonexistent if not specified. PKG_SHELL.user is the user's shell, and defaults to /sbinno/login if not specified.

Similarly, groups can be created by adding entries to the PKG_GROUPS variable, whose syntax is:

    group

The numeric GID of the group may be set by defining PKG_GID.group.

If a package needs to create the users and groups at an earlier stage, then it can set USERGROUP_PHASE to either configure or build to indicate the phase before which the users and groups are created. In this case, the numeric UIDs and GIDs of the created users and groups are automatically hardcoded into the final installation scripts.

Packages that install system shells should register them in the shell database, /etc/shells, to make things easier to the administrator. This must be done from the installation scripts to keep binary packages working on any system. pkginstall provides an easy way to accomplish this task.

When a package provides a shell interpreter, it has to set the PKG_SHELL variable to its absolute file name. This will add some hooks to the installation scripts to handle it. Consider the following example, taken from shells/zsh:

    PKG_SHELL=      ${PREFIX}/bin/zsh

Packages that install X11 fonts should update the database files that index the fonts within each fonts directory. This can easily be accomplished within the pkginstall framework.

When a package installs X11 fonts, it must list the directories in which fonts are installed in the FONTS_DIRS.type variables, where type can be one of “ttf”, “type1” or “x11”. This will add hooks to the installation scripts to run the appropriate commands to update the fonts database files within each of those directories. For convenience, if the directory path is relative, it is taken to be relative to the package's installation prefix. Consider the following example, taken from fonts/dbz-ttf:

    FONTS_DIRS.ttf= ${PREFIX}/lib/X11/fonts/TTF

Global default options are listed in PKG_DEFAULT_OPTIONS, which is a list of the options that should be built into every package if that option is supported. This variable should be set in /etc/mk.conf.

The following example shows how bsd.options.mk should be used by the hypothetical ``wibble'' package, either in the package Makefile, or in a file, e.g. options.mk, that is included by the main package Makefile.

    PKG_OPTIONS_VAR=                PKG_OPTIONS.wibble
    PKG_SUPPORTED_OPTIONS=          wibble-foo ldap
    PKG_OPTIONS_OPTIONAL_GROUPS=    database
    PKG_OPTIONS_GROUP.database=     mysql pgsql
    PKG_SUGGESTED_OPTIONS=          wibble-foo
    PKG_OPTIONS_LEGACY_VARS+=       WIBBLE_USE_OPENLDAP:ldap
    PKG_OPTIONS_LEGACY_OPTS+=       foo:wibble-foo

    .include "../../mk/bsd.prefs.mk"

    # this package was previously named wibble2
    .if defined(PKG_OPTIONS.wibble2)
    PKG_LEGACY_OPTIONS+=            ${PKG_OPTIONS.wibble2}
    PKG_OPTIONS_DEPRECATED_WARNINGS+= \
            "Deprecated variable PKG_OPTIONS.wibble2 used, use ${PKG_OPTIONS_VAR} instead."
    .endif

    .include "../../mk/bsd.options.mk"

    # Package-specific option-handling

    ###
    ### FOO support
    ###
    .if !empty(PKG_OPTIONS:Mwibble-foo)
    CONFIGURE_ARGS+=    --enable-foo
    .endif

    ###
    ### LDAP support
    ###
    .if !empty(PKG_OPTIONS:Mldap)
    .  include "../../databases/openldap-client/buildlink3.mk"
    CONFIGURE_ARGS+=    --enable-ldap=${BUILDLINK_PREFIX.openldap-client}
    .endif

    ###
    ### database support
    ###
    .if !empty(PKG_OPTIONS:Mmysql)
    .  include "../../mk/mysql.buildlink3.mk"
    .endif
    .if !empty(PKG_OPTIONS:Mpgsql)
    .  include "../../mk/pgsql.buildlink3.mk"
    .endif

The first section contains the information about which build options are supported by the package, and any default options settings if needed.

A package should never modify PKG_DEFAULT_OPTIONS or the variable named in PKG_OPTIONS_VAR. These are strictly user-settable. To suggest a default set of options, use PKG_SUGGESTED_OPTIONS.

PKG_OPTIONS_VAR must be defined before including bsd.options.mk. If none of PKG_SUPPORTED_OPTIONS, PKG_OPTIONS_OPTIONAL_GROUPS, and PKG_OPTIONS_REQUIRED_GROUPS are defined (as can happen with platform-specific options if none of them is supported on the current platform), PKG_OPTIONS is set to the empty list and the package is otherwise treated as not using the options framework.

After the inclusion of bsd.options.mk, the variable PKG_OPTIONS contains the list of selected build options, properly filtered to remove unsupported and duplicate options.

The remaining sections contain the logic that is specific to each option. The correct way to check for an option is to check whether it is listed in PKG_OPTIONS:

    .if !empty(PKG_OPTIONS:Moption)

Options that enable similar features in different packages (like optional support for a library) should use a common name in all packages that support it (like the name of the library). If another package already has an option with the same meaning, use the same name.

Options that enable features specific to one package, where it's unlikely that another (unrelated) package has the same (or a similar) optional feature, should use a name prefixed with pkgname-.

If a group of related packages share an optional feature specific to that group, prefix it with the name of the “main” package (e. g. djbware-errno-hack).

For new options, add a line to mk/defaults/options.description. Lines have two fields, separated by tab. The first field is the option name, the second its description. The description should be a whole sentence (starting with an uppercase letter and ending with a period) that describes what enabling the option does. E. g. “Enable ispell support.” The file is sorted by option names.

This chapter gives a detailed description on how a package is built. Building a package is separated into different phases (for example fetch, build, install), all of which are described in the following sections. Each phase is splitted into so-called stages, which take the name of the containing phase, prefixed by one of pre-, do- or post-. (Examples are pre-configure, post-build.) Most of the actual work is done in the do-* stages.

The basic steps for building a program are always the same. First the program's source (distfile) must be brought to the local system and then extracted. After any pkgsrc-specific patches to compile properly are applied, the software can be configured, then built (usually by compiling), and finally the generated binaries, etc. can be put into place on the system.

Before outlining the process performed by the NetBSD package system in the next section, here's a brief discussion on where programs are installed, and which variables influence this.

The automatic variable PREFIX indicates where all files of the final program shall be installed. It is usually set to LOCALBASE (/usr/pkg), or CROSSBASE for pkgs in the “cross” category. The value of PREFIX needs to be put into the various places in the program's source where paths to these files are encoded. See Section 9.3, “patches/*” and Section 17.3.1, “Shared libraries - libtool” for more details.

When choosing which of these variables to use, follow the following rules:

When building a package, a number of directories is used to store source files, temporary files, pkgsrc-internal files, and so on. These directories are explained here.

Some of the directory variables contain relative pathnames. There are two common base directories for these relative directories: PKGSRCDIR/PKGPATH is used for directories that are pkgsrc-specific. WRKSRC is used for directories inside the package itself.

You can run a particular phase by typing make phase, where phase is the name of the phase. This will automatically run all phases that are required for this phase. The default phase is build, that is, when you run make without parameters in a package directory, the package will be built, but not installed.

The first step in building a package is to fetch the distribution files (distfiles) from the sites that are providing them. This is the task of the fetch phase.

    DISTFILES=      ${DISTNAME}${EXTRACT_SUFX} additional-files.tar.gz

    DISTFILES=      ${DISTNAME}${EXTRACT_SUFX}
    DISTFILES+=     foo-file.tar.gz
    SITES.foo-file.tar.gz= \
            http://www.somewhere.com/somehow/ \
            http://www.somewhereelse.com/mirror/somehow/

    MASTER_SITES=   http://www.example.com/download.cgi?file=

    ${MASTER_SITE_APACHE}
    ${MASTER_SITE_BACKUP}
    ${MASTER_SITE_CYGWIN}
    ${MASTER_SITE_DEBIAN}
    ${MASTER_SITE_FREEBSD}
    ${MASTER_SITE_FREEBSD_LOCAL}
    ${MASTER_SITE_GNOME}
    ${MASTER_SITE_GNU}
    ${MASTER_SITE_GNUSTEP}
    ${MASTER_SITE_IFARCHIVE}
    ${MASTER_SITE_KDE}
    ${MASTER_SITE_MOZILLA}
    ${MASTER_SITE_MYSQL}
    ${MASTER_SITE_OPENOFFICE}
    ${MASTER_SITE_PERL_CPAN}
    ${MASTER_SITE_PGSQL}
    ${MASTER_SITE_R_CRAN}
    ${MASTER_SITE_SOURCEFORGE}
    ${MASTER_SITE_SOURCEFORGE_JP}
    ${MASTER_SITE_SUNSITE}
    ${MASTER_SITE_SUSE}
    ${MASTER_SITE_TEX_CTAN}
    ${MASTER_SITE_XCONTRIB}
    ${MASTER_SITE_XEMACS}

    MASTER_SITES=   ${MASTER_SITE_GNU:=subdirectory/name/}
    MASTER_SITES=   ${MASTER_SITE_SOURCEFORGE:=project_name/}

    ${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS}

After the distfile(s) are fetched, their checksum is generated and compared with the checksums stored in the distinfo file. If the checksums don't match, the build is aborted. This is to ensure the same distfile is used for building, and that the distfile wasn't changed, e.g. by some malign force, deliberately changed distfiles on the master distribution site or network lossage.

When the distfiles are present on the local system, they need to be extracted, as they usually come in the form of some compressed archive format.

By default, all DISTFILES are extracted. If you only need some of them, you can set the EXTRACT_ONLY variable to the list of those files.

Extracting the files is usually done by a little program, mk/scripts/extract, which already knows how to extract various archive formats, so most likely you will not need to change anything here. But if you need, the following variables may help you:

If the extract program doesn't serve your needs, you can also override the EXTRACT_CMD variable, which holds the command used for extracting the files. This command is executed in the ${WRKSRC} directory. During execution of this command, the shell variable extract_file holds the absolute pathname of the file that is going to be extracted.

And if that still does not suffice, you can override the do-extract target in the package Makefile.

After extraction, all the patches named by the PATCHFILES, those present in the patches subdirectory of the package as well as in $LOCALPATCHES/$PKGPATH (e.g. /usr/local/patches/graphics/png) are applied. Patchfiles ending in .Z or .gz are uncompressed before they are applied, files ending in .orig or .rej are ignored. Any special options to patch(1) can be handed in PATCH_DIST_ARGS. See Section 9.3, “patches/*” for more details.

By default patch(1) is given special args to make it fail if the patches apply with some lines of fuzz. Please fix (regen) the patches so that they apply cleanly. The rationale behind this is that patches that don't apply cleanly may end up being applied in the wrong place, and cause severe harm there.

This is covered in Chapter 16, Tools needed for building or running.

This phase creates wrapper programs for the compilers and linkers. The following variables can be used to tweak the wrappers.

Most pieces of software need information on the header files, system calls, and library routines which are available on the platform they run on. The process of determining this information is known as configuration, and is usually automated. In most cases, a script is supplied with the distfiles, and its invocation results in generation of header files, Makefiles, etc.

If the package contains a configure script, this can be invoked by setting HAS_CONFIGURE to “yes”. If the configure script is a GNU autoconf script, you should set GNU_CONFIGURE to “yes” instead. What happens in the configure phase is roughly:

    .for d in ${CONFIGURE_DIRS}
            cd ${WRKSRC} && cd ${d} && env ${CONFIGURE_ENV} \
                ${CONFIGURE_SCRIPT} ${CONFIGURE_ARGS}
    .endfor

CONFIGURE_DIRS (default: “.”) is a list of pathnames relative to WRKSRC. In each of these directories, the configure script is run with the environment CONFIGURE_ENV and arguments CONFIGURE_ARGS. The variables CONFIGURE_ENV, CONFIGURE_SCRIPT (default: “./configure”) and CONFIGURE_ARGS may all be changed by the package.

If the program uses an Imakefile for configuration, the appropriate steps can be invoked by setting USE_IMAKE to “yes”. (If you only want the package installed in ${X11PREFIX} but xmkmf not being run, set USE_X11BASE instead.)

For building a package, a rough equivalent of the following code is executed.

    .for d in ${BUILD_DIRS}
            cd ${WRKSRC} && cd ${d} && env ${MAKE_ENV} \
                ${MAKE_PROGRAM} ${BUILD_MAKE_FLAGS} \
                    -f ${MAKE_FILE} ${BUILD_TARGET}
    .endfor

BUILD_DIRS (default: “.”) is a list of pathnames relative to WRKSRC. In each of these directories, MAKE_PROGRAM is run with the environment MAKE_ENV and arguments BUILD_MAKE_FLAGS. The variables MAKE_ENV, BUILD_MAKE_FLAGS, MAKE_FILE and BUILD_TARGET may all be changed by the package.

The default value of MAKE_PROGRAM is “gmake” if USE_TOOLS contains “gmake”, “make” otherwise. The default value of MAKE_FILE is “Makefile”, and BUILD_TARGET defaults to “all”.

[TODO]

Once the build stage has completed, the final step is to install the software in public directories, so users can access the programs and files.

In the install phase, a rough equivalent of the following code is executed. Additionally, before and after this code, much magic is performed to do consistency checks, registering the package, and so on.

    .for d in ${INSTALL_DIRS}
            cd ${WRKSRC} && cd ${d} && env ${MAKE_ENV} \
                ${MAKE_PROGRAM} ${INSTALL_MAKE_FLAGS} \
                    -f ${MAKE_FILE} ${BUILD_TARGET}
    .endfor

The variable's meanings are analogous to the ones in the build phase. INSTALL_DIRS defaults to BUILD_DIRS. INSTALL_TARGET is “install” by default, plus “install.man” if USE_IMAKE is defined.

In the install phase, the following variables are useful. They are all variations of the install(1) command that have the owner, group and permissions preset. INSTALL is the plain install command. The specialized variants, together with their intended use, are:

Some other variables are:

[TODO]

The default set of tools used by pkgsrc is defined in bsd.pkg.mk. This includes standard Unix tools, such as: cat, awk, chmod, test, and so on. These can be seen by running: make show-var VARNAME=USE_TOOLS.

If a package needs a specific program to build then the USE_TOOLS variable can be used to define the tools needed.

In the following examples, the :pkgsrc means to use the pkgsrc version and not the native version for a build dependency. And the :run means that it is used for a run-time dependencies also (and becomes a DEPENDS). The default is a build dependency which can be set with :build. (So in this example, it is the same as gmake:build and pkg-config:build.)

USE_TOOLS+=     mktemp:pkgsrc
USE_TOOLS+=     gmake perl:run pkg-config

When using the tools framework, a TOOLS_PATH.foo variable is defined which contains the full path to the appropriate tool. For example, TOOLS_PATH.bash could be “/bin/bash” on Linux systems.

If you always need a pkgsrc version of the tool at run-time, then just use DEPENDS instead.

When improving or porting pkgsrc to a new platform, have a look at (or create) the corresponding platform specific make file fragment under pkgsrc/mk/tools/tools.${OPSYS}.mk which defines the name of the common tools. For example:

.if exists(/usr/bin/bzcat)
TOOLS_PLATFORM.bzcat?=          /usr/bin/bzcat
.elif exists(/usr/bin/bzip2)
TOOLS_PLATFORM.bzcat?=          /usr/bin/bzip2 -cd
.endif

TOOLS_PLATFORM.true?=           true                    # shell builtin