This file is unused for some time now. Remove.

1 files changed, 0 insertions, 1246 deletions

diff --git a/doc/guide/files/features.xml b/doc/guide/files/features.xml
deleted file mode 100644
index 1b20b5a729d..00000000000
--- a/doc/guide/files/features.xml
+++ /dev/null
@@ -1,1246 +0,0 @@
-<!-- $NetBSD: features.xml,v 1.2 2004/10/22 00:24:48 hubertf Exp $ -->
-
-<chapter id="features"> <?dbhtml filename="features.html"?>
-<title>FAQs &amp; features of the package system</title>
-
-<sect1>
-<title>Packages using GNU autoconf</title>
-
-<para>
-If your package uses GNU autoconf created configure scripts, add the following
-to your package's <filename>Makefile</filename>:
-</para>
-
-<programlisting>GNU_CONFIGURE= yes</programlisting>
-
-<para>
-Note that this appends <quote>--prefix=${PREFIX}</quote> to
-<varname>CONFIGURE_ARGS</varname>, so you don't
-have to do that yourself, but may not be desired.
-</para>
-</sect1>
-
-
-<sect1>
-<title>Other distrib methods than .tar.gz</title>
-
-<para>
-If your package uses a different distribution method from
-<filename>.tar.gz</filename>, take a
-look at the package for <pkg>editors/sam</pkg>, which uses a gzipped shell archive
-(shar), but the quick solution is to set
-<varname>EXTRACT_SUFX</varname> to the name after the
-<varname>DISTNAME</varname> field, and add the following to your
-package's <filename>Makefile</filename>:
-</para>
-
-<programlisting>EXTRACT_SUFX=   .msg.gz
-EXTRACT_CMD=            zcat
-EXTRACT_BEFORE_ARGS=
-EXTRACT_AFTER_ARGS=     |sh</programlisting>
-</sect1>
-
-
-<sect1>
-<title>Packages not creating their own subdirectory</title>
-
-<para>
-Your package doesn't create a subdirectory for itself (like GNU software
-does, for instance), but extracts itself in the current directory: see
-<pkg>editors/sam</pkg> again, but the quick answer is:
-</para>
-
-<programlisting>WRKSRC=		${WRKDIR}</programlisting>
-
-<para>
-Please note that the old:
-</para>
-
-<programlisting>NO_WRKSUBDIR=   yes</programlisting>
-
-<para>
-has been deprecated and should not be used.
-</para>
-</sect1>
-
-<sect1>
-<title>Custom configuration process</title>
-
-<para>
-Your package uses a weird Configure script, eg.
-<pkg>sysutils/top</pkg>. The quick answer is:
-</para>
-
-<programlisting>HAS_CONFIGURE=          yes
-CONFIGURE_SCRIPT=       Configure
-CONFIGURE_ARGS+=        netbsd13</programlisting>
-</sect1>
-
-
-<sect1>
-<title>Packages not building in their DISTNAME directory</title>
-
-<para>
-Your package builds in a different directory from its base
-<varname>DISTNAME</varname> (see <pkg>lang/tcl</pkg> and
-<pkg>x11/tk</pkg>).
-</para>
-
-<programlisting>WRKSRC=         ${WRKDIR}/${DISTNAME}/unix</programlisting>
-</sect1>
-
-
-<sect1>
-<title>How to fetch all distfiles at once</title>
-
-<para>
-You would like to download all the distfiles in a single batch from work or
-university, where you can't run a <command>make fetch</command>. There
-is an archive of distfiles on <ulink
-url="ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/">ftp.NetBSD.org</ulink>,
-but downloading the entire directory may not be appropriate.
-</para>
-
-<para>
-The answer here is to do a <command>make fetch-list</command> in
-<filename>/usr/pkgsrc</filename>, carry the 
-resulting list to your machine at work/school and use it there If you don't
-have a NetBSD-compatible ftp(1) (like lukemftp) at work, don't forget to
-set <varname>FETCH_CMD</varname> to something that fetches a URL:
-</para>
-
-<para>
-At home:
-</para>
-
-<screen><prompt>%</prompt> <userinput>cd /usr/pkgsrc</userinput>
-<prompt>%</prompt> <userinput>make fetch-list FETCH_CMD=wget DISTDIR=/tmp/distfiles >/tmp/fetch.sh</userinput>
-<prompt>%</prompt> <userinput>scp /tmp/fetch.sh work:/tmp</userinput></screen>
-
-<para>
-At work:
-</para>
-
-<screen><prompt>%</prompt> <userinput>sh /tmp/fetch.sh</userinput></screen>
-
-<para>
-then tar up <filename>/tmp/distfiles</filename> and take it home.
-</para>
-
-<para>
-If you have a machine running NetBSD, and you want to get
-<emphasis>all</emphasis> distfiles
-(even ones that aren't for your machine architecture), you can do so by
-using the above-mentioned <command>make fetch-list</command> approach, or
-fetch the distfiles directly by running:
-</para>
-
-<screen><prompt>%</prompt> <userinput>make mirror-distfiles</userinput></screen>
-
-<para>
-If you even decide to ignore <varname>NO_{SRC,BIN}_ON_{FTP,CDROM}</varname>,
-then you can get everything by running:
-</para>
-
-<screen><prompt>%</prompt> <userinput>make fetch NO_SKIP=yes</userinput></screen>
-</sect1>
-
-
-<sect1>
-<title>How to fetch files from behind a firewall</title>
-
-<para>
-If you are sitting behind a firewall which does not allow direct connections
-to Internet hosts (i.e. non-NAT), you may specify the relevant proxy hosts.
-This is done using an environment variable in the form of a URL
-e.g. in Amdahl, the machine <quote>orpheus.amdahl.com</quote> is one of
-the firewalls, and it uses port 80 as the proxy port number. So the proxy
-environment variables are:
-</para>
-
-<programlisting>ftp_proxy=ftp://orpheus.amdahl.com:80/
-http_proxy=http://orpheus.amdahl.com:80/</programlisting>
-</sect1>
-
-
-<sect1>
-<title>If your patch contains an RCS ID</title>
-
-<para>
-See <xref linkend="components.patches"/> for information on how to
-remove RCS IDs from patch files.
-</para>
-</sect1>
-
-
-<sect1>
-<title>How to pull in variables from /etc/mk.conf</title>
-
-<para>
-The problem with package-defined variables that can be overridden via
-<varname>MAKECONF</varname> or <filename>/etc/mk.conf</filename> is that make(1) expands a variable as it is
-used, but evaluates preprocessor like statements (.if, .ifdef and
-.ifndef) as they are read.  So, to use any variable (which may be set
-in <filename>/etc/mk.conf</filename>) in one of the .if* statements, the file
-<filename>/etc/mk.conf</filename>
-must be included before that .if* statement.
-</para>
-
-<para>
-Rather than have a number of ad-hoc ways of including
-<filename>/etc/mk.conf</filename>,
-should it exist, or <varname>MAKECONF</varname>, should it exist, include the
-<filename>pkgsrc/mk/bsd.prefs.mk</filename> file in the package Makefile before any
-preprocessor-like .if, .ifdef, or .ifndef statements:
-</para>
-
-<programlisting>.include "../../mk/bsd.prefs.mk"
-
-.if defined(USE_MENUS)
-  ...
-.endif</programlisting>
-
-<para>
-If you wish to set the CFLAGS variable in /etc/mk.conf please make sure
-to use:
-
-<screen>CFLAGS+=	-your -flags</screen>
-
-Using <varname>CFLAGS=</varname> (ie without the <quote>+</quote>) may
-lead to problems with packages that need to add their own flags.  Also,
-you may want to take a look at the <pkg>devel/cpuflags</pkg> package if
-you're interested in optimization for the current CPU.
-</para>
-</sect1>
-
-<sect1>
-<title>Is there a mailing list for pkg-related discussion?</title>
-
-<para>
-Yes, <email>tech-pkg@NetBSD.org</email> is the list for discussing package
-related issues. To subscribe do:
-</para>
-
-<programlisting>% echo subscribe tech-pkg | mail majordomo@NetBSD.org</programlisting>
-</sect1>
-
-
-<sect1>
-<title>How do I tell <command>make fetch</command> to do passive FTP?</title>
-
-<para>
-This depends on which utility is used to retrieve distfiles. From
-<filename>bsd.pkg.mk</filename>, <varname>FETCH_CMD</varname> is assigned
-the first available command from the following list:
-</para>
-
-<programlisting>/usr/bin/fetch
-${LOCALBASE}/bsd/bin/ftp
-/usr/bin/ftp</programlisting>
-
-<para>
-On a default NetBSD install, this will be
-<filename>/usr/bin/ftp</filename>, which automatically
-tries passive connections first, and falls back to active connections if the
-server refuses to do passive. For the other tools, add the following to your
-<filename>/etc/mk.conf</filename> file:
-<varname>PASSIVE_FETCH=1</varname>.
-</para>
-
-<para>
-Having that option present will prevent
-<filename>/usr/bin/ftp</filename> from falling back to
-active transfers.
-</para>
-</sect1>
-
-
-<sect1>
-<title>Dependencies on other packages</title>
-
-<para>
-Your package may depend on some other package being present - and there are
-various ways of expressing this dependency. NetBSD supports the
-<varname>BUILD_DEPENDS</varname> and <varname>DEPENDS</varname> definitions,
-as well as dependencies via
-<filename>buildlink3.mk</filename> (see <!-- <xref
-linkend="buildlink3"/> -->).
-</para>
-
-<para>
-The basic difference between the two definitions is as follows: The
-<varname>DEPENDS</varname> definition registers that pre-requisite in the binary package,
-whilst the <varname>BUILD_DEPENDS</varname> definition does not.
-</para>
-
-<para>
-This means that if you only need a package present whilst you are building,
-it should be noted as a <varname>BUILD_DEPENDS</varname>.
-</para>
-
-<para>
-The format for a <varname>BUILD_DEPENDS</varname> and a
-<varname>DEPENDS</varname> definition is:
-</para>
-
-<programlisting>&lt;pre-req-package-name&gt;:../../&lt;category&gt;/&lt;pre-req-package&gt;</programlisting>
-
-<para>
-Please note that the <quote>pre-req-package-name</quote> may include any of the wildcard
-version numbers recognised by pkg_info(1).
-</para>
-
-<orderedlist>
-
-<listitem>
-<para>
-If your package needs to use another package to build itself, this
-is specified using the <varname>BUILD_DEPENDS</varname> definition.
-</para>
-
-<programlisting>BUILD_DEPENDS+=  autoconf-2.13:../../devel/autoconf</programlisting>
-</listitem>
-
-<listitem>
-<para>
-If your package needs a library with which to link, this is specified
-using the <varname>DEPENDS</varname> definition.  An example of this is
-the <pkg>print/lyx</pkg>
-package, which uses the xpm library, version 3.4j to build.
-</para>
-
-<programlisting>DEPENDS+=       xpm-3.4j:../../graphics/xpm</programlisting>
-
-<para>
-You can also use wildcards in package dependences:
-</para>
-
-<programlisting>DEPENDS+=	xpm-[0-9]*:../../graphics/xpm</programlisting>
-
-<para>
-Note that such wildcard dependencies are retained when creating binary
-packages.  The dependency is checked when installing the binary
-package and any package which matches the pattern will be used. 
-Wildcard dependencies should be used with care.
-</para>
-
-<para>
-The -[0-9]* should be used instead of -* to avoid potentially
-ambiguous matches such as tk-postgresql matching a tk-*
-<varname>DEPENDS</varname>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-If your package needs some executable to be able to run correctly, this
-is specified using the <varname>DEPENDS</varname> definition. The
-<pkg>print/lyx</pkg> package needs
-to be able to execute the latex binary from the teTeX package when it runs,
-and that is specified:
-</para>
-
-<programlisting>DEPENDS+=        teTeX-[0-9]*:../../print/teTeX</programlisting>
-
-<para>
-The comment about wildcard dependencies from previous paragraph
-applies here, too.
-</para>
-</listitem>
-
-</orderedlist>
-
-<para>
-If your package needs files from another package to build, see the
-first part of the <quote>do-configure</quote> target
-<pkg>print/ghostscript5</pkg> package
-(it relies on the jpeg sources being present in source form during the
-build):
-</para>
-
-<programlisting>if [ ! -e ${_PKGSRCDIR}/graphics/jpeg/${WRKDIR:T}/jpeg-6b ]; then \
-	cd ${_PKGSRCDIR}/../../graphics/jpeg &amp;&amp; ${MAKE} extract;              \
-fi</programlisting>
-
-<para>
-If you build any other packages that way, please make sure the working
-files are deleted too when this package's working files are cleaned up.
-The easiest way to do so is by adding a pre-clean target:
-</para>
-
-<programlisting>pre-clean:
-	cd ${_PKGSRCDIR}/../../graphics/jpeg &amp;&amp; ${MAKE} clean</programlisting>
-
-<para>
-Please also note the <varname>BUILD_USES_MSGFMT</varname> and
-<varname>BUILD_USES_GETTEXT_M4</varname> definitions,
-which are provided as convenience definitions.  The former works out whether
-msgfmt(1) is part of the base system, and, if it isn't, installs the
-<pkg>devel/gettext</pkg> package.  The latter adds a build dependency on either an
-installed version of an older gettext package, or if it isn't, installs the
-<pkg>devel/gettext-m4</pkg> package.
-</para>
-</sect1>
-
-
-<sect1>
-<title>Conflicts with other packages</title>
-
-<para>
-Your package may conflict with other packages a user might already have
-installed on his system, e.g. if your package installs the same set of
-files like another package in our pkgsrc tree.
-</para>
-
-<para>
-In this case you can set <varname>CONFLICTS</varname> to a space separated
-list of packages (including version string) your package conflicts with.
-</para>
-
-<para>
-For example <pkg>x11/Xaw3d</pkg> and
-<pkg>x11/Xaw-Xpm</pkg> install provide the
-same shared library, thus you set in
-<filename>pkgsrc/x11/Xaw3d/Makefile</filename>:
-</para>
-
-<programlisting>CONFLICTS=      Xaw-Xpm-[0-9]*</programlisting>
-
-<para>
-and in <filename>pkgsrc/x11/Xaw-Xpm/Makefile</filename>:
-</para>
-
-<programlisting>CONFLICTS=      Xaw3d-[0-9]*</programlisting>
-
-<para>
-Packages will automatically conflict with other packages with the name prefix
-and a different version string. <quote>Xaw3d-1.5</quote> e.g. will automatically conflict
-with the older version <quote>Xaw3d-1.3</quote>.
-</para>
-</sect1>
-
-
-<sect1>
-<title>Software which has a homepage</title>
-
-<para>
-The NetBSD packages system now supports a variable called
-<varname>HOMEPAGE</varname>.
-If the software being packaged has a home page, the Makefile should
-include the URL for that page in the <varname>HOMEPAGE</varname> variable.
-The definition of the variable should be placed immediately after the
-<varname>MAINTAINER</varname> variable.
-</para>
-</sect1>
-
-
-<sect1>
-<title>How to handle modified distfiles with the 'old' name</title>
-
-<para>
-Sometimes authors of a software package make some modifications after the
-software was released, and they put up a new distfile without changing the
-package's version number. If a package is already in pkgsrc at that time, 
-the md5 checksum will no longer match. The correct way to work around this
-is to update the package's md5 checksum to match the package on the master
-site (beware, any mirrors may not be up to date yet!), and to remove the 
-old distfile from ftp.NetBSD.org's
-<filename>/pub/NetBSD/packages/distfiles</filename> directory.
-Furthermore, a mail to the package's author seems appropriate making sure
-the distfile was really updated on purpose, and that no trojan horse or so
-crept in.
-</para>
-</sect1>
-
-<sect1>
-<title>What does "Don't know how to make /usr/share/tmac/tmac.andoc" mean?</title>
-<para>
-When compiling the <pkg>pkgtools/pkg_install</pkg> package, you get the error
-from make that it doesn't know how to make
-<filename>/usr/share/tmac/tmac.andoc</filename>? This
-indicates that you don't have installed the <quote>text</quote> set on your machine
-(nroff, ...). It is recommended to do that.
-</para>
-
-<para>
-In the case of the <pkg>pkgtools/pkg_install</pkg> package, you can get
-away with setting <varname>NOMAN=YES</varname> either in the environment
-or in <filename>/etc/mk.conf</filename>.
-</para>
-</sect1>
-
-
-<sect1>
-<title>How to handle incrementing versions when fixing an existing
-package</title>
-
-<para>
-When making fixes to an existing package it can be useful to change
-the version number in <varname>PKGNAME</varname>. To avoid conflicting with
-future versions
-by the original author, a <quote>nb1</quote>, <quote>nb2</quote>, ... suffix
-can be used on package
-versions by setting <varname>PKGREVISION=1</varname> (2,. ..). The
-<quote>nb</quote> is treated like a <quote>.</quote> by the pkg tools. e.g.
-</para>
-
-<programlisting>DISTNAME=	foo-17.42
-PKGREVISION=	9</programlisting>
-
-<para>
-will result in a <varname>PKGNAME</varname> of <quote>foo-17.42nb9</quote>.
-</para>
-
-<para>
-When a new release of the package is released, the
-<varname>PKGREVISION</varname> should be
-removed. e.g. on a new minor release of the above package, things should
-be like:
-</para>
-
-<programlisting>DISTNAME=	foo-17.43</programlisting>
-</sect1>
-
-
-<sect1>
-<title>Could not find bsd.own.mk - what's wrong?</title>
-
-<para>
-You didn't install the compiler set, <filename>comp.tgz</filename>, when
-you installed your NetBSD machine. Please get it and install it, by
-extracting it in <filename>/</filename>:
-</para>
-
-<screen><prompt>#</prompt> <userinput>cd /</userinput>
-<prompt>#</prompt> <userinput>tar --unlink -zxvpf .../comp.tgz</userinput></screen>
-
-<para>
-<filename>comp.tgz</filename> is part of every NetBSD release. Get
-the one that corresponds to your release (determine via
-<command>uname -r</command>).
-</para>
-</sect1>
-
-
-<sect1>
-<title>Restricted packages</title>
-
-<para>
-Some licenses restrict how software may be re-distributed.  In order to
-satisfy these restrictions, the package system defines five make variables
-that can be set to note these restrictions:
-</para>
-
-<itemizedlist>
-
-<listitem>
-<para><varname>RESTRICTED</varname></para>
-<para>
-   This variable should be set whenever a restriction exists
-   (regardless of its kind).  Set this variable to a string
-   containing the reason for the restriction.
-</para>
-</listitem>
-
-<listitem> 
-<para><varname>NO_BIN_ON_CDROM</varname></para>
-<para>
-   Binaries may not be placed on CD-ROM.  Set this variable to
-   <varname>${RESTRICTED}</varname> whenever a binary package may not
-   be included on a CD-ROM.
-</para>
-</listitem>
-
-<listitem> 
-<para><varname>NO_BIN_ON_FTP</varname></para>
-<para>
-   Binaries may not be placed on an FTP server.  Set this
-   variable to <varname>${RESTRICTED}</varname> whenever a binary package
-   may not not be made available on the Internet.
-</para>
-</listitem>
-
-<listitem>
-<para><varname>NO_SRC_ON_CDROM</varname></para>
-<para>
-   Distfiles may not be placed on CD-ROM.  Set this variable to
-   <varname>${RESTRICTED}</varname> if re-distribution of the source code
-   or other distfile(s) is not allowed on CD-ROMs.
-</para>
-</listitem>
-
-<listitem> 
-<para><varname>NO_SRC_ON_FTP</varname></para>
-<para>
-   Distfiles may not be placed on FTP.  Set this variable to
-   <varname>${RESTRICTED}</varname> if re-distribution of the source
-   code or other distfile(s) via the Internet is not allowed.
-</para>
-</listitem>
-
-</itemizedlist>
-
-<para>
-Please note that the use of <varname>NO_PACKAGE</varname>,
-<varname>IGNORE</varname>, <varname>NO_CDROM</varname>, or other generic
-make variables to denote restrictions is deprecated, because they
-unconditionally prevent users from generating binary packages!
-</para>
-</sect1>
-
-
-<sect1>
-<title>Packages using (n)curses</title>
-
-<para>
-Some packages need curses functionality that wasn't present in NetBSD's own
-curses prior to 1.4Y.
-</para>
-
-<para>
-If <filename>../../devel/ncurses/buildlink3.mk</filename> is included in
-a package's <filename>Makefile</filename>,
-then a curses library and headers with ncurses functionality are linked
-into <varname>${BUILDLINK_DIR}</varname> at pre-configure time.  If
-ncurses is actually required, then define <varname>USE_NCURSES</varname>
-in the package's <filename>Makefile</filename>:
-<screen>USE_NCURSES=	# redrawwin</screen>
-The comment should indicate which functions are missing.
-
-</para>
-</sect1>
-
-
-<sect1>
-<title>Automated security check</title>
-
-<para>
-Please be aware that there can often be bugs in third-party software,
-and some of these bugs can leave a machine vulnerable to exploitation
-by attackers.  In an effort to lessen the exposure, the NetBSD
-packages team maintains a database of known-exploits to packages which
-have at one time been included in pkgsrc.  The database can be
-downloaded automatically, and a security audit of all packages
-installed on a system can take place.  To do this, install the
-<pkg>security/audit-packages</pkg> package.  It has two components:
-</para>
-
-<orderedlist>
-
-<listitem>
-<para>
-     <quote>download-vulnerability-list</quote>, an easy way to download a list of the
-     security vulnerabilities information. This list is kept up to date by
-     the NetBSD security officer and the NetBSD packages team, and is
-     distributed from the NetBSD ftp server:
-</para>
-<para>
-<ulink
-url="ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/pkg-vulnerabilities"/>
-</para>
-</listitem>
-
-<listitem>
-<para>
-     <quote>audit-packages</quote>, an easy way to audit the current machine, checking
-     each vulnerability which is known. If a vulnerable package is
-     installed, it will be shown by output to stdout, including a
-     description of the type of vulnerability, and a URL containing more
-     information.
-</para>
-</listitem>
-
-</orderedlist>
-
-<para>
-Use of the audit-packages package is strongly recommended.
-</para>
-
-<para>
-The following message is displayed as part of the audit-packages
-installation procedure:
-</para>
-
-<screen>
-======================================================================
-You may wish to have the vulnerabilities file downloaded daily so that
-it remains current.  This may be done by adding an appropriate entry
-to the root users crontab(5) entry.  For example the entry
-	
-# download vulnerabilities file
-0 3 * * * ${PREFIX}/sbin/download-vulnerability-list &gt;/dev/null 2&gt;&amp;1
-	
-will update the vulnerability list every day at 3AM.
-	
-In addition, you may wish to run the package audit from the daily
-security script.  This may be accomplished by adding the following
-lines to /etc/security.local
-	
-if [ -x ${PREFIX}/sbin/audit-packages ]; then
-	${PREFIX}/sbin/audit-packages
-fi
-======================================================================
-</screen>
-
-<para>
-Note to package developers: When a vulnerability is found, this should be
-noted in
-<filename>localsrc/security/advisories/pkg-vulnerabilities</filename>, and after the
-commit of that file, it should be copied to both
-<filename>/pub/NetBSD/packages/distfiles/pkg-vulnerabilities</filename>
-and
-<filename>/pub/NetBSD/packages/distfiles/vulnerabilities</filename> on
-ftp.NetBSD.org by
-<filename>localsrc/security/advisories/Makefile</filename>.
-</para>
-</sect1>
-
-
-<sect1>
-<title>What's the proper way to create an account from a package?</title>
-
-<para>
-There are two make variables used to control the creation of package-specific
-groups and users at pre-install time.  The first is
-<varname>PKG_GROUPS</varname>, which is a
-list of group[:groupid] elements, where the groupid is optional.  The second
-is <varname>PKG_USERS</varname>, which is a list of elements of the form:
-</para>
-
-<programlisting>user:group[:[userid][:[description][:[home][:shell]]]]</programlisting>
-
-<para>
-where only the user and group are required, the rest being optional.  A
-simple example is:
-</para>
-
-<programlisting>PKG_GROUPS=	foogroup
-PKG_USERS=	foouser:foogroup</programlisting>
-
-<para>
-A more complex example is that creates two groups and two users is:
-</para>
-
-<programlisting>PKG_GROUPS=	group1 group2:1005
-PKG_USERS=	first:group1::First\\ User			\
-		second:group2::Second\\ User:/home/second:${SH}</programlisting>
-
-<para>
-By default, a new user will have home directory
-<filename>/nonexistent</filename>, and login shell
-<filename>/sbin/nologin</filename> unless they are specified as part of
-the user element.
-</para>
-
-<para>
-The package Makefile must also set
-<varname>USE_PKGINSTALL=YES</varname>. This will cause the users and groups
-to be created at pre-install time, and the admin will be prompted to remove
-them at post-deinstall time.  Automatic creation of the users and groups
-can be toggled on and off by setting the environment variable
-<varname>PKG_CREATE_USERGROUP</varname> prior to package installation.
-</para>
-</sect1>
-
-
-<sect1>
-<title>How to handle compiler bugs</title>
-
-<para>
-Some source files trigger bugs in the compiler, based on combinations
-of compiler version and architecture and almost always relation to
-optimisation being enabled.  Common symptoms are gcc internal errors
-or never finishing compiling a file.
-</para>
-
-<para>
-Typically a workaround involves testing the <varname>MACHINE_ARCH</varname>
-and compiler version, disabling optimisation for that
-file/<varname>MACHINE_ARCH</varname>/compiler
-combination, and documenting it in <filename>doc/HACKS</filename>. See
-<filename>doc/HACKS</filename> for examples.
-</para>
-</sect1>
-
-
-<sect1 id="features.info-files">
-<title>Packages providing info files</title>
-
-<para>
-Some packages install info files or use the <quote>makeinfo</quote>
-or <quote>install-info</quote> commands. Each of the info files:
-<itemizedlist>
-<listitem>is considered to be installed in the directory
-          <filename>${PREFIX}/${INFO_DIR}</filename>,</listitem>
-<listitem>is registered in the Info directory file
-          <filename>${PREFIX}/${INFO_DIR}/dir</filename>,</listitem>
-<listitem>and must be listed as a filename in the
-          <varname>INFO_FILES</varname> variable in the package
-          Makefile.</listitem>
-</itemizedlist>
-</para>
-
-<para>
-<varname>INFO_DIR</varname> defaults to <quote>info</quote> and can be
-overridden in the package Makefile. <filename>INSTALL</filename> and
-<filename>DEINSTALL</filename> scripts will be generated to handle
-registration of the info files in the Info directory file. The
-<quote>install-info</quote> command used for the info files registration is
-either provided by the system, or by a special purpose package
-automatically added as dependency if needed.
-</para>
-
-<para>
-A package which needs the <quote>makeinfo</quote> command at build
-time must define the variable <varname>USE_MAKEINFO</varname> in its
-Makefile. If a minimum version of the <quote>makeinfo</quote> command
-is needed it should be noted with the <varname>TEXINFO_REQD</varname>
-variable in the package <filename>Makefile</filename>. By default, a
-minimum version of 3.12 is required. If the system does not provide a
-<command>makeinfo</command> command or if it does not match the required
-minimum, a build dependency on the <pkg>devel/gtexinfo</pkg> package
-will be added automatically.
-</para>
-
-<para>
-The build and installation process of the software provided by the package
-should not use the <command>install-info</command> command as the
-registration of info files is the task of the package
-<filename>INSTALL</filename> script, and it must use the appropriate
-<command>makeinfo</command> command.
-</para>
-
-<para>
-To achieve this goal the pkgsrc infrastructure creates overriding scripts
-for the <command>install-info</command> and <command>makeinfo</command>
-commands in a directory listed early in <varname>PATH</varname>.
-</para>
-
-<para>
-The script overriding <command>install-info</command> has no effect except
-the logging of a message. The script overriding <command>makeinfo</command>
-logs a message and according to the value of <varname>USE_MAKEINFO</varname>
-and <varname>TEXINFO_REQD</varname> either run the appropriate
-<command>makeinfo</command> command or exit on error.
-</para>
-</sect1>
-
-<sect1>
-<title>Packages whose distfiles aren't available for plain downloading</title>
-
-<para>
-If you need to download from a dynamic URL you can set
-<varname>DYNAMIC_MASTER_SITES</varname>
-and a <command>make fetch</command> will call
-<filename>files/getsite.sh</filename> with the name of each file
-to download as an argument, expecting it to output the URL of the directory
-from which to download it. <pkg>graphics/ns-cult3d</pkg> is an example of this usage.
-</para>
-
-<para>
-If the download can't be automated, because the user must submit personal
-information to apply for a password, or must pay for the source, or whatever,
-you can set <varname>_FETCH_MESSAGE</varname> to a macro which displays
-a message explaining the situation. <varname>_FETCH_MESSAGE</varname> must
-be executable shell commands, not just a message. (Generally, it executes
-<varname>${ECHO}</varname>). As of this writing, the following
-packages use this: <pkg>audio/realplayer</pkg>,
-<pkg>cad/simian</pkg>, <pkg>devel/ipv6socket</pkg>,
-<pkg>emulators/vmware-module</pkg>,
-<pkg>fonts/acroread-jpnfont</pkg>,
-<pkg>sysutils/storage-manager</pkg>,
-<pkg>www/ap-aolserver</pkg>, <pkg>www/openacs</pkg>. Try to be consistent
-with them.
-</para>
-</sect1>
-
-<sect1>
-<title>Configuration files handling and placement</title>
-
-<para>
-The global variable <varname>PKG_SYSCONFBASE</varname> (and some others)
-can be set by the system administrator in <filename>/etc/mk.conf</filename>
-to define the place where
-configuration files get installed. Therefore, packages must be adapted to
-support this feature. Keep in mind that you should only install files that
-are strictly necessary in the configuration directory, files that can
-go to <filename>$PREFIX/share</filename> should go there.
-</para>
-
-<para>
-We will take a look at available variables first
-(<filename>bsd.pkg.mk</filename> contains more
-information). <varname>PKG_SYSCONFDIR</varname> is where the
-configuration files for a package
-may be found (that is, the full path, e.g. <filename>/etc</filename>
-or <filename>/usr/pkg/etc</filename>). This
-value may be customized in various ways:
-</para>
-
-<orderedlist>
-
-<listitem>
-<para>
-    <varname>PKG_SYSCONFBASE</varname> is the main config directory under
-    which all package configuration files are to be found. Users will
-    typically want to set it to <filename>/etc</filename>, or accept the
-    default location of <filename>$PREFIX/etc</filename>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-    <varname>PKG_SYSCONFSUBDIR</varname> is the subdirectory of
-    <varname>PKG_SYSCONFBASE</varname> under which
-    the configuration files for a particular package may be found. Defaults
-    to <varname>${SYSCONFBASE}</varname>.
-</para>
-</listitem>
-
-<listitem>
-<para>
-    <varname>PKG_SYSCONFVAR</varname> is the special suffix used to
-    distinguish any overriding values for a particular package
-    (see next item). It defaults to <varname>${PKGBASE}</varname>, but
-    for a collection of related packages that should all have the same
-    <varname>PKG_SYSCONFDIR</varname> value, it can be set in each of
-    the package Makefiles to a common value.
-</para>
-</listitem>
-
-<listitem>
-<para>
-    <varname>PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</varname> overrides the value of
-    <varname>${PKG_SYSCONFDIR}</varname> for packages with the same value
-    for <varname>PKG_SYSCONFVAR</varname>.
-</para>
-
-<para>
-    As an example, all the various KDE packages may want to set
-    <varname>PKG_SYSCONFVAR</varname> to <quote>kde</quote> so admins can
-    set <varname>PKG_SYSCONFDIR.kde</varname> in
-    <filename>/etc/mk.conf</filename> to define where to install KDE
-    config files.
-</para>
-</listitem>
-
-</orderedlist>
-
-<para>
-Programs' configuration directory should be defined during the configure
-stage. Packages that use GNU autoconf can usually do this by using the
-<quote>--sysconfdir</quote> parameter, but this brings some problems as
-we will see now.
-When you change this pathname in packages, you should not allow them to
-install files in that directory directly. Instead they need to install
-those files under <filename>share/examples/${PKGNAME}</filename> so
-<filename>PLIST</filename> can register them.
-</para>
-
-<para>
-Once you have the required configuration files in place (under the
-<filename>share/examples</filename> directory) the variable
-<varname>CONF_FILES</varname> should be set to copy
-them into <varname>PKG_SYSCONFDIR</varname>. The contents of this variable
-is formed by pairs
-of filenames; the first element of the pair specifies the file inside the
-examples directory (registered by <filename>PLIST</filename>) and the
-second element specifies
-the target file. This is done this way to allow binary packages to place
-files in the right directory using
-<filename>INSTALL</filename>/<filename>DEINSTALL</filename> scripts which are
-created automatically.  The package <filename>Makefile</filename> must also
-set <varname>USE_PKGINSTALL=YES</varname> to use
-these automatically generated scripts.  The automatic copying of config
-files can be toggled by setting the environment variable
-<varname>PKG_CONFIG</varname> prior to package installation.
-</para>
-
-<para>
-Here is an example, taken from mail/mutt/Makefile:
-</para>
-
-<programlisting>EGDIR=		${PREFIX}/share/doc/mutt/samples
-CONF_FILES=	${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc</programlisting>
-
-<para>
-As you can see, this package installs configuration files inside
-<varname>EGDIR</varname>, which are registered by
-<filename>PLIST</filename>. After that, the variable
-<varname>CONF_FILES</varname> lists
-the installed file first and then the target file. Users will also get an
-automatic message when files are installed using this method.
-</para>
-</sect1>
-
-
-<sect1>
-<title>Packages providing login shells</title>
-
-<para>
-If the purpose of the package is to provide a login shell, the variable
-<varname>PKG_SHELL</varname> should contain the full pathname of the
-shell executable installed by this package. The package
-<filename>Makefile</filename> must also set
-<varname>USE_PKGINSTALL=YES</varname> to use the automatically generated
-<filename>INSTALL</filename>/<filename>DEINSTALL</filename> scripts.
-</para>
-
-<para>
-An example taken from shells/zsh:
-</para>
-
-<programlisting>USE_PKGINSTALL=	YES
-...
-PKG_SHELL=	${PREFIX}/bin/zsh</programlisting>
-
-<para>
-The shell is registered into <filename>/etc/shells</filename> file automatically in the
-post-install target by the generated <filename>INSTALL</filename> script
-and removed in the deinstall
-target by the <filename>DEINSTALL</filename> script.
-</para>
-</sect1>
-
-
-<sect1>
-<title>Packages providing locale catalogues</title>
-
-<para>
-If the package provides its own locale catalogues, the variable
-<varname>USE_PKGLOCALEDIR</varname> should be defined.  It will ensure
-that the package's <filename>Makefile</filename> template files are fixed
-and point to the correct locale directories
-(which may vary, depending on OS), if necessary.  See <xref
-linkend="plist.misc"/> for details about <varname>PKGLOCALEDIR</varname>.
-This functionality is buildlink3-only.
-</para>
-</sect1>
-
-
-<sect1>
-<title>Using 'sudo' with pkgsrc</title>
-
-<para>
-When installing packages as non-root user and using the just-in-time
-su(1) feature of pkgsrc, it can become annoying to type in the root
-password for each required package installed. To avoid this, the sudo
-package can be used, which does password caching over a limited time.
-To use it, install sudo (either as binary package or from
-<pkg>security/sudo</pkg>) and then put the following
-into your <filename>/etc/mk.conf</filename>:
-</para>
-
-<programlisting>SU_CMD=/usr/pkg/bin/sudo /bin/sh -c</programlisting>
-</sect1>
-
-
-<sect1>
-<title>Packages containing perl scripts</title>
-
-<para>
-If your package contains interpreted perl scripts, set
-<varname>REPLACE_PERL</varname> to ensure that the proper interpreter
-path is set. <varname>REPLACE_PERL</varname> should contain a list of
-scripts, relative to <varname>WRKSRC</varname>, that you want adjusted.
-</para>
-</sect1>
-
-<sect1>
-<title>Packages with hardcoded paths to other interpreters</title>
-
-<para>
-Your package may also contain scripts with hardcoded paths to other
-interpreters besides (or as well as) perl.  To correct the full
-pathname to the script interpreter, you need to set the following
-definitions in your <filename>Makefile</filename> (we shall use
-<command>tclsh</command> in this example):
-
-<programlisting>REPLACE_INTERPRETER+=	tcl
-_REPLACE.tcl.old=	.*/bin/tclsh
-_REPLACE.tcl.new=	${PREFIX}/bin/tclsh
-_REPLACE_FILES.tcl=	...list of tcl scripts which need to be fixed,
-			relative to ${WRKSRC}, just as in REPLACE_PERL</programlisting>
-</para>
-</sect1>
-
-<sect1>
-<title>Utilities for package management (pkgtools)</title>
-
-<para>
-The directory pkgtools contains a number of useful utilities.  This section
-attempts only to make the reader aware of the utilities and when they might
-be useful, and not to duplicate the documentation that comes with each
-package.
-</para>
-
-<para>
-Utilities used by pkgsrc (automatically installed when needed):
-<itemizedlist>
-<listitem>x11-links
-  <para>
-    symlinks for use by buildlink
-  </para>
-</listitem>
-</itemizedlist>
-</para>
-
-<para>
-OS tool augmentation (automatically installed when needed):
-<itemizedlist>
-<listitem>digest
-  <para>
-    calculates SHA1 checksums (and other kinds)
-  </para>
-</listitem>
-<listitem>libnbcompat
-  <para>
-    compat library for pkg tools
-  </para>
-</listitem>
-<listitem>mtree
-  <para>
-    installed on non-BSD systems due to lack of native mtree
-  </para>
-</listitem>
-<listitem>pkg_install
-  <para>
-    up-to-date replacement for /usr/sbin/pkg_install, or for
-    use on operating systems where pkg_install is not present
-  </para>
-</listitem>
-</itemizedlist>
-</para>
-
-<para>
-Utilities used by pkgsrc (not automatically installed):
-<itemizedlist>
-<listitem>pkg_tarup
-  <para>
-    create a binary package from an already-installed package.
-    used by 'make replace' to save the old package
-  </para>
-</listitem>
-<listitem>xpkgwedge
-  <para>
-    put X11 packages someplace else (see above)
-  </para>
-</listitem>
-</itemizedlist>
-</para>
-
-<para>
-Utilities for keeping track of installed packages, being up to date, etc:
-<itemizedlist>
-<listitem>pkgchk
-  <para>
-    installs pkg_chk, which reports on packages whose installed
-    versions do not match the latest pkgsrc entries
-  </para>
-</listitem>
-<listitem>pkgdep
-  <para>
-    makes dependency graphs of packages, to aid in choosing a
-    strategy for updating
-  </para>
-</listitem>
-<listitem>pkgdepgraph
-  <para>
-    make graph from above (uses graphviz)
-  </para>
-</listitem>
-<listitem>pkglint
-  <para>
-    This provides two distinct abilities:
-    check a pkgsrc entry for correctness (pkglint)
-    check for and remove out-of-date distfiles and binary
-    packages (lintpkgsrc)
-  </para>
-</listitem>
-<listitem>pkgsurvey
-  <para>
-    report what packages you have installed
-  </para>
-</listitem>
-</itemizedlist>
-</para>
-
-<para>
-Utilities for people maintaining or creating individual packages:
-<itemizedlist>
-<listitem>pkgdiff
-  <para>
-    automate making and maintaining patches for a package
-  </para>
-</listitem>
-<listitem>rpm2pkg, url2pkg
-  <para>
-    aids in converting to pkgsrc
-  </para>
-</listitem>
-<listitem>gensolpkg
-  <para>
-    convert pkgsrc to a Solaris package
-  </para>
-</listitem>
-</itemizedlist>
-</para>
-
-<para>
-Utilities for people maintaining pkgsrc (or more obscure pkg utilities)
-<itemizedlist>
-<listitem>pkgconflict
-  <para>
-    find packages that conflict but aren't marked as such
-  </para>
-</listitem>
-<listitem>pkgcomp
-  <para>
-    build packages in a chrooted area
-  </para>
-</listitem>
-<listitem>libkver
-  <para>
-    spoof kernel version for chrooted cross builds
-  </para>
-</listitem>
-</itemizedlist>
-</para>
-
-</sect1>
-
-<sect1>
-<title>How to use pkgsrc as non-root</title>
-<para>
-If you want to use pkgsrc as non-root user, you can set some variables
-to make pkgsrc work under these conditions. Please see 
-<ulink
-url="http://mail-index.netbsd.org/tech-pkg/2003/09/27/0023.html">this
-message</ulink> for more details.
-</para>
-</sect1>
-
-
-<sect1>
-<title>Packages that cannot or should not be built</title>
-
-<para>
-There are several reasons why a package might be instructed to not
-build under certain circumstances. If the package builds and runs
-on most platforms, the exceptions should be noted with
-<varname>NOT_FOR_PLATFORM</varname>. If the package builds and runs on
-a small handful of platforms, set <varname>ONLY_FOR_PLATFORM</varname>
-instead. If the package should be skipped (for example, because it
-provides functionality already provided by the system), set
-<varname>PKG_SKIP_REASON</varname> to a descriptive message. If
-the package should fail because some preconditions are not met,
-set <varname>PKG_FAIL_REASON</varname> to a descriptive message.
-</para>
-
-<para>
-<varname>IGNORE</varname> is deprecated because it didn't provide enough
-information to determine whether the build should fail.
-</para>
-</sect1>
-
-</chapter>