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. The Makefile describes various things about a package, for example from where to get it, how to configure, build, and install it. A package Makefile contains several sections that describe the package. In the first section there are the following variables, which should appear exactly in the order given here. DISTNAME is the basename of the distribution file to be downloaded from the package's website. PKGNAME is the name of the package, as used by pkgsrc. You only need to provide it if it differs from DISTNAME. Usually it is the directory name together with the version number. It must match the regular expression ^[A-Za-z0-9][A-Za-z0-9-_.+]*$, that is, it starts with a letter or digit, and contains only letters, digits, dashes, underscores, dots and plus signs. CATEGORIES is a list of categories which the package fits in. You can choose any of the top-level directories of pkgsrc for it. MASTER_SITES is a list of URLs where the distribution files can be downloaded. Each URL must end with a slash. The second section contains the following variables. MAINTAINER is the mail address of the package's maintainer, which is the person you can contact when the package does not work. HOMEPAGE is a URL where users can find more information about the package. COMMENT is a one-line comment about the purpose of the package. The MASTER_SITES may be set to one of the predefined sites: ${MASTER_SITE_APACHE} ${MASTER_SITE_BACKUP} ${MASTER_SITE_CYGWIN} ${MASTER_SITE_DEBIAN} ${MASTER_SITE_FREEBSD} ${MASTER_SITE_FREEBSD_LOCAL} ${MASTER_SITE_GNOME} ${MASTER_SITE_GNU} ${MASTER_SITE_GNUSTEP} ${MASTER_SITE_IFARCHIVE} ${MASTER_SITE_MOZILLA} ${MASTER_SITE_OPENOFFICE} ${MASTER_SITE_PERL_CPAN} ${MASTER_SITE_R_CRAN} ${MASTER_SITE_SOURCEFORGE} ${MASTER_SITE_SUNSITE} ${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.