Darwin 5.x and 6.x are supported. There are two methods of using pkgsrc on Mac OS X, by using a disk image, or a UFS partition.

Before you start, you will need to download and install the Mac OS X Developer Tools from Apple's Developer Connection. See http://developer.apple.com/macosx/ for details. Also, make sure you install X11 for Mac OS X and the X11 SDK from http://www.apple.com/macosx/x11/download/ if you intend to build packages that use the X11 Window System.

If you already have a UFS partition, or have a spare partition that you can format as UFS, it is recommended to use that instead of the disk image. It'll be somewhat faster and will mount automatically at boot time, where you must manually mount a disk image.

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

# ./bootstrap --pkgdbdir /usr/pkg/pkgdb --pkgsrcdir /Volumes/ufs/pkgsrc

FreeBSD 4.7 and 5.0 have been tested and are supported, other versions may work.

Care should be taken so that the tools that this kit installs do not conflict with the FreeBSD userland tools. There are several steps:

Interix is a POSIX-compatible subsystem for the Windows NT kernel, providing a Unix-like environment with a tighter kernel integration than available with Cygwin. It is part of the Windows Services for Unix package, available for free for any licensed copy of Windows 2000, XP (not including XP Home), or 2003. SFU can be downloaded from http://www.microsoft.com/windows/sfu/.

Services for Unix 3.5, current as of this writing, has been tested. 3.0 or 3.1 may work, but are not officially supported. (The main difference in 3.0/3.1 is lack of pthreads.)

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

You will need a working C compiler, either gcc or SGI's MIPS and MIPSpro compiler (cc/c89). Please set the CC environment variable according to your preference. If you do not have a license for the MIPSpro compiler suite, you can download a gcc tardist file from http://freeware.sgi.com/.

Please note that you will need IRIX 6.5.17 or higher, as this is the earliest version of IRIX providing support for if_indextoname(3), if_nametoindex(3), etc.

At this point in time, pkgsrc only supports one ABI at a time. That is, you can not switch between the old 32-bit ABI, the new 32-bit ABI and the 64-bit ABI. If you start out using "abi=n32", that's what all your packages will be built with.

Therefore, please make sure that you have no conflicting CFLAGS in your environment or the /etc/mk.conf. Particularly, make sure that you do not try to link n32 object files with lib64 or vice versa. Check your /etc/compiler.defaults!

If you have the actual pkgsrc tree mounted via NFS from a different host, please make sure to set WRKOBJDIR to a local directory, as it appears that IRIX linker occasionally runs into issues when trying to link over a network-mounted file system.

The bootstrapping process should set all the right options for programs such as imake(1), but you may want to set some options depending on your local setup. Please see pkgsrc/mk/defaults/mk.conf and, of course, your compiler's man pages for details.

If you are using SGI's MIPSPro compiler, please set

PKGSRC_COMPILER=mipspro

in /etc/mk.conf. Otherwise, pkgsrc will assume you are using gcc and may end up passing invalid flags to the compiler. Note that bootstrap should create an appropriate mk.conf.example by default.

If you have both the MIPSPro compiler chain installed as well as gcc, but want to make sure that MIPRPro is used, please set your PATH to not include the location of gcc (often /usr/freeware/bin), and (important) pass the '--preserve-path' flag.

Some versions of Linux (for example Debian GNU/Linux) need either libtermcap or libcurses (libncurses). Installing the distributions libncurses-dev package (or equivalent) should fix the problem.

pkgsrc supports both gcc (GNU Compiler Collection) and icc (Intel C++ Compiler). gcc is the default. icc 8.0 and 8.1 on i386 have been tested.

To bootstrap using icc, assuming the default icc installation directory:

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

icc supports __attribute__, but the GNU configure test uses a nested function, which icc does not support. #undef'ing __attribute__ has the unfortunate side-effect of breaking many of the Linux header files, which cannot be compiled properly without __attribute__. The test must be overridden so that __attribute__ is assumed supported by the compiler.

After bootstrapping, you should set PKGSRC_COMPILER in /etc/mk.conf:

PKGSRC_COMPILER=icc

The default installation directory for icc is /opt/intel_cc_80, which is also the pkgsrc default. If you have installed it into a different directory, set ICCBASE in /etc/mk.conf:

ICCBASE=/opt/icc

pkgsrc uses the static linking method of the runtime libraries provided by icc, so binaries can be run on other systems which do not have the shared libraries installed.

Libtool, however, extracts a list of libraries from the ld(1) command run when linking a C++ shared library and records it, throwing away the -Bstatic and -Bdynamic options interspersed between the libraries. This means that libtool-linked C++ shared libraries will have a runtime dependency on the icc libraries until this is fixed in libtool.

OpenBSD 3.0 and 3.2 are tested and supported.

Care should be taken so that the tools that this kit installs do not conflict with the OpenBSD userland tools. There are several steps:

Solaris 2.6 through 9 are supported on both x86 and sparc. You will need a working C compiler. Both gcc 2.95.3 and Sun WorkShop 5 have been tested.

The following packages are required on Solaris 8 for the bootstrap process and to build packages.

Please note the use of GNU binutils on Solaris is not supported.

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

CFLAGS= -xtarget=ultra -xarch=v9

Precompiled packages are stored on ftp.NetBSD.org and its mirrors in the directory /pub/NetBSD/packages/<OSVERSION>/<ARCH>/ for anonymous FTP access. OSVERSION is the NetBSD version (uname -r), ARCH is the architecture (uname -p). In that directory, there is a subdirectory for each category plus a subdirectory All which includes the actual binaries in .tgz files. The category subdirectories use symbolic links to those files (this is the same directory layout as in /usr/pkgsrc/packages).

This same directory layout applies for CD-ROM distributions, only that the directory may be rooted somewhere else, probably somewhere below /cdrom. Please consult your CD-ROMs documentation for the exact location.

If you have the files on a CD-ROM or downloaded them to your hard disk, you can install them with the following command (be sure to su to root first):

# pkg_add /path/to/package.tgz

If you have FTP access and you don't want to download the packages via FTP prior to installation, you can do this automatically by giving pkg_add an FTP URL:

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

Note that any prerequisite packages needed to run the package in question will be installed, too, assuming they are present where you install from.

To save some typing, you can set the PKG_PATH environment variable to a semicolon-separated list of paths (including remote URLs); trailing slashes are not allowed.

Additionally to the All directory there exists a vulnerable directory to which binary packages with known vulnerabilities are moved, since removing them could cause missing dependencies. To use these packages, add the vulnerable directory to your PKG_PATH. However, you should run security/audit-packages regularly, especially after installing new packages, and verify that the vulnerabilities are acceptable for your configuration. An example PKG_PATH would be: ftp://ftp.NetBSD.org/pub/NetBSD/packages/<OSVERSION>/<ARCH>/All;ftp://ftp.NetBSD.org/pub/NetBSD/packages/<OSVERSION>/<ARCH>/vulnerable Please note that semicolon (';') is a shell meta-character, so you'll probably have to quote it.

After you've installed packages, be sure to have /usr/pkg/bin and /usr/pkg/sbin in your PATH so you can actually start the just installed program.

Please pay very careful attention to the warnings expressed in the pkg_add(1) manual page about the inherent dangers of installing binary packages which you did not create yourself, and the security holes that can be introduced onto your system by indiscriminate adding of such files.

To build packages from source on a NetBSD system the “comp” and the “text” distribution sets must be installed. If you want to build X11-related packages the “xbase” and “xcomp” distribution sets are required, too.

The first step for building a package is downloading the distfiles (i.e. the unmodified source). If they have not yet been downloaded, pkgsrc will fetch them automatically.

You can overwrite some of the major distribution sites to fit to sites that are close to your own. Have a look at pkgsrc/mk/defaults/mk.conf to find some examples — in particular, look for the MASTER_SORT, MASTER_SORT_REGEX and INET_COUNTRY definitions. This may save some of your bandwidth and time.

You can change these settings either in your shell's environment, or, if you want to keep the settings, by editing the /etc/mk.conf file, and adding the definitions there.

If you don't have a permanent Internet connection and you want to know which files to download, make fetch-list will tell you what you'll need. Put these distfiles into /usr/pkgsrc/distfiles.

Assuming that the distfile has been fetched (see previous section), become root and change into the relevant directory and run make.

For example, type

% cd misc/figlet
% make

at the shell prompt to build the various components of the package, and

# make install

to install the various components into the correct places on your system. Installing the package on your system requires you to be root. However, pkgsrc has a just-in-time-su feature, which allows you to only become root for the actual installation step

Taking the figlet utility as an example, we can install it on our system by building as shown in Appendix B, Build logs.

The program is installed under the default root of the packages tree - /usr/pkg. Should this not conform to your tastes, set the LOCALBASE variable in your environment, and it will use that value as the root of your packages tree. So, to use /usr/local, set LOCALBASE=/usr/local in your environment. Please note that you should use a directory which is dedicated to packages and not shared with other programs (i.e., do not try and use LOCALBASE=/usr). Also, you should not try to add any of your own files or directories (such as src/, obj/, or pkgsrc/) below the LOCALBASE tree. This is to prevent possible conflicts between programs and other files installed by the package system and whatever else may have been installed there.

Some packages look in /etc/mk.conf to alter some configuration options at build time. Have a look at pkgsrc/mk/defaults/mk.conf to get an overview of what will be set there by default. Environment variables such as LOCALBASE can be set in /etc/mk.conf to save having to remember to set them each time you want to use pkgsrc.

Occasionally, people want to “look under the covers” to see what is going on when a package is building or being installed. This may be for debugging purposes, or out of simple curiosity. A number of utility values have been added to help with this.

If you want to install a binary package that you've either created yourself (see next section), that you put into pkgsrc/packages manually or that is located on a remote FTP server, you can use the "bin-install" target. This target will install a binary package - if available - via pkg_add(1), else do a make package. The list of remote FTP sites searched is kept in the variable BINPKG_SITES, which defaults to ftp.NetBSD.org. Any flags that should be added to pkg_add(1) can be put into BIN_INSTALL_FLAGS. See pkgsrc/mk/defaults/mk.conf for more details.

A final word of warning: If you set up a system that has a non-standard setting for LOCALBASE, be sure to set that before any packages are installed, as you can not use several directories for the same purpose. Doing so will result in pkgsrc not being able to properly detect your installed packages, and fail miserably. Note also that precompiled binary packages are usually built with the default LOCALBASE of /usr/pkg, and that you should not install any if you use a non-standard LOCALBASE.

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

As /usr/pkg will be completely deleted at the start of bulk builds, make sure your login shell is placed somewhere else. Either drop it into /usr/local/bin (and adjust your login shell in the passwd file), or (re-)install it via pkg_add(1) from /etc/rc.local, so you can login after a reboot (remember that your current process won't die if the package is removed, you just can't start any new instances of the shell any more). Also, if you use NetBSD earlier than 1.5, or you still want to use the pkgsrc version of ssh for some reason, be sure to install ssh before starting it from rc.local:

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

Not doing so will result in you being not able to log in via ssh after the bulk build is finished or if the machine gets rebooted or crashes. You have been warned! :)

Make sure you don't need any of the packages still installed.

Be sure to remove all other things that might interfere with builds, like some libs installed in /usr/local, etc. then become root and type:

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

If for some reason your last build didn't complete (power failure, system panic, ...), you can continue it by running:

# sh mk/bulk/build restart

At the end of the bulk build, you will get a summary via mail, and find build logs in the directory specified by FTP in the build.conf file.

The bulk builds consist of three steps:

During the build, a list of broken packages will be compiled in /usr/pkgsrc/.broken (or .../.broken.${MACHINE} if OBJMACHINE is set), individual build logs of broken builds can be found in the package's directory. These files are used by the bulk-targets to mark broken builds to not waste time trying to rebuild them, and they can be used to debug these broken package builds later.

Currently, roughly the following requirements are valid for NetBSD 2.0/i386:

Note that all pkgs will be de-installed as soon as they are turned into a binary package, and that sources are removed, so there is no excessively huge demand to disk space. Afterwards, if the package is needed again, it will be installed via pkg_add(1) instead of building again, so there are no cycles wasted by recompiling.

If you don't want all the packages nuked from a machine (rendering it useless for anything but pkg compiling), there is the possibility of doing the package bulk build inside a chroot environment.

The first step is to set up a chroot sandbox, e.g. /usr/sandbox. This can be done by using null mounts, or manually.

There is a shell script called pkgsrc/mk/bulk/mksandbox which will set up the sandbox environment using null mounts. It will also create a script called sandbox in the root of the sandbox environment, which will allow the null mounts to be activated using the sandbox mount command and deactivated using the sandbox umount command.

To set up a sandbox environment by hand, after extracting all the sets from a NetBSD installation or doing a make distribution DESTDIR=/usr/sandbox in /usr/src/etc, be sure the following items are present and properly configured:

When the chroot sandbox is set up, you can start the build with the following steps:

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

This will just jump inside the sandbox and start building. At the end of the build, mail will be sent with the results of the build. Created binary pkgs will be in /usr/sandbox/usr/pkgsrc/packages (wherever that points/mounts to/from).

In addition to building a complete set of all packages in pkgsrc, the pkgsrc/mk/bulk/build script may be used to build a subset of the packages contained in pkgsrc. By setting SPECIFIC_PKGS in /etc/mk.conf, the variables

will define the set of packages which should be built. The bulk build code will also include any packages which are needed as dependencies for the explicitly listed packages.

One use of this is to do a bulk build with SPECIFIC_PKGS in a chroot sandbox periodically to have a complete set of the binary packages needed for your site available without the overhead of building extra packages that are not needed.

This section describes how pkgsrc developers can upload binary pkgs built by bulk builds to ftp.NetBSD.org.

If you would like to automatically create checksum files for the binary packages you intend to upload, remember to set MKSUMS=yes in your mk/bulk/build.conf.

If you would like to PGP sign the checksum files (highly recommended!), remember to set SIGN_AS=username@NetBSD.org in your mk/bulk/build.conf. This will prompt you for your GPG password to sign the files before uploading everything.

Then, make sure that you have RSYNC_DST set properly in your mk/bulk/build.conf file, i.e. adjust it to something like one of the following:

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

Please use appropriate values for "pkgsrc-200xQy", "NetBSD-a.b.c" and "arch" here. If your login on ftp.NetBSD.org is different from CVS_USER, write your login directly into the variable, e.g. my local account is "feyrer", but for my login "hubertf", I use:

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

A separate upload directory is used here to allow "closing" the directory during upload. To do so, run the following command on ftp.NetBSD.org next:

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

Please note that /pub/NetBSD/packages is only appropriate for packages for the NetBSD operating system. Binary packages for other operating systems should go into /pub/pkgsrc.

Before uploading the binary pkgs, ssh authentication needs to be set up. This example shows how to set up temporary keys for the root account inside the sandbox (assuming that no keys should be present there usually):

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

Now take the output of id-dsa.pub and append it to your ~/.ssh/authorized_keys file on ftp.NetBSD.org. You can remove the key after the upload is done!

Next, test if your ssh connection really works:

chroot-# ssh ftp.NetBSD.org date 

Use "-l yourNetBSDlogin" here as appropriate!

Now after all this works, you can exit the sandbox and start the upload:

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

The upload process may take quite some time. Use ls(1) or du(1) on the FTP server to monitor progress of the upload. The upload script will take care of not uploading restricted packages and putting vulnerable packages into the vulnerable subdirectory.

After the upload has ended, first thing is to revoke ssh access:

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

Use whatever is needed to remove the key you've entered before! Last, move the uploaded packages out of the upload directory to have them accessible to everyone:

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

Complete documentation for cdpack is found in the cdpack(1) man page. The following short example assumes that the binary packages are left in /usr/pkgsrc/packages/All and that sufficient disk space exists in /u2 to hold the ISO 9660 images.

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

If you wish to include a common set of files (COPYRIGHT, README, etc.) on each CD in the collection, then you need to create a directory which contains these files. e.g.

# 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

Now create the images:

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

Each image will contain README, COPYING, and bin/myscript in their root directories.

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
      

When you add a string to an external list (example 3), it must be quoted. In all other cases, you must not add a quoting level. You must not merge internal and external lists, unless you are sure that all entries are correctly interpreted in both lists.

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

This code converts the internal list INT_LIST into the external list EXT_LIST. As the elements of an internal list are unquoted they must be quoted here. The reason for appending "" is explained below.

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
        env ${EXT_LIST} /bin/sh -c 'echo "$$string"; echo "$$x"'
      

Example 1 leads to a syntax error in the shell, as the characters are just copied.

Example 2 leads to a syntax error too, and if you leave out the last " character from ${STRING}, date(1) will be executed. The $HOME shell variable would be evaluated, too.

Example 3 outputs each space character preceded by a backslash (or not), depending on the implementation of the echo(1) command.

Example 4 handles correctly every string that does not start with a dash. In that case, the result depends on the implementation of the echo(1) command. As long as you can guarantee that your input does not start with a dash, this form is appropriate.

Example 5 handles even the case of a leading dash correctly.

The EXT_LIST does not need to be quoted because the quoting has already been done when adding elements to the list.

As internal lists shall not be passed to the shell, there is no example for it.

There are many possible sources of wrongly quoted variables. This section lists some of the commonly known ones.

The pkgsrc bmake program does not handle the following assignment correctly. In case _othervar_ contains a ``-'' character, one of the closing braces is included in ${VAR} after this code executes.

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

For a more complex code snippet and a workaround, see the package regress/make-quoting, testcase bug1.

The following real-life example buildlink3.mk is taken from pkgsrc/graphics/tiff:

# $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_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/+$//} 

The header and footer manipulate BUILDLINK_DEPTH, which is common across all buildlink3.mk files and is used to track at what depth we are including buildlink3.mk files.

The first section controls if the dependency on pkg is added. BUILDLINK_DEPENDS is the global list of packages for which dependencies are added by buildlink3.

The second section advises pkgsrc that the buildlink3.mk file for pkg has been included at some point. BUILDLINK_PACKAGES is the global list of packages for which buildlink3.mk files have been included. It must always be appended to within a buildlink3.mk file.

The third section is protected from multiple inclusion and controls how the dependency on pkg is added. Several important variables are set in the section:

The following variables are all optionally defined within this second section (protected against multiple inclusion) and control which package files are symlinked into ${BUILDLINK_DIR} and how their names are transformed during the symlinking:

The last section includes any buildlink3.mk needed for pkg's library dependencies. Including these buildlink3.mk files means that the headers and libraries for these dependencies are also symlinked into ${BUILDLINK_DIR} whenever the pkg buildlink3.mk file is included.

There are two situations that require increasing the dependency listed in BUILDLINK_DEPENDS.pkg after a package update:

In these cases, BUILDLINK_DEPENDS.pkg should be adjusted to require at least the new package version. In some cases, the packages that depend on this new version may need their PKGREVISIONs increased and, if they have buildlink3.mk files, their BUILDLINK_DEPENDS.pkg adjusted, too. This is needed so that binary packages made using it will require the correct package dependency and not settle for an older one which will not contain the necessary shared libraries.

Please take careful consideration before adjusting BUILDLINK_DEPENDS.pkg as we don't want to cause unneeded package deletions and rebuilds. In many cases, new versions of packages work just fine with older dependencies. See Section 15.1.4, “Handling dependencies” for more information about dependencies on other packages, including the BUILDLINK_RECOMMENDED and RECOMMENDED definitions.

The following is the recommended template for builtin.mk files:

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

The first section sets IS_BUILTIN.pkg depending on if pkg really exists in the base system. This should not be a base system software with similar functionality to pkg; it should only be “yes” if the actual package is included as part of the base system. This variable is only used internally within the builtin.mk file.

The second section sets BUILTIN_PKG.pkg to the version of pkg in the base system if it exists (if IS_BUILTIN.pkg is “yes”). This variable is only used internally within the builtin.mk file.

The third section sets USE_BUILTIN.pkg and is required in all builtin.mk files. The code in this section must make the determination whether the built-in software is adequate to satisfy the dependencies listed in BUILDLINK_DEPENDS.pkg. This is typically done by comparing BUILTIN_PKG.pkg against each of the dependencies in BUILDLINK_DEPENDS.pkg. USE_BUILTIN.pkg must be set to the correct value by the end of the builtin.mk file. Note that USE_BUILTIN.pkg may be “yes” even if IS_BUILTIN.pkg is “no” because we may make the determination that the built-in version of the software is similar enough to be used as a replacement.

The last section is guarded by CHECK_BUILTIN.pkg, and includes code that uses the value of USE_BUILTIN.pkg set in the previous section. This typically includes, e.g., adding additional dependency restrictions and listing additional files to symlink into ${BUILDLINK_DIR} (via BUILDLINK_FILES.pkg).

When building packages, it's possible to choose whether to set a global preference for using either the built-in (native) version or the pkgsrc version of software to satisfy a dependency. This is controlled by setting PREFER_PKGSRC and PREFER_NATIVE. These variables take values of either “yes”, “no”, or a list of packages. PREFER_PKGSRC tells pkgsrc to use the pkgsrc versions of software, while PREFER_NATIVE tells pkgsrc to use the built-in versions. Preferences are determined by the most specific instance of the package in either PREFER_PKGSRC or PREFER_NATIVE. If a package is specified in neither or in both variables, then PREFER_PKGSRC has precedence over PREFER_NATIVE. For example, to require using pkgsrc versions of software for all but the most basic bits on a NetBSD system, you can set:

        PREFER_PKGSRC=  yes
        PREFER_NATIVE=  getopt skey tcp_wrappers
      

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

The following variables can be set to request the creation of directories anywhere in the file system:

Creating non-empty files outside the installation prefix is tricky because the PLIST forces all files to be inside it. To overcome this problem, the only solution is to extract the file in the known place (i.e., inside the installation prefix) and copy it to the appropriate location during installation (done by the installation scripts generated by pkginstall). We will call the former the master file in the following paragraphs, which describe the variables that can be used to automatically and consistently handle files outside the installation prefix:

As said before, the PKG_SYSCONFDIR variable specifies where configuration files shall be installed. Its contents are set based upon the following variables:

Based on the above variables, pkginstall determines the value of PKG_SYSCONFDIR, which is the only variable that can be used within a package to refer to its configuration directory. The algorithm used to set its value is basically the following:

It is worth mentioning that ${PKG_SYSCONFDIR} is automatically added to OWN_DIRS. See Section 12.1.1, “Directory manipulation” what this means.

Given that pkgsrc (and users!) expect configuration files to be in a known place, you need to teach each package where it shall install its files. In some cases you will have to patch the package Makefiles to achieve it. If you are lucky, though, it may be as easy as passing an extra flag to the configuration script; this is the case of GNU Autoconf- generated files:

CONFIGURE_ARGS+= --sysconfdir=${PKG_SYSCONFDIR}

Note that this specifies where the package has to look for its configuration files, not where they will be originally installed (although the difference is never explicit, unfortunately).

As said before, pkginstall automatically handles configuration files. This means that the packages themselves must not touch the contents of ${PKG_SYSCONFDIR} directly. Bad news is that many software installation scripts will, out of the box, mess with the contents of that directory. So what is the correct procedure to fix this issue?

You must teach the package (usually by manually patching it) to install any configuration files under the examples hierarchy, share/examples/${PKGBASE}/. This way, the PLIST registers them and the administrator always has the original copies available.

Once the required configuration files are in place (i.e., under the examples hierarchy), the pkginstall framework can use them as master copies during the package installation to update what is in ${PKG_SYSCONFDIR}. To achieve this, the variables CONF_FILES and CONF_FILES_PERMS are used. Check out Section 12.1.2, “File manipulation” for information about their syntax and their purpose. Here is an example, taken from the mail/mutt package:

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

Note that the EGDIR variable is specific to that package and has no meaning outside it.

The automatic copying of config files can be toggled by setting the environment variable PKG_CONFIG prior to package installation.

The automatic copying of config files can be toggled by setting the environment variable PKG_RCD_SCRIPTS prior to package installation. Note that the scripts will be always copied inside the examples hierarchy, ${PREFIX}/share/examples/rc.d/, no matter what the value of this variable is.

The automatic registration of shell interpreters can be disabled by the administrator by setting the PKG_REGISTER_SHELLS environment variable to NO.

The problem with package-defined variables that can be overridden via MAKECONF or /etc/mk.conf is that make(1) expands a variable as it is used, but evaluates preprocessor-like statements (.if, .ifdef and .ifndef) as they are read. So, to use any variable (which may be set in /etc/mk.conf) in one of the .if* statements, the file /etc/mk.conf must be included before that .if* statement.

Rather than having a number of ad-hoc ways of including /etc/mk.conf, should it exist, or MAKECONF, should it exist, include the pkgsrc/mk/bsd.prefs.mk file in the package Makefile before any preprocessor-like .if, .ifdef, or .ifndef statements:

.include "../../mk/bsd.prefs.mk"
    
    .if defined(USE_MENUS)
      ...
    .endif

If you wish to set the CFLAGS variable in /etc/mk.conf, please make sure to use:

CFLAGS+=  -your -flags

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

Documentation should be installed into ${PREFIX}/share/doc/${PKGBASE} or ${PREFIX}/share/doc/${PKGNAME} (the latter includes the version number of the package).

Some licenses restrict how software may be re-distributed. In order to satisfy these restrictions, the package system defines five make variables that can be set to note these restrictions:

Please note that the use of NO_PACKAGE, IGNORE, NO_CDROM, or other generic make variables to denote restrictions is deprecated, because they unconditionally prevent users from generating binary packages!

Your package may depend on some other package being present - and there are various ways of expressing this dependency. pkgsrc supports the BUILD_DEPENDS and DEPENDS definitions, the USE_TOOLS definition, as well as dependencies via buildlink3.mk, which is the preferred way to handle dependencies, and which uses the variables named above. See Chapter 11, Buildlink methodology for more information.

The basic difference between the two variables is as follows: The DEPENDS definition registers that pre-requisite in the binary package so it will be pulled in when the binary package is later installed, whilst the BUILD_DEPENDS definition does not, marking a dependency that is only needed for building the package.

This means that if you only need a package present whilst you are building, it should be noted as a BUILD_DEPENDS.

The format for a BUILD_DEPENDS and a DEPENDS definition is:

<pre-req-package-name>:../../<category>/<pre-req-package>

Please note that the “pre-req-package-name” may include any of the wildcard version numbers recognized by pkg_info(1).

If your package needs files from another package to build, see the first part of the “do-configure” target print/ghostscript5 package (it relies on the jpeg sources being present in source form during the build):

if [ ! -e ${_PKGSRCDIR}/graphics/jpeg/${WRKDIR:T}/jpeg-6b ]; then \
          cd ${_PKGSRCDIR}/../../graphics/jpeg && ${MAKE} extract;              \
    fi

If you build any other packages that way, please make sure the working files are deleted too when this package's working files are cleaned up. The easiest way to do so is by adding a pre-clean target:

pre-clean:
          cd ${_PKGSRCDIR}/../../graphics/jpeg && ${MAKE} clean

Please also note the BUILD_USES_MSGFMT and BUILD_USES_GETTEXT_M4 definitions, which are provided as convenience definitions. The former works out whether msgfmt(1) is part of the base system, and, if it isn't, installs the devel/gettext package. The latter adds a build dependency on either an installed version of an older gettext package, or if it isn't, installs the devel/gettext-m4 package.

Your package may conflict with other packages a user might already have installed on his system, e.g. if your package installs the same set of files like another package in our pkgsrc tree.

In this case you can set CONFLICTS to a space-separated list of packages (including version string) your package conflicts with.

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

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

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

CONFLICTS=      Xaw3d-[0-9]*

Packages will automatically conflict with other packages with the name prefix and a different version string. “Xaw3d-1.5” e.g. will automatically conflict with the older version “Xaw3d-1.3”.

There are several reasons why a package might be instructed to not build under certain circumstances. If the package builds and runs on most platforms, the exceptions should be noted with NOT_FOR_PLATFORM. If the package builds and runs on a small handful of platforms, set ONLY_FOR_PLATFORM instead. Both ONLY_FOR_PLATFORM and NOT_FOR_PLATFORM are OS triples (OS-version-platform) that can use glob-style wildcards.

If the package should be skipped (for example, because it provides functionality already provided by the system), set PKG_SKIP_REASON to a descriptive message. If the package should fail because some preconditions are not met, set PKG_FAIL_REASON to a descriptive message.

To ensure that a package may not be deleted, once it has been installed, the PKG_PRESERVE definition should be set in the package Makefile. This will be carried into any binary package that is made from this pkgsrc entry. A “preserved” package will not be deleted using pkg_delete(1) unless the “-f” option is used.

When a vulnerability is found, this should be noted in localsrc/security/advisories/pkg-vulnerabilities, and after committing that file, use make upload in the same directory to update the file on ftp.NetBSD.org.

After fixing the vulnerability by a patch, its PKGREVISION should be increased (this is of course not necessary if the problem is fixed by using a newer release of the software). In addition, if a buildlink3.mk file exists for an affected package, a corresponding BUILDLINK_RECOMMENDED.pkg entry should be added or updated in it.

Also, if the fix should be applied to the stable pkgsrc branch, be sure to submit a pullup request!

Binary packages already on ftp.NetBSD.org will be handled semi-automatically by a weekly cron job.

Some source files trigger bugs in the compiler, based on combinations of compiler version and architecture and almost always relation to optimisation being enabled. Common symptoms are gcc internal errors or never finishing compiling a file.

Typically, a workaround involves testing the MACHINE_ARCH and compiler version, disabling optimisation for that file/MACHINE_ARCH/compiler combination, and documenting it in pkgsrc/doc/HACKS. See that file for a number of examples!

When making fixes to an existing package it can be useful to change the version number in PKGNAME. To avoid conflicting with future versions by the original author, a “nb1”, “nb2”, ... suffix can be used on package versions by setting PKGREVISION=1 (2, ...). The “nb” is treated like a “.” by the pkg tools. e.g.

  DISTNAME= foo-17.42
    PKGREVISION=  9

will result in a PKGNAME of “foo-17.42nb9”.

When a new release of the package is released, the PKGREVISION should be removed, e.g. on a new minor release of the above package, things should be like:

DISTNAME=   foo-17.43

One appealing feature of pkgsrc is that it runs on many different platforms. As a result, it is important to ensure, where possible, that packages in pkgsrc are portable. There are some particular details you should pay attention to while working on pkgsrc.

${INSTALL_DATA_DIR} ${PREFIX}/dir1
${INSTALL_DATA_DIR} ${PREFIX}/dir2

If you need to download from a dynamic URL you can set DYNAMIC_MASTER_SITES and a make fetch will call files/getsite.sh with the name of each file to download as an argument, expecting it to output the URL of the directory from which to download it. graphics/ns-cult3d is an example of this usage.

If the download can't be automated, because the user must submit personal information to apply for a password, or must pay for the source, or whatever, you can set _FETCH_MESSAGE to a macro which displays a message explaining the situation. _FETCH_MESSAGE must be executable shell commands, not just a message. (Generally, it executes ${ECHO}). As of this writing, the following packages use this: cad/simian, devel/ipv6socket, emulators/vmware-module, fonts/acroread-jpnfont, multimedia/realplayer, sysutils/storage-manager, www/ap-aolserver, www/openacs. Try to be consistent with them.

Sometimes authors of a software package make some modifications after the software was released, and they put up a new distfile without changing the package's version number. If a package is already in pkgsrc at that time, the checksum will no longer match. The contents of the new distfile should be compared against the old one before changing anything, to make sure the distfile was really updated on purpose, and that no trojan horse or so crept in. Then, the correct way to work around this is to set DIST_SUBDIR to a unique directory name, usually based on PKGNAME_NOREV. In case this happens more often, PKGNAME can be used (thus including the nbX suffix) or a date stamp can be appended, like ${PKGNAME_NOREV}-YYYYMMDD. Do not forget regenerating the distinfo file after that, since it contains the DIST_SUBDIR path in the filenames. Furthermore, a mail to the package's authors seems appropriate telling them that changing distfiles after releases without changing the file names is not good practice.

pkgsrc supports many different machines, with different object formats like a.out and ELF, and varying abilities to do shared library and dynamic loading at all. To accompany this, varying commands and options have to be passed to the compiler, linker, etc. to get the Right Thing, which can be pretty annoying especially if you don't have all the machines at your hand to test things. The devel/libtool pkg can help here, as it just “knows” how to build both static and dynamic libraries from a set of source files, thus being platform-independent.

Here's how to use libtool in a pkg in seven simple steps:

Add USE_LIBTOOL=yes to the package Makefile. This will override the package's own libtool in most cases. For older libtool using packages, libtool is made by ltconfig script during the do-configure step; you can check the libtool script location by doing make configure; find work*/ -name libtool.

LIBTOOL_OVERRIDE specifies which libtool scripts, relative to WRKSRC, to override. By default, it is set to “libtool */libtool */*/libtool”. If this does not match the location of the package's libtool script(s), set it as appropriate.

If you do not need *.a static libraries built and installed, then use SHLIBTOOL_OVERRIDE instead.

If your package makes use of the platform-independent library for loading dynamic shared objects, that comes with libtool (libltdl), you should include devel/libltdl/buildlink3.mk.

Some packages use libtool incorrectly so that the package may not work or build in some circumstances. Some of the more common errors are:

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

For packages that need only autoconf:

AUTOCONF_REQD=    2.50     # if default version is not good enough
USE_TOOLS+=     autoconf   # use "autoconf213" for autoconf-2.13
...

pre-configure:
          cd ${WRKSRC}; autoconf

...

and for packages that need automake and autoconf:

AUTOMAKE_REQD=  1.7.1      # if default version is not good enough
USE_TOOLS+=     automake   # use "automake14" for automake-1.4
...

pre-configure:
          cd ${WRKSRC};                                           \
          aclocal; autoheader;                                    \
          automake -a --foreign -i; autoconf

...

Packages which use GNU Automake will almost certainly require GNU Make.

There are times when the configure process makes additional changes to the generated files, which then causes the build process to try to re-execute the automake sequence. This is prevented by touching various files in the configure stage. If this causes problems with your package you can set AUTOMAKE_OVERRIDE=NO in the package Makefile.

To port an application to NetBSD, it's usually necessary for the compiler to be able to judge the system on which it's compiling, and we use definitions so that the C pre-processor can do this.

To test whether you are working on a 4.4 BSD-derived system, you should use the BSD definition, which is defined in <sys/param.h> on said systems.

#include <sys/param.h>

and then you can surround the BSD-specific parts of your package's C/C++ code using this conditional:

#if (defined(BSD) && BSD >= 199306)
    ...
#endif

Please use the “__NetBSD__” definition sparingly - it should only apply to features of NetBSD that are not present in other 4.4-lite-derived BSDs.

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

The INTERACTIVE_STAGE definition is provided to notify the pkgsrc mechanism of an interactive stage which will be needed, and this should be set in the package's Makefile, e.g.:

INTERACTIVE_STAGE= build

Multiple interactive stages can be specified:

INTERACTIVE_STAGE= configure install

A package may be covered by a license which the user has or has not agreed to accept. For these cases, pkgsrc contains a mechanism to note that a package is covered by a particular license, and the package cannot be built unless the user has accepted the license. (Installation of binary packages are not currently subject to this mechanism.) Packages with licenses that are either Open Source according to the Open Source Initiative or Free according to the Free Software Foundation will not be marked with a license tag. Packages with licenses that have not been determined to meet either definition will be marked with a license tag referring to the license. This will prevent building unless pkgsrc is informed that the license is acceptable, and enables displaying the license.

The license tag mechanism is intended to address copyright-related issues surrounding building, installing and using a package, and not to address redistribution issues (see RESTRICTED and NO_SRC_ON_FTP, etc.). However, the above definition of licenses for which tags are not needed implies that packages with redistribution restrictions should have tags.

Denoting that a package is covered by a particular license is done by placing the license in pkgsrc/licenses and setting the LICENSE variable to a string identifying the license, e.g. in graphics/xv:

LICENSE=        xv-license

When trying to build, the user will get a notice that the package is covered by a license which has not been accepted:

% make
===> xv-3.10anb9 has an unacceptable license: xv-license.
===>     To view the license, enter "/usr/bin/make show-license".
===>     To indicate acceptance, add this line to your /etc/mk.conf:
===>     ACCEPTABLE_LICENSES+=xv-license
*** Error code 1

The license can be viewed with make show-license, and if it is considered appropriate, the line printed above can be added to /etc/mk.conf to indicate acceptance of the particular license:

ACCEPTABLE_LICENSES+=xv-license

When adding a package with a new license, the license text should be added to pkgsrc/licenses for displaying. A list of known licenses can be seen in this directory as well as by looking at the list of (commented out) ACCEPTABLE_LICENSES variable settings in pkgsrc/mk/defaults/mk.conf.

The use of LICENSE=shareware, LICENSE=no-commercial-use, and similar language is deprecated because it does not crisply refer to a particular license text. Another problem with such usage is that it does not enable a user to denote acceptance of the license for a single package without accepting the same license text for another package. In particular, this can be inappropriate when e.g. one accepts a particular license to indicate to pkgsrc that a fee has been paid.

Certain packages, most of them in the games category, install a score file that allows all users on the system to record their highscores. In order for this to work, the binaries need to be installed setgid and the score files owned by the appropriate group and/or owner (traditionally the "games" user/group). The following variables, documented in more detail in mk/defaults/mk.conf, control this behaviour: SETGIDGAME, GAMEDATAMODE, GAMEGRP, GAMEMODE, GAMEOWN.

Note that per default, setgid installation of games is disabled; setting SETGIDGAME=YES will set all the other variables accordingly.

A package should therefor never hard code file ownership or access permissions but rely on INSTALL_GAME and INSTALL_GAME_DATA to set these correctly.

If your package contains interpreted perl scripts, set REPLACE_PERL to ensure that the proper interpreter path is set. REPLACE_PERL should contain a list of scripts, relative to WRKSRC, that you want adjusted.

Your package may also contain scripts with hardcoded paths to other interpreters besides (or as well as) perl. To correct the full pathname to the script interpreter, you need to set the following definitions in your Makefile (we shall use tclsh in this example):

  REPLACE_INTERPRETER+=     tcl
    _REPLACE.tcl.old=     .*/bin/tclsh
    _REPLACE.tcl.new=     ${PREFIX}/bin/tclsh
    _REPLACE_FILES.tcl=   ...list of tcl scripts which need to be fixed,
                          relative to ${WRKSRC}, just as in REPLACE_PERL

Makefiles of packages providing perl5 modules should include the Makefile fragment ../../lang/perl5/module.mk. It provides a do-configure target for the standard perl configuration for such modules as well as various hooks to tune this configuration. See comments in this file for details.

Perl5 modules will install into different places depending on the version of perl used during the build process. To address this, pkgsrc will append lines to the PLIST corresponding to the files listed in the installed .packlist file generated by most perl5 modules. This is invoked by defining PERL5_PACKLIST to a space-separated list of paths to packlist files, e.g.:

PERL5_PACKLIST=   ${PERL5_SITEARCH}/auto/Pg/.packlist

The variables PERL5_SITELIB, PERL5_SITEARCH, and PERL5_ARCHLIB represent the three locations in which perl5 modules may be installed, and may be used by perl5 packages that don't have a packlist. These three variables are also substituted for in the PLIST.

Some packages install info files or use the “makeinfo” or “install-info” commands. Each of the info files:

INFO_DIR defaults to “info” and can be overridden in the package Makefile. INSTALL and DEINSTALL scripts will be generated to handle registration of the info files in the Info directory file. The “install-info” command used for the info files registration is either provided by the system, or by a special purpose package automatically added as dependency if needed.

A package which needs the “makeinfo” command at build time must define the variable USE_MAKEINFO in its Makefile. If a minimum version of the “makeinfo” command is needed it should be noted with the TEXINFO_REQD variable in the package Makefile. By default, a minimum version of 3.12 is required. If the system does not provide a makeinfo command or if it does not match the required minimum, a build dependency on the devel/gtexinfo package will be added automatically.

The build and installation process of the software provided by the package should not use the install-info command as the registration of info files is the task of the package INSTALL script, and it must use the appropriate makeinfo command.

To achieve this goal, the pkgsrc infrastructure creates overriding scripts for the install-info and makeinfo commands in a directory listed early in PATH.

The script overriding install-info has no effect except the logging of a message. The script overriding makeinfo logs a message and according to the value of USE_MAKEINFO and TEXINFO_REQD either run the appropriate makeinfo command or exit on error.

If a package installs .schemas or .entries files, used by GConf2, you need to take some extra steps to make sure they get registered in the database:

If a package installs .omf files, used by scrollkeeper, you need to take some extra steps to make sure they get registered in the database:

If a package installs font files, you will need to rebuild the fonts database in the directory where they get installed at installation and deinstallation time. This can be automatically done by using mk/fonts.mk, which you need to include in your Makefile.

When the file is included, you can list the directories where fonts are installed in the FONTS_type_DIRS variables, where type can be one of “TTF”, “TYPE1” or “X11”. Also make sure that the database file fonts.dir is not listed in the PLIST.

Note that you should not create new directories for fonts; instead use the standard ones to avoid that the user needs to manually configure his X server to find them.

If a package installs GTK2 immodules or loaders, you need to take some extra steps to get them registered in the GTK2 database properly:

If a package installs SGML or XML data files that need to be registered in system-wide catalogs (like DTDs, sub-catalogs, etc.), you need to take some extra steps:

If a package provides extensions to the MIME database by installing .xml files inside ${PREFIX}/share/mime/packages, you need to take some extra steps to ensure that the database is kept consistent with respect to these new files:

If a package uses intltool during its build, include the ../../textproc/intltool/buildlink3.mk file, which forces it to use the intltool package provided by pkgsrc, instead of the one bundled with the distribution file.

This tracks intltool's build-time dependencies and uses the latest available version; this way, the package benefits of any bug fixes that may have appeared since it was released.

If a package contains a rc.d script, it won't be copied into the startup directory by default, but you can enable it, by adding the option PKG_RCD_SCRIPTS=YES in /etc/mk.conf. This option will copy the scripts into /etc/rc.d when a package is installed, and it will automatically remove the scripts when the package is deinstalled.