Whenever you're preparing a package, there are a number of files involved which are described in the following sections. 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. MASTER_SITE_SUBDIR has been deprecated and should no longer be used. 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: Add MANCOMPRESSED if manpages are installed in compressed form by the package; see comment in bsd.pkg.mk. Replace /usr/local with ${PREFIX} in all files (see patches, below). If the package installs any info files, see . Set MAINTAINER to be yourself. If you really can't maintain the package for future updates, set it to tech-pkg@NetBSD.org. If a home page for the software in question exists, add the variable HOMEPAGE right after MAINTAINER. The value of this variable should be the URL for the home page. Be sure to set the COMMENT variable to a short description of the package, not containing the pkg's name. 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 ) 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 &os; 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 &man.patch.1; command to modify the sources as distributed in the distribution file into a form that will compile and run perfectly on &os;. 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 &os; 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 . 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. DESCR A multi-line description of the piece of software. This should include any credits where they are due. Please bear in mind that others do not share your sense of humour (or spelling idiosyncrasies), and that others will read everything that you write here. PLIST This file governs the files that are installed on your system: all the binaries, manual pages, etc. There are other directives which may be entered in this file, to control the creation and deletion of directories, and the location of inserted files. See for more information. INSTALL This shell script is invoked twice by &man.pkg.add.1;. First time after package extraction and before files are moved in place, the second time after the files to install are moved in place. This can be used to do any custom procedures not possible with @exec commands in PLIST. See &man.pkg.add.1; and &man.pkg.create.1; for more information. DEINSTALL This script is executed before and after any files are removed. It is this script's responsibility to clean up any additional messy details around the package's installation, since all pkg_delete knows is how to delete the files created in the original distribution. See &man.pkg.delete.1; and &man.pkg.create.1; for more information. MESSAGE Display this file after installation of the package. Useful for things like legal notices on almost-free software and hints for updating config files after installing modules for apache, PHP etc. Please note that you can modify variables in it easily by using MESSAGE_SUBST in the package's Makefile: MESSAGE_SUBST+= SOMEVAR="somevalue" replaces "${SOMEVAR}" with somevalue in MESSAGE. 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.