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's 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 package can complain vigorously, or send chocolate as a sign of appreciation.

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

        ${MASTER_SITE_APACHE}
        ${MASTER_SITE_DEBIAN}
        ${MASTER_SITE_GNOME}
        ${MASTER_SITE_GNU}
        ${MASTER_SITE_GNUSTEP}
        ${MASTER_SITE_IFARCHIVE}
        ${MASTER_SITE_MOZILLA}
        ${MASTER_SITE_PERL_CPAN}
        ${MASTER_SITE_SOURCEFORGE}
        ${MASTER_SITE_SUNSITE}
        ${MASTER_SITE_R_CRAN}
        ${MASTER_SITE_SUSE}
        ${MASTER_SITE_TEX_CTAN}
        ${MASTER_SITE_XCONTRIB}
        ${MASTER_SITE_XEMACS} 

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/}
        ${MASTER_SITE_SOURCEFORGE:=project_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     cross         geography     meta-pkgs     security
audio         databases     graphics      misc          shells
benchmarks    devel         ham           multimedia    sysutils
biology       editors       inputmethod   net           textproc
cad           emulators     lang          news          time
chat          finance       mail          parallel      wm
comms         fonts         math          pkgtools      www
converters    games         mbone         print         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 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, for example www/navigator). These are kept in the same distinfo file and care should be taken when upgrading such a package to ensure distfile information is not lost.

The message digest/checksum for all the official patches found in the patches/ directory (see Section 7.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 (or make mps if you're in a hurry).

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

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

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

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

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

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

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

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

When you type make the distribution files are unpacked into this directory. It can be removed by running make clean. Besides the sources, this directory is also used to keep various timestamp files.

If a package doesn't create a subdirectory for itself (like GNU software does, for instance), but extracts itself in the current directory, you should set WRKSRC accordingly, e.g. editors/sam again, but the quick answer is:

WRKSRC=                ${WRKDIR}

Please note that the old NO_WRKSUBDIR has been deprecated and should not be used. Also, if your package doesn't create a subdir with the name of DISTNAME but some different name, set WRKSRC to point to the proper name in ${WRKDIR}. See lang/tcl and x11/tk for examples, and here is another one:

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

The name of the working directory created by pkgsrc is work by default. If the same pkgsrc tree should be used on several different platforms, the variable OBJMACHINE can be set in /etc/mk.conf to attach the platform to the directory name, e.g. work.i386 or work.sparc.

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.