Add chapter about configuring pkgsrc, as proposed on tech-pkg by jmmv, and

fill in section about options framework.

4 files changed, 80 insertions, 4 deletions

diff --git a/doc/guide/files/Makefile b/doc/guide/files/Makefile
index 89b0b420ae0..074a4999860 100644
--- a/doc/guide/files/Makefile
+++ b/doc/guide/files/Makefile
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.3 2005/06/03 12:27:48 jmmv Exp $
+# $NetBSD: Makefile,v 1.4 2005/06/08 13:59:30 dillo Exp $
 
 WEB_PREFIX?=	${.CURDIR}/../htdocs
 
@@ -9,6 +9,7 @@ SRCS+=	binary.xml
 SRCS+=	build.xml
 SRCS+=	buildlink.xml
 SRCS+=	components.xml
+SRCS+=	configuring.xml
 SRCS+=	debug.xml
 SRCS+=	examples.xml
 SRCS+=	faq.xml
diff --git a/doc/guide/files/chapters.ent b/doc/guide/files/chapters.ent
index 8ce6d4b7a43..c2e312be87b 100644
--- a/doc/guide/files/chapters.ent
+++ b/doc/guide/files/chapters.ent
@@ -1,13 +1,14 @@
 <!--
 	Creates entities for each chapter in the pkgsrc book.
 
-	$NetBSD: chapters.ent,v 1.4 2005/06/03 12:27:48 jmmv Exp $
+	$NetBSD: chapters.ent,v 1.5 2005/06/08 13:59:30 dillo Exp $
 -->
 
 <!-- users-guide -->
 <!ENTITY chap.intro			SYSTEM "introduction.xml">
 <!ENTITY chap.getting			SYSTEM "getting.xml">
 <!ENTITY chap.using			SYSTEM "using.xml">
+<!ENTITY chap.configuring		SYSTEM "configuring.xml">
 <!ENTITY chap.binary			SYSTEM "binary.xml">
 <!ENTITY chap.components		SYSTEM "components.xml">
 <!ENTITY chap.plist			SYSTEM "plist.xml">
diff --git a/doc/guide/files/configuring.xml b/doc/guide/files/configuring.xml
new file mode 100644
index 00000000000..a7be4f3f6c3
--- /dev/null
+++ b/doc/guide/files/configuring.xml
@@ -0,0 +1,73 @@
+<!-- $NetBSD: configuring.xml,v 1.1 2005/06/08 13:59:30 dillo Exp $ -->
+
+<chapter id="configuring">
+<title>Configuring pkgsrc</title>
+
+<sect1 id="selecting-options">
+<title>Selecting build options</title>
+
+<para>Some packages have build time options, usually to select between
+different dependencies, enable optional support for big dependencies
+or enable experimental features.</para>
+
+<para>To see which options, if any, a package supports, and which
+options are mutually exclusive, run <command>make show-options</command>,
+for example:</para>
+
+<programlisting>
+The following options are supported by this package:
+        ssl      Enable SSL support.
+Exactly one of the following gecko options is required:
+        firefox  Use firefox as gecko rendering engine.
+        mozilla  Use mozilla as gecko rendering engine.
+At most one of the following database options may be selected:
+        mysql    Enable support for MySQL database.
+        pgsql    Enable support for PostgreSQL database.
+
+These options are enabled by default: firefox
+These options are currently enabled: mozilla ssl
+</programlisting>
+
+<para>The following variables can be defined in
+<filename>/etc/mk.conf</filename> to select which options to enable
+for a package: <varname>PKG_DEFAULT_OPTIONS</varname>, which can be
+used to select or disable options for all packages that support them,
+and <varname>PKG_OPTIONS.<replaceable>pkgbase</replaceable></varname>,
+which can be used to select or disable options specifically for
+package <replaceable>pkgbase</replaceable>.  Options listed in these
+variables are selected, options preceded by <quote>-</quote> are
+disabled.</para>
+
+<para>The following settings are consulted in the order given, and the
+last setting that selects or disables an option is used:</para>
+
+<orderedlist>
+<listitem><para>the default options as suggested by the package
+maintainer</para></listitem>
+
+<listitem><para>the options implied by the settings of legacy
+variables (see below)</para></listitem>
+
+<listitem><para><varname>PKG_DEFAULT_OPTIONS</varname></para></listitem>
+
+<listitem><para><varname>PKG_OPTIONS.<replaceable>pkgbase</replaceable></varname></para></listitem>
+</orderedlist>
+
+<para>For groups of mutually exclusive options, the last option
+selected is used, all others are automatically disabled.  If an option
+of the group is explicitly disabled, the previously selected option,
+if any, is used.  It is an error if no option from a required group of
+options is selected, and building the package will fail.</para>
+
+<para>Before the options framework was introduced, build options were
+selected by setting a variable in <filename>/etc/mk.conf</filename>
+for each option.  To ease transition to the options framework for the
+user, these legacy variables are converted to the appropriate options
+setting automatically.  A warning is issued to prompt the user to
+update <filename>/etc/mk.conf</filename> to use the options framework
+directly.  Support for these legacy variables will be removed
+eventually.</para>
+
+</sect1>
+
+</chapter>
diff --git a/doc/guide/files/pkgsrc.xml b/doc/guide/files/pkgsrc.xml
index 0b80f45275a..88db07b6c1e 100644
--- a/doc/guide/files/pkgsrc.xml
+++ b/doc/guide/files/pkgsrc.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: pkgsrc.xml,v 1.8 2005/06/03 12:27:48 jmmv Exp $ -->
+<!-- $NetBSD: pkgsrc.xml,v 1.9 2005/06/08 13:59:30 dillo Exp $ -->
 
 
 <?xml version="1.0"?>
@@ -45,7 +45,7 @@
       <holder role="mailto:www@NetBSD.org">The NetBSD Foundation, Inc</holder>
     </copyright>
 
-    <pubdate>$NetBSD: pkgsrc.xml,v 1.8 2005/06/03 12:27:48 jmmv Exp $</pubdate>
+    <pubdate>$NetBSD: pkgsrc.xml,v 1.9 2005/06/08 13:59:30 dillo Exp $</pubdate>
 
     <abstract>
       <para>Information about using the NetBSD package system (pkgsrc)
@@ -62,6 +62,7 @@
     &chap.getting;
     &chap.platform;
     &chap.using;
+    &chap.configuring;
     &chap.binary;
     &chap.faq;
   </part>