For Operating Systems other than NetBSD, we provide a bootstrap kit to build the required tools to use pkgsrc on your platform. As well as native NetBSD support, pkgsrc and the bootstrap kit have support for the following operating systems:

Support for other platforms is under development.

Installing the bootstrap kit should be as simple as:

# cvs checkout othersrc/bootstrap-pkgsrc
# cd othersrc/bootstrap-pkgsrc
# ./bootstrap

This will use the defaults of /usr/pkg for the prefix and /var/db/pkg for the package database directory. However, these can also be set using command-line parameters.

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.

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

# cd bootstrap-pkgsrc
# ./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 --pkgsrc=/Volumes/ufs/pkgsrc

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

CFLAGS=	-xtarget=ultra -xarch=v9

This section describes how to find, retrieve and install a precompiled binary package that someone else already prepared for your type of machine.

# pkg_add /path/to/package.tgz

# pkg_add ftp://ftp.NetBSD.org/pub/NetBSD/packages/<OS Ver>/<arch>/All/package.tgz

This assumes that the package is already part of the NetBSD package system. If it is not, see Part II.

release=pkgsrc

% setenv CVSROOT anoncvs@anoncvs.NetBSD.org:/cvsroot
% setenv CVS_RSH ssh
% cd /usr
% cvs checkout -P pkgsrc

% cd /usr/pkgsrc
% cvs -q update -dP

% cd editors/vim
% make

% make install
===> Installing for top-3.5beta5
===> Becoming root@mofo to install top-3.5beta5.
/usr/bin/su Password: <password>
[...installation continues...]

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.

Create a binary package:

# cd sysutils/top
# 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 gzip or bzip2 tar file. See Section B.2, “Packaging top” for a continuation of the above sysutils/top example.

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

See Section 8.3, “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 your system! Having a 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 everyone. 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

BULK_PREREQ+= pkgtools/xpkgwedge

# echo "I do not have enough disk space to build this pig." \
    > pkgsrc/games/crafty-book-enormous/$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

After your bulk pkgsrc 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 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

Building, installation and creation of a binary package are all controlled by the package's Makefile.

There is a Makefile for each package. This file includes the standard bsd.pkg.mk file (referenced as ../../mk/bsd.pkg.mk), which sets all the definitions and actions necessary for the package to compile and install itself. The mandatory variables are the DISTNAME which specifies the base name of the distribution file to be downloaded from the site on the Internet, MASTER_SITES which specifies that site, CATEGORIES which denotes the categories into which the package falls, PKGNAME which is the name of the package, the MAINTAINER name, and the COMMENT variable, which should contain a one-line description of the package (the package name should not appear, it will be added automatically). The maintainer variable is there so that anyone who quibbles with the (always completely correct) decisions taken by the guy who maintains the port can complain vigorously.

The MASTER_SITES may be set to one of the predefined sites:

${MASTER_SITE_XCONTRIB}
${MASTER_SITE_GNU}
${MASTER_SITE_PERL_CPAN}
${MASTER_SITE_TEX_CTAN}
${MASTER_SITE_SUNSITE}
${MASTER_SITE_GNOME}
${MASTER_SITE_SOURCEFORGE}

If one of these predefined sites is chosen, you may require the ability to specify a subdirectory of that site. Since these macros may expand to more than one actual site, you must use the following construct to specify a subdirectory:

${MASTER_SITE_GNU:=subdirectory/name/}

Note the trailing slash after the subdirectory name.

If the package has multiple DISTFILES or multiple PATCHFILES from different sites, set SITES_foo to a list of URI's where file “foo” may be found. “foo” includes the suffix, e.g.

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/

Note that the normal default setting of DISTFILES must be made explicit if you want to add to it (rather than replace it), as you usually would.

Currently the following values are available for CATEGORIES. If more than one is used, they need to be separated by spaces:

archivers  audio      benchmarks   biology       cad     
chat       comms      converters   cross         databases
devel      editors    emulators    finance       fonts
games      graphics   ham          japanese      lang
mail       math       mbone        misc          net
news       parallel   print        security      shells
sysutils   textproc   time         wm            www
x11

Please pay attention to the following gotchas:

Most important, the mandatory message digest, or checksum, of all the distfiles needed for the package to compile, confirming they match the original file distributed by the author. This ensures that the distfile retrieved from the Internet has not been corrupted during transfer or altered by a malign force to introduce a security hole. It is best generated using the make makesum command. The digest algorithm used was, at one stage, md5, but that was felt lacking compared to sha1, and so sha1 is now the default algorithm. The distfile size is also generated and stored in new distinfo files. The pkgtools/digest utility calculates all of the digests in the distinfo file, and it provides various different algorithms. At the current time, the algorithms provided are: md5, rmd160, sha1, sha256, sha384 and sha512.

Some packages have different sets of distfiles on a per architecture basis (a good example is 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.

The message digest/checksum for all the official patches found in the patches/ directory (see Section 5.3, “patches/*”) for the package is also stored in the distinfo file. This is a message digest/checksum of all lines in the patch file except the NetBSD RCS Id. This file is generated by invoking make makepatchsum.

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

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

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.

When you type make the distribution files are unpacked into this directory. It can be removed by running make clean.

This directory is also used to keep various timestamp files.

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.

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

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 order of things is important.

Similar to MESSAGE_SUBST (see above), you can add variables and their expansions to this variable in the following way:

PLIST_SUBST+=    SOMEVAR="somevalue"

which replaces all occurrences of “${SOMEVAR}” in the PLIST with “somevalue”. For the values which are replaced by default, please look in bsd.pkg.mk (and search for PLIST_SUBST).

Makefile 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, the NetBSD packages system 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:

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.

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

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 port using the 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.

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 and LTCONFIG_OVERRIDE=${WRKSRC}/ltconfig to the package Makefile as the quick way to bypass the pkg's own libtool. The pkg's own libtool is created by ltconfig script at do-configure target. If USE_LIBTOOL and LTCONFIG_OVERRIDE are defined, the specified ltconfig is overridden, using devel/libtool instead of the pkg's own libtool. For newer versions of libtool (without ltconfig) it may be necessary to use LIBTOOL_OVERRIDE=${WRKSRC}/libtool instead.

If your package makes use of the platform independent library for loading dynamic shared objects, that comes with libtool (libltdl), you should include the libtool buildlink2.mk (and set USE_BUILDLINK2=YES).

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. Two Makefile fragments are provided in pkgsrc/mk/autoconf.mk and pkgsrc/mk/automake.mk to help dealing with these tools. See comments in these files for details.

For packages that need only autoconf:

AUTOCONF_REQD=	2.50	# if default version is not good enough
...

pre-configure:
	cd ${WRKSRC}; ${AUTOCONF}

...
.include "../../mk/autoconf.mk"

and for packages that need automake and autoconf:

AUTOMAKE_REQD=	1.7.1	# if default version is not good enough
...

pre-configure:
	cd ${WRKSRC};						\
	${ACLOCAL};						\
	${AUTOHEADER};						\
	${AUTOMAKE} -a --foreign -i;				\
	${AUTOCONF}

...
.include "../mk/automake.mk"

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.

Packages should be taught to look for their configuration files in ${PKG_SYSCONFDIR}, which is passed through to the configure and build processes. PKG_SYSCONFDIR may be customized in various ways by setting other make variables:

The only variables that users should customize are PKG_SYSCONFBASE and PKG_SYSCONFDIR.${PKG_SYSCONFVAR}. Users will typically want to set PKG_SYSCONFBASE to /etc, or to accept the default location of ${PREFIX}/etc.

If you have found any bugs in the package you make available, if you had to do special steps to make it run under NetBSD or if you enhanced the software in various other ways, be sure to report these changes back to the original author of the program! With that kind of support, the next release of the program can incorporate these fixes, and people not using the NetBSD packages system can win from your efforts.

Support the idea of free software!

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, though its value becomes that of X11BASE if USE_IMAKE or USE_X11BASE is set. 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 5.3, “patches/*” and Section 7.2, “Shared libraries - libtool” for more details.

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

The main targets used during the build process defined in bsd.pkg.mk are:

If no target is specified, the default is “build”. If a subsequent stage is requested, all prior stages are made: e.g. make build will also perform the equivalent of:

make fetch
make checksum
make extract
make patch
make configure
make build

The process of converting packages to use the buildlink2 framework is fairly straightforward. The package Makefile must define USE_BUILDLINK2. If a dependency on a particular package, e.g. foo, is required for its libraries and headers, then we replace:

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

with

.include "../../category/foo/buildlink2.mk"

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

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

A simple example of a buildlink2.mk file for a mythical package foo follows:

BUILDLINK_PACKAGES+=          foo
BUILDLINK_PKGBASE.foo=        foo
BUILDLINK_DEPENDS.foo?=       foo>=1.0
BUILDLINK_PKGSRCDIR.foo?=     ../../category/foo

EVAL_PREFIX+=                 BUILDLINK_PREFIX.foo=foo
BUILDLINK_PREFIX.foo_DEFAULT= ${LOCALBASE}
BUILDLINK_FILES.foo=          include/foo.h
BUILDLINK_FILES.foo+=         include/bar.h
BUILDLINK_FILES.foo+=         lib/libfoo.*

BUILDLINK_TARGETS+=           foo-buildlink

foo-buildlink: _BUILDLINK_USE

The first section controls how the dependency on foo is added. The dependency is constructed from four parts:

The second section controls which files are linked into BUILDLINK_DIR:

The remaining parts create the “foo-buildlink” target that actually performs the symlinking and adds the “foo-buildlink” target to BUILDLINK_TARGETS, which is the global list of targets to execute at do-buildlink time.

If your package uses GNU autoconf created configure scripts, add the following to your package's Makefile:

GNU_CONFIGURE= yes

Note that this appends “--prefix=${PREFIX}” to CONFIGURE_ARGS, so you don't have to do that yourself, but may not be desired.

If your package uses a different distribution method from .tar.gz, take a look at the package for editors/sam, which uses a gzipped shell archive (shar), but the quick solution is to set EXTRACT_SUFX to the name after the DISTNAME field, and add the following to your package's Makefile:

EXTRACT_SUFX=   .msg.gz
EXTRACT_CMD=            zcat
EXTRACT_BEFORE_ARGS=
EXTRACT_AFTER_ARGS=     |sh

Your package doesn't create a subdirectory for itself (like GNU software does, for instance), but extracts itself in the current directory: see editors/sam again, but the quick answer is:

WRKSRC=		${WRKDIR}

Please note that the old:

NO_WRKSUBDIR=   yes

has been deprecated and should not be used.

Your package uses a weird Configure script, eg. sysutils/top. The quick answer is:

HAS_CONFIGURE=          yes
CONFIGURE_SCRIPT=       Configure
CONFIGURE_ARGS+=        netbsd13

Your package builds in a different directory from its base DISTNAME (see lang/tcl and x11/tk).

WRKSRC=         ${WRKDIR}/${DISTNAME}/unix

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, 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 lukemftp) at work, don't forget to set FETCH_CMD to something that fetches an 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

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/

See Section 5.3, “patches/*” for information on how to remove RCS IDs from patch files.

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 have 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

Yes, <tech-pkg@NetBSD.org> is the list for discussing package related issues. To subscribe do:

% echo subscribe tech-pkg | mail majordomo@NetBSD.org

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:

/usr/bin/fetch
${LOCALBASE}/bsd/bin/ftp
/usr/bin/ftp

On a default NetBSD install, 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.

Your package may depend on some other package being present - and there are various ways of expressing this dependency. NetBSD supports the BUILD_DEPENDS and DEPENDS definitions, as well as dependencies via buildlink2.mk (see Chapter 9, buildlink2 methodology).

The basic difference between the two definitions is as follows: The DEPENDS definition registers that pre-requisite in the binary package, whilst the BUILD_DEPENDS definition does not.

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 recognised 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 provide 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”.

The NetBSD packages system now supports a variable called HOMEPAGE. If the software being packaged has a home page, the Makefile should include the URL for that page in the HOMEPAGE variable. The definition of the variable should be placed immediately after the MAINTAINER variable.

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 md5 checksum will no longer match. The correct way to work around this is to update the package's md5 checksum to match the package on the master site (beware, any mirrors may not be up to date yet!), and to remove the old distfile from ftp.NetBSD.org's /pub/NetBSD/packages/distfiles directory. Furthermore, a mail to the package's author seems appropriate making sure the distfile was really updated on purpose, and that no trojan horse or so crept in.

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 on your machine (nroff, ...). It is recommended to do that.

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.

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

You didn't install the compiler set, comp.tgz, when you installed your NetBSD machine. Please get it 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).

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!

Some packages need curses functionality that wasn't present in NetBSD's own curses prior to 1.4Y.

If ../../devel/ncurses/buildlink2.mk is included in a package's Makefile, then a curses library and headers with ncurses functionality are linked into ${BUILDLINK_DIR} at pre-configure time. If ncurses is actually required, then define USE_NCURSES in the package's Makefile.

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 audit-packages package is strongly recommended.

The following message is displayed as part of the audit-packages installation procedure:

======================================================================
You may wish to have the vulnerabilities file downloaded daily so that
it remains current.  This may be done by adding an appropriate entry
to the root users crontab(5) entry.  For example the entry
	
# download vulnerabilities file
0 3 * * * ${PREFIX}/sbin/download-vulnerability-list >/dev/null 2>&1
	
will update the vulnerability list every day at 3AM.
	
In addition, you may wish to run the package audit from the daily
security script.  This may be accomplished by adding the following
lines to /etc/security.local
	
if [ -x ${PREFIX}/sbin/audit-packages ]; then
	${PREFIX}/sbin/audit-packages
fi
======================================================================

Note to package developers: When a vulnerability is found, this should be noted in localsrc/security/advisories/pkg-vulnerabilities, and after the commit of that file, it should be copied to /pub/NetBSD/packages/distfiles/vulnerabilities on ftp.NetBSD.org.

There are two make variables used to control the creation of package-specific groups and users at pre-install time. The first is PKG_GROUPS, which is a list of group[:groupid] elements, where the groupid is optional. The second is PKG_USERS, which is a list of elements of the form:

user:group[:[userid][:[description][:[home][:shell]]]]

where only the user and group are required, the rest being optional. A simple example is:

PKG_GROUPS=	foogroup
PKG_USERS=	foouser:foogroup

A more complex example is that creates two groups and two users is:

PKG_GROUPS=	group1 group2:1005
PKG_USERS=	first:group1::First\\ User			\
		second:group2::Second\\ User:/home/second:${SH}

By default, a new user will have home directory /nonexistent, and login shell /sbin/nologin unless they are specified as part of the user element.

The package Makefile must also include ../../mk/bsd.pkg.install.mk prior to the inclusion of bsd.pkg.mk. This will cause the users and groups to be created at pre-install time, and the admin will be prompted to remove them at post-deinstall time. Automatic creation of the users and groups can be toggled on and off by setting the environment variable PKG_CREATE_USERGROUP prior to package installation.

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 doc/HACKS. See doc/HACKS for examples.

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

INFO_DIR defaults to “info” and can be overridden in the package Makefile. INSTALL and DEINSTALL scripts will be generated for handling registration of the info files in the Info directory file. The command “install-info” 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 need 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 is added automatically.

The installation process of the software provided by the package must not use “install-info”, as the registration of info files is the task of the package INSTALL sript, and it must use the right “makeinfo”.

If the package use buildlink2 framework no special action should be needed to achieve this goal.

If the package does not use the buildlink2 framework patch files are likely to be needed so the build and installation process of the software picks up the possibly dummy values of INSTALL_INFO and MAKEINFO variables.

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: audio/realplayer, cad/simian, devel/ipv6socket, emulators/vmare-module, fonts/acroread-jpnfont, sysutils/storage-manager, www/ap-aolserver, www/openacs. Try to be consistent with them.

The global variable PKG_SYSCONFBASE (and some others) can be set by the system administrator in /etc/mk.conf to define the place where configuration files get installed. Therefore, packages must be adapted to support this feature. Keep in mind that you should only install files that are strictly necessary in the configuration directory, files that can go to $PREFIX/share should go there.

We will take a look at available variables first (bsd.pkg.mk contains more information). PKG_SYSCONFDIR is where the configuration files for a package may be found (that is, the full path, e.g. /etc or /usr/pkg/etc). This value may be customized in various ways:

Programs' configuration directory should be defined during the configure stage. Packages that use GNU autoconf can usually do this by using the “--sysconfdir” parameter, but this brings some problems as we will see now. When you change this pathname in packages, you should not allow them to install files in that directory directly. Instead they need to install those files under share/examples/${PKGNAME} so PLIST can register them.

Once you have the required configuration files in place (under the share/examples directory) the variable CONF_FILES should be set to copy them into PKG_SYSCONFDIR. The contents of this variable is formed by pairs of filenames; the first element of the pair specifies the file inside the examples directory (registered by PLIST) and the second element specifies the target file. This is done this way to allow binary packages to place files in the right directory using INSTALL/DEINSTALL scripts which are created automatically. The package Makefile must also include ../../mk/bsd.pkg.install.mk prior to the inclusion of bsd.pkg.mk to use these automatically generated scripts. The automatic copying of config files can be toggled by setting the environment variable PKG_CONFIG prior to package installation.

Here is an example, taken from mail/mutt/Makefile:

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

As you can see, this package installs configuration files inside EGDIR, which are registered by PLIST. After that, the variable CONF_FILES lists the installed file first and then the target file. Users will also get an automatic message when files are installed using this method.

If the purpose of the package is to provide a login shell, the variable PKG_SHELL should contain the full pathname of the shell executable installed by this package. The package Makefile also must include ../../mk/bsd.pkg.install.mk prior to the inclusion of bsd.pkg.mk to use the automatically generated INSTALL/DEINSTALL scripts.

An example taken from shells/zsh:

PKG_SHELL=	${PREFIX}/bin/zsh
.include "../../mk/bsd.pkg.install.mk"

The shell is registered into /etc/shells file automatically in the post-install target by the INSTALL script generated by bsd.pkg.install.mk and removed in the deinstall target by the DEINSTALL script.

If the package provides its own locale catalogues, the variable USE_PKGLOCALEDIR should be defined. It will ensure that the package's Makefile template files are fixed and point to the correct locale directories (which may vary, depending on OS), if necessary. See Section 6.1, “Miscellaneous” for details about PKGLOCALEDIR. This functionality is buildlink2-only.

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:

SU_CMD=/usr/pkg/bin/sudo /bin/sh -c

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.

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

IGNORE is deprecated because it didn't provide enough information to determine whether the build should fail.

You have to separate between binary and “normal” (source) packages here:

This section is only of interest for NetBSD developers with write access to the NetBSD pkgsrc repository. Please remember that cvs imports files relative to the cwd, and that the pathname that you give the cvs import command is so that it knows where to place the files in the repository. Newly created packages should be imported with a vendor tag of “TNF” and a release tag of “pkgsrc-base”, e.g:

% cd
.../pkgsrc/<category>/<pkgname>
% cvs import pkgsrc/<category>/<pkgname> TNF pkgsrc-base

Remember to move the directory from which you imported out of the way, or cvs will complain the next time you “cvs update” your source tree. Also don't forget to add the new package to the category's Makefile.

The commit message of the initial import should include part of the DESCR file, so people reading the mailing lists know what the package is/does.

Please note all package updates/additions in pkgsrc/doc/CHANGES. It's very important to keep this file up to date and conforming to the existing format, because it will be used by scripts to automatically update pages on www.NetBSD.org and other sites.

For new packages, “cvs import” is preferred to “cvs add” because the former gets everything with a single command, and provides a consistent tag.

Please always put a concise, appropriate and relevant summary of the changes between old and new versions into the commit log when updating a package. There are various reasons for this:

Please also recognise that, just because a new version of a package has been released, it should not automatically be upgraded in the CVS repository. We prefer to be conservative in the packages that are included in pkgsrc - development or beta packages are not really the best thing for most places in which pkgsrc is used. Please use your judgement about what should go into pkgsrc, and bear in mind that stability is to be preferred above new and possibly untested features.