Package components - files, directories and contents
Whenever you're preparing a package, there are a number of
files involved which are described in the following
sections.
Makefile
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.
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
MASTER_SITES is a list of URLs where
the distribution files can be downloaded. Each URL must end with a
slash.
The MASTER_SITES may make use of
the following 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
want 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 URIs
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/
DISTFILES: Name(s)
of archive file(s) containing distribution. The default is
${DISTNAME}${EXTRACT_SUFX}. Should only
be set if you have more than one distfile.
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.
EXTRACT_SUFX: Suffix of the
distribution file, will be appended to
DISTNAME. Defaults to
.tar.gz.
The second section contains information about separately
downloaded patches, if any.
PATCHFILES:
Name(s) of additional files that contain distribution patches.
There is no default. pkgsrc will look for them at
PATCH_SITES.
They will automatically be uncompressed before patching if
the names end with .gz or
.Z.
PATCH_SITES:
Primary location(s) for distribution patch files (see
PATCHFILES below) if not found locally.
The third section contains the following variables.
MAINTAINER is the email address
of the person who feels responsible for this package, and who is
most likely to look at problems or questions regarding this
package which have been reported with &man.send-pr.1;. Other
developers should contact the MAINTAINER before
making major changes to the package. When packaging a new program,
set MAINTAINER to yourself. If you really can't
maintain the package for future updates, set it to
pkgsrc-users@NetBSD.org.
HOMEPAGE is a URL where users can
find more information about the package.
COMMENT is a one-line
description of the package (should not include the package
name).
Other variables that affect the build:
WRKSRC: The directory where the
interesting distribution files of the package are found. The
default is ${WRKDIR}/${DISTNAME}, which
works for most packages.
If a package doesn't create a subdirectory for itself
(most GNU software does, for instance), but extracts itself in
the current directory, you should set WRKSRC=
${WRKDIR}.
If a package doesn't create a subdirectory with the name
of DISTNAME but some different name, set
WRKSRC to point to the proper name in
${WRKDIR}, for example WRKSRC=
${WRKDIR}/${DISTNAME}/unix. See lang/tcl and x11/tk for other examples.
The name of the working directory created by pkgsrc is
taken from the WRKDIR_BASENAME variable. By
default, its value is work. If you want
to use the same pkgsrc tree for building different kinds of
binary packages, you can change the variable according to your
needs. Two other variables handle common cases of setting
WRKDIR_BASENAME individually. If
OBJHOSTNAME is defined in
/etc/mk.conf, the first component of the
host's name is attached to the directory name. If
OBJMACHINE is defined, the platform name is
attached, which might look like work.i386
or work.sparc.
Please pay attention to the following gotchas:
Add MANCOMPRESSED if man pages 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
.
distinfo
The distinfo file contains the message
digest, or checksum, of each distfile needed for the package. This
ensures that the distfiles retrieved from the Internet have not been
corrupted during transfer or altered by a malign force to introduce
a security hole. Due to recent rumor about weaknesses of digest
algorithms, all distfiles are protected using both SHA1 and RMD160
message digests, as well as the file size.
The distinfo file also contains the
checksums for all the patches found in the
patches directory (see ).
To regenerate the distinfo file, use the
make makedistinfo or make mdi
command.
Some packages have different sets of distfiles depending on
the platform, 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.
patches/*
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 .
When adding a patch that corrects a problem in the distfile (rather
than e.g. enforcing pkgsrc's view of where man pages should go), send
the patch as a bug report to the maintainer. This benefits
non-pkgsrc users of the package, and usually enables removing
the patch in future version.
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.
Other mandatory files
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.
Optional files
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
This file is displayed 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.
work*
When you type make, the distribution files are
unpacked into the directory denoted by
WRKDIR. It can be removed by running
make clean. Besides the sources, this
directory is also used to keep various timestamp files.
The directory gets removed completely on clean.
The default is ${.CURDIR}/work
or ${.CURDIR}/work.${MACHINE_ARCH}
if OBJMACHINE is set.
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.