443 lines
19 KiB
XML
443 lines
19 KiB
XML
<!-- $NetBSD: components.xml,v 1.13 2005/09/02 19:12:37 rillig Exp $ -->
|
|
|
|
<chapter id="components"> <?dbhtml filename="components.html"?>
|
|
<title>Package components - files, directories and contents</title>
|
|
|
|
<para> Whenever you're preparing a package, there are a number of
|
|
files involved which are described in the following
|
|
sections. </para>
|
|
|
|
<sect1 id="components.Makefile">
|
|
<title><filename>Makefile</filename></title>
|
|
|
|
<para>Building, installation and creation of a binary package are all
|
|
controlled by the package's <filename>Makefile</filename>.
|
|
The <filename>Makefile</filename> describes various things about
|
|
a package, for example from where to get it, how to configure,
|
|
build, and install it.
|
|
</para>
|
|
|
|
<para>A package <filename>Makefile</filename> contains several
|
|
sections that describe the package.</para>
|
|
|
|
<para>In the first section there are the following variables, which
|
|
should appear exactly in the order given here.
|
|
<itemizedlist>
|
|
|
|
<listitem><para><varname>DISTNAME</varname> is the basename of the
|
|
distribution file to be downloaded from the package's
|
|
website.</para></listitem>
|
|
|
|
<listitem><para><varname>PKGNAME</varname> 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
|
|
<varname>^[A-Za-z0-9][A-Za-z0-9-_.+]*$</varname>, that is, it
|
|
starts with a letter or digit, and contains only letters, digits,
|
|
dashes, underscores, dots and plus signs.</para></listitem>
|
|
|
|
<listitem><para><varname>CATEGORIES</varname> is a list of categories
|
|
which the package fits in. You can choose any of the top-level
|
|
directories of pkgsrc for it.</para>
|
|
|
|
<para>Currently the following values are available for
|
|
<varname>CATEGORIES</varname>. If more than
|
|
one is used, they need to be separated by spaces:</para>
|
|
|
|
<programlisting>
|
|
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</programlisting>
|
|
</listitem>
|
|
|
|
<listitem><para><varname>MASTER_SITES</varname> is a list of URLs where
|
|
the distribution files can be downloaded. Each URL must end with a
|
|
slash.</para>
|
|
<para>The <varname>MASTER_SITES</varname> may make use of
|
|
the following predefined sites:</para>
|
|
|
|
<!-- sort bsd.sites.mk | sed -n 's/\(^MA[A-Z_]*\).*/ ${\1}/p' -->
|
|
<programlisting>
|
|
${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}
|
|
</programlisting>
|
|
|
|
<para>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 <emphasis>must</emphasis> use the
|
|
following construct to specify a subdirectory:</para>
|
|
|
|
<programlisting>
|
|
${MASTER_SITE_GNU:=subdirectory/name/}
|
|
${MASTER_SITE_SOURCEFORGE:=project_name/}</programlisting>
|
|
|
|
<para>Note the trailing slash after the subdirectory name.</para>
|
|
|
|
<para>If the package has multiple
|
|
<varname>DISTFILES</varname> or multiple
|
|
<varname>PATCHFILES</varname> from different
|
|
sites, set <varname>SITES_foo</varname> to a list of URIs
|
|
where file <quote>foo</quote> may be
|
|
found. <quote>foo</quote> includes the suffix, e.g.:</para>
|
|
<programlisting>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/</programlisting>
|
|
</listitem>
|
|
|
|
<listitem><para><varname>DISTFILES</varname>: Name(s)
|
|
of archive file(s) containing distribution. The default is
|
|
<filename>${DISTNAME}${EXTRACT_SUFX}</filename>. Should only
|
|
be set if you have more than one distfile.</para>
|
|
<para>Note that the normal default setting of
|
|
<varname>DISTFILES</varname> must be made explicit if you
|
|
want to add to it (rather than replace it), as you usually
|
|
would.</para>
|
|
</listitem>
|
|
|
|
<listitem><para><varname>EXTRACT_SUFX</varname>: Suffix of the
|
|
distribution file, will be appended to
|
|
<varname>DISTNAME</varname>. Defaults to
|
|
<filename>.tar.gz</filename>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>The second section contains information about separately
|
|
downloaded patches, if any.
|
|
<itemizedlist>
|
|
<listitem><para><varname>PATCHFILES:</varname>
|
|
Name(s) of additional files that contain distribution patches.
|
|
There is no default. pkgsrc will look for them at
|
|
<varname>PATCH_SITES</varname>.
|
|
They will automatically be uncompressed before patching if
|
|
the names end with <filename>.gz</filename> or
|
|
<filename>.Z</filename>.</para>
|
|
</listitem>
|
|
<listitem><para><varname>PATCH_SITES</varname>:
|
|
Primary location(s) for distribution patch files (see
|
|
<varname>PATCHFILES</varname> below) if not found locally.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>The third section contains the following variables.
|
|
<itemizedlist>
|
|
|
|
<listitem><para><varname>MAINTAINER</varname> is the email address of the
|
|
contact person for this package.
|
|
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;. The right
|
|
person to contact before making major changes to the
|
|
package.
|
|
When packaging a new program, set
|
|
<varname>MAINTAINER</varname> to yourself. If you really
|
|
can't maintain the package for future updates, set it to
|
|
<email>tech-pkg@NetBSD.org</email>.</para>
|
|
</listitem>
|
|
|
|
<listitem><para><varname>HOMEPAGE</varname> is a URL where users can
|
|
find more information about the package.</para></listitem>
|
|
|
|
<listitem><para><varname>COMMENT</varname> is a one-line
|
|
description of the package (should not include the package
|
|
name).</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>Other variables that affect the build:
|
|
<itemizedlist>
|
|
<listitem><para><varname>WRKSRC</varname>:
|
|
The subdirectory of <filename>${WRKDIR}</filename> to which
|
|
the distribution actually unpacks. The default is
|
|
<filename>${WRKDIR}/${DISTNAME}</filename>.
|
|
The value of <varname>WRKSRC</varname> should be set
|
|
explicitly if the package does not follow standard
|
|
conventions and include the package's name as a
|
|
subdirectory.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>Please pay attention to the following gotchas:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Add <varname>MANCOMPRESSED</varname> if man pages are installed in
|
|
compressed form by the package; see comment in
|
|
<filename>bsd.pkg.mk</filename>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Replace <filename>/usr/local</filename> with
|
|
<quote>${PREFIX}</quote> in all files (see patches, below).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the package installs any info files, see
|
|
<xref linkend="faq.info-files"/>.</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
</sect1>
|
|
|
|
<sect1 id="components.distinfo">
|
|
<title><filename>distinfo</filename></title>
|
|
|
|
<para>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 <command>make makesum</command> 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 <filename role="pkg">pkgtools/digest</filename> utility
|
|
calculates all of the digests in the distinfo file, and it provides
|
|
various different algorithms. At the current time, the algorithms
|
|
provided are:
|
|
<emphasis>md5</emphasis>, <emphasis>rmd160</emphasis>,
|
|
<emphasis>sha1</emphasis>, <emphasis>sha256</emphasis>,
|
|
<emphasis>sha384</emphasis> and <emphasis>sha512</emphasis>.</para>
|
|
|
|
<para>Some packages have different sets of distfiles on a per architecture
|
|
basis, for example <filename
|
|
role="pkg">www/navigator</filename>). 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.</para>
|
|
|
|
<para>The message digest/checksum for all the official patches found in the
|
|
<filename>patches/</filename> directory (see
|
|
<xref linkend="components.patches"/>) for the package is also stored in
|
|
the <filename>distinfo</filename> 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 <command>make
|
|
makepatchsum</command> (or <command>make mps</command> if you're
|
|
in a hurry).</para>
|
|
</sect1>
|
|
|
|
<sect1 id="components.patches">
|
|
<title>patches/*</title>
|
|
|
|
<para>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
|
|
<quote>patches/patch-*</quote> glob expansion), so
|
|
<filename>patch-aa</filename> is applied before
|
|
<filename>patch-ab</filename>, etc.</para>
|
|
|
|
<para>The <filename>patch-*</filename> files should be in
|
|
<command>diff -bu</command> format, and apply without a fuzz to avoid
|
|
problems. (To force patches to apply
|
|
with fuzz you can set <varname>PATCH_FUZZ_FACTOR=-F2</varname>).
|
|
Furthermore, do not put changes for more than one file into a single
|
|
patch file, as this will make future modifications more difficult.</para>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>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
|
|
<command>pkgdiff</command> from the
|
|
<filename role="pkg">pkgtools/pkgdiff</filename> package to avoid
|
|
these problems.</para>
|
|
|
|
<para>For even more automation, we recommend using <command>mkpatches</command> from the same
|
|
package to make a whole set of patches. You just have to backup files
|
|
before you edit them to <filename>filename.orig</filename>, e.g. with
|
|
<command>cp -p filename filename.orig</command> or, easier, by using
|
|
<command>pkgvi</command> 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 <command>patchdiff</command>.</para>
|
|
|
|
<para>When you have finished a package, remember to generate the checksums
|
|
for the patch files by using the <command>make makepatchsum</command>
|
|
command, see <xref linkend="components.distinfo"/>.</para>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>Patch files that are distributed by the author or other
|
|
maintainers can be listed in
|
|
<varname>$PATCHFILES</varname>. </para>
|
|
|
|
<para>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
|
|
<filename>$LOCALPATCHES</filename>
|
|
directory. The directory tree there is expected to have the same
|
|
<quote>category/package</quote> structure as pkgsrc, and patches are
|
|
expected to be stored inside these dirs (also known as
|
|
<filename>$LOCALPATCHES/$PKGPATH</filename>). For
|
|
example, if you want to keep a private patch for
|
|
<filename>pkgsrc/graphics/png</filename>, keep
|
|
it in <filename>$LOCALPATCHES/graphics/png/mypatch</filename>. All
|
|
files in the named directory are expected to be patch files, and
|
|
<emphasis>they are applied after pkgsrc patches are applied</emphasis>.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="other-mandatory-files">
|
|
<title>Other mandatory files</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><filename>DESCR</filename></term>
|
|
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><filename>PLIST</filename></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
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 <xref linkend="plist"/> for more information. </para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect1>
|
|
|
|
<sect1 id="components.optional">
|
|
<title>Optional files</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><filename>INSTALL</filename></term>
|
|
|
|
<listitem>
|
|
<para>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
|
|
<filename>PLIST</filename>. See
|
|
&man.pkg.add.1; and &man.pkg.create.1; for more information.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><filename>DEINSTALL</filename></term>
|
|
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><filename>MESSAGE</filename></term>
|
|
|
|
<listitem>
|
|
<para>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
|
|
<varname>MESSAGE_SUBST</varname> in the package's
|
|
<filename>Makefile</filename>:</para>
|
|
|
|
<programlisting>MESSAGE_SUBST+= SOMEVAR="somevalue"</programlisting>
|
|
|
|
<para>replaces "${SOMEVAR}" with <quote>somevalue</quote> in
|
|
<filename>MESSAGE</filename>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect1>
|
|
|
|
<sect1 id="work-dir">
|
|
<title><filename>work*</filename></title>
|
|
|
|
<para>When you type <command>make</command>, the distribution files are
|
|
unpacked into the directory denoted by
|
|
<varname>WRKDIR</varname>. It can be removed by running
|
|
<command>make clean</command>. Besides the sources, this
|
|
directory is also used to keep various timestamp files.
|
|
The directory gets <emphasis>removed completely</emphasis> on clean.
|
|
The default is <filename>${.CURDIR}/work</filename>
|
|
or <filename>${.CURDIR}/work.${MACHINE_ARCH}</filename>
|
|
if <varname>OBJMACHINE</varname> is set.</para>
|
|
|
|
<para> 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 <varname>WRKSRC</varname>
|
|
accordingly, e.g. <filename role="pkg">editors/sam</filename>
|
|
again, but the quick answer is:</para>
|
|
|
|
<programlisting>WRKSRC= ${WRKDIR}</programlisting>
|
|
|
|
<para>If a package doesn't create a subdir with the name of
|
|
<varname>DISTNAME</varname> but some different name, set
|
|
<varname>WRKSRC</varname> to point to the proper name in
|
|
<filename>${WRKDIR}</filename>. See <filename
|
|
role="pkg">lang/tcl</filename> and
|
|
<filename role="pkg">x11/tk</filename> for examples, and here is
|
|
another one: </para>
|
|
|
|
<programlisting>WRKSRC= ${WRKDIR}/${DISTNAME}/unix</programlisting>
|
|
|
|
<para> The name of the working directory created by pkgsrc is
|
|
<filename>work</filename> by default. If the same pkgsrc tree
|
|
should be used on several different platforms, the variable
|
|
<varname>OBJMACHINE</varname> can be set in /etc/mk.conf to
|
|
attach the platform to the directory name,
|
|
e.g. <filename>work.i386</filename> or
|
|
<filename>work.sparc</filename>. </para>
|
|
</sect1>
|
|
|
|
<sect1 id="files-dir">
|
|
<title><filename>files/*</filename></title>
|
|
|
|
<para>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 <quote>${CP}</quote> command in the
|
|
<quote>pre-configure</quote> target to achieve
|
|
this. Alternatively, you could simply diff the file against
|
|
<filename>/dev/null</filename> and use the patch mechanism to manage
|
|
the creation of this file.</para>
|
|
</sect1>
|
|
</chapter>
|