Document some more variables.

2 files changed, 261 insertions, 125 deletions

diff --git a/doc/guide/files/components.xml b/doc/guide/files/components.xml
index 724aece1d02..ed8c22f9b5e 100644
--- a/doc/guide/files/components.xml
+++ b/doc/guide/files/components.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: components.xml,v 1.9 2005/07/27 21:29:50 rpaulo Exp $ -->
+<!-- $NetBSD: components.xml,v 1.10 2005/07/28 11:05:36 wiz Exp $ -->
 
 <chapter id="components"> <?dbhtml filename="components.html"?>
   <title>Package components - files, directories and contents</title>
@@ -37,106 +37,150 @@
       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></listitem>
+	    which the package fits in. You can choose any of the top-level
+	    directories of pkgsrc for it.</para>
 
-      <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></listitem>
+	<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 URI's
+	    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 the following variables.
+    <para>The second section contains information about separately
+      downloaded patches, if any.
+      <itemizedlist><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>.
+	<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 mail address of the
-      package's maintainer, which is the person you can contact when the
-      package does not work.</para></listitem>
+      <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 comment about
-      the purpose of 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>The <varname>MASTER_SITES</varname> may be set to one of the
-      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 require the
-      ability 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>
-
-    <note>
-      <para><varname>MASTER_SITE_SUBDIR</varname> has been deprecated and
-        <emphasis>should no longer be used</emphasis>.</para>
-    </note>
-
-    <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 URI's 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>
-
-    <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>
-
-    <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>
-
-    <para> Please pay attention to the following gotchas: </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>Please pay attention to the following gotchas:</para>
 
     <itemizedlist>
       <listitem>
@@ -155,23 +199,6 @@ converters    games         mbone         print         x11</programlisting>
           <xref linkend="faq.info-files"/>.</para>
       </listitem>
 
-      <listitem>
-        <para>Set <varname>MAINTAINER</varname> to be 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>If a home page for the software in question exists, 
-          add the variable <varname>HOMEPAGE</varname> right after
-          <varname>MAINTAINER</varname>. The value of this
-          variable should be the URL for the home page.</para>
-      </listitem>
-
-      <listitem>
-        <para>Be sure to set the <varname>COMMENT</varname> variable to a short
-          description of the package, not containing the pkg's name.</para>
-      </listitem>
     </itemizedlist>
   </sect1>
 
@@ -357,21 +384,24 @@ converters    games         mbone         print         x11</programlisting>
     <title><filename>work*</filename></title>
 
     <para>When you type <command>make</command> the distribution files are
-      unpacked into this directory. It can be removed by running
+      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.</para>
-      
+      directory is also used to keep various timestamp files.
+      The directory gets <note>removed completely</note> 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>
+      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> Please note that the old <varname>NO_WRKSUBDIR</varname>
-      has been deprecated and should not be used. Also, if your
-      package doesn't create a subdir with the name of
+    <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 
diff --git a/doc/guide/files/configuring.xml b/doc/guide/files/configuring.xml
index 2a1beac0a73..2b277a09417 100644
--- a/doc/guide/files/configuring.xml
+++ b/doc/guide/files/configuring.xml
@@ -1,13 +1,96 @@
-<!-- $NetBSD: configuring.xml,v 1.3 2005/07/26 17:29:13 wiz Exp $ -->
+<!-- $NetBSD: configuring.xml,v 1.4 2005/07/28 11:05:36 wiz Exp $ -->
 
 <chapter id="configuring">
   <title>Configuring pkgsrc</title>
 
-  <!-- General configuration -->
-  <!--	DISTDIR -->
-  <!--	PACKAGES -->
-  <!--	WRKOBJDIR -->
-  <!--	FAILOVER_FETCH -->
+  <sect1 id="general-configuration">
+    <title>General configuration</title>
+
+    <para>In this section you can find some variables that apply all
+      pkgsrc packages.  The preferred method of setting them is by
+      setting them in <filename>/etc/mk.conf</filename>.
+      <unorderedlist>
+	<listitem><para><varname>LOCALBASE</varname>: Where
+	    packages will be installed. The default is
+	    <filename>/usr/pkg</filename>. Do not mix binary packages
+	    with different <varname>LOCALBASE</varname>s!</para>
+	</listitem>
+	<listitem><para><varname>CROSSBASE</varname>: Where
+	    <quote>cross</quote> category packages will be
+	    installed. The default is
+	    <filename>${LOCALBASE}/cross</filename>.</para>
+	</listitem>
+	<listitem><para><varname>X11BASE</varname>: Where
+	    X11 is installed on the system. The default is
+	    <filename>/usr/X11R6</filename>.</para>
+	</listitem>
+	<listitem><para><varname>DISTDIR</varname>: Where to store the
+	    downloaded copies of the original source distributions used
+	    for building pkgsrc packages. The default is
+	    <filename>${PKGSRCDIR}/distfiles</filename>.</para>
+	</listitem>
+	<listitem><para><varname>MASTER_SITE_OVERRIDE</varname>:
+	    If set, override the packages'
+	    <varname>MASTER_SITES</varname> with this value.</para>
+	</listitem>
+	<listitem><para><varname>MASTER_SITE_BACKUP</varname>:
+	    Backup location(s) for distribution files and patch files
+	    if not found locally or in
+	    <filename>${MASTER_SITES}</filename> or
+	    <filename>${PATCH_SITES}</filename> respectively.
+	    The defaults are
+	    <filename>ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/${DIST_SUBDIR}/</filename>
+	    and
+	    <filename>ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/</filename>.</para>
+	</listitem>
+	<listitem><para><varname>BINPKG_SITES</varname>:
+	    List of sites carrying binary pkgs.</para>
+	</listitem>
+      </unorderedlist>
+    </para>
+  </sect1>
+
+  <sect1 tag="general-configuration">
+    <title>General configuration</title>
+    <para>XXX
+      <unorderedlist>
+	<listitem><para><varname>PACKAGES</varname>: The top level
+	    directory for the binary packages. The default is
+	    <filename>${PKGSRCDIR}/packages</filename>.</para>
+	</listitem>
+	<listitem><para><varname>WRKOBJDIR</varname>:
+	    The top level directory where, if defined, the separate
+	    working directories will get created, and symbolically
+	    linked to from <filename>${WRKDIR}</filename> (see below).
+	    This is useful for building packages on several
+	    architectures, then <filename>${PKGSRCDIR}</filename>
+	    can be NFS-mounted while <filename>${WRKOBJDIR}</filename>
+	    is local to every architecture. (It should be noted that
+	    <varname>PKGSRCDIR</varname> should not be set by the user
+	    &mdash; it is an internal definition which refers to the
+	    root of the pkgsrc tree. It is possible to have many
+	    pkgsrc tree instances.)</para>
+	</listitem>
+	<listitem><para><varname>LOCALPATCHES</varname>:
+	    Directory for local patches that aren't part of pkgsrc.
+	    See <xref linkend="components.patches" /> for more
+	    information. <replaceable>rel</replaceable> and
+	    <replaceable>arch</replaceable> are replaced with OS
+	    release (<quote>2.0</quote>, etc.) and architecture
+	    (<quote>mipsel</quote>, etc.).</para>
+	</listitem>
+	<listitem><para><varname>PKGMAKECONF</varname>: Location of
+	    the <filename>mk.conf</filename> file used by a package's
+	    BSD-style Makefile. If this is not set,
+	    <varname>MAKECONF</varname> is set to
+	    <filename>/dev/null</filename> to avoid picking up
+	    settings used by builds in <filename>/usr/src</filename>.</para>
+	</listitem>
+	<!--	DISTDIR -->
+	<!--	FAILOVER_FETCH -->
+      </unorderedlist>
+    </para>
+  </sect1>
 
   <!-- Compiler settings -->
   <!--	PKGSRC_COMPILER -->
@@ -21,15 +104,39 @@
   <!--	ALLOW_VULNERABLE_PACKAGES -->
   <!--	PKGVULNDIR -->
 
-  <!-- Developer/advanced settings -->
-  <!--	IGNORE_RECOMMENDED -->
-  <!--	PKG_DEVELOPER -->
+  <sect1 id="developer-advanced-settings">
+    <title>Developer/advanced settings</title>
+
+    <!--	IGNORE_RECOMMENDED -->
+    <para>XXX
+      <unorderedlist>
+	<listitem><para><varname>PKG_DEVELOPER</varname>:
+	    Run some sanity checks that package developers want:
+	    <unorderedlist>
+	      <listitem>make sure patches apply with zero fuzz</listitem>
+	      <listitem>run check-shlibs to see that all binaries will
+		find their shared libs.</listitem>
+	      <!-- XXX: some more stuff -->
+	    </unorderedlist></para></listitem>
+	<listitem><para><varname>PKG_DEBUG_LEVEL</varname>:
+	    The level of debugging output which is displayed whilst
+	    making and installing the package.
+	    The default value for this is 0, which will not display
+	    the commands as they are executed (normal, default, quiet
+	    operation); the value 1 will display all shell commands
+	    before their invocation, and the value 2 will display both
+	    the shell commands before their invocation, and their
+	    actual execution progress with <command>set -x</command>
+	    will be displayed.</para></listitem>
+      </unorderedlist>
+    </para>
+  </sect1>
 
   <!-- pkginstall-related variables -->
   <!--	PKG_REGISTER_SHELLS -->
   <!--	PKG_RCD_SCRIPTS -->
 
-  <sect1 id="selecting-options">
+  <sect1 id="selecting-build-options">
     <title>Selecting Build Options</title>
 
     <para>Some packages have build time options, usually to select between
@@ -93,7 +200,6 @@
       update <filename>/etc/mk.conf</filename> to use the options framework
       directly.  Support for these legacy variables will be removed
       eventually.</para>
-
   </sect1>
 
 </chapter>