[pkgsrc/trunk]: pkgsrc/doc/guide/files Add chapter about configuring pkgsrc, ...

[dillo <dillo%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/b4fabd6a0319
branches:  trunk
changeset: 495394:b4fabd6a0319
user:      dillo <dillo%pkgsrc.org@localhost>
date:      Wed Jun 08 13:59:30 2005 +0000

description:
Add chapter about configuring pkgsrc, as proposed on tech-pkg by jmmv, and
fill in section about options framework.

diffstat:

 doc/guide/files/Makefile        |   3 +-
 doc/guide/files/chapters.ent    |   3 +-
 doc/guide/files/configuring.xml |  73 +++++++++++++++++++++++++++++++++++++++++
 doc/guide/files/pkgsrc.xml      |   5 +-
 4 files changed, 80 insertions(+), 4 deletions(-)

diffs (139 lines):

diff -r 2d2b4429bfd7 -r b4fabd6a0319 doc/guide/files/Makefile
--- a/doc/guide/files/Makefile  Wed Jun 08 13:20:04 2005 +0000
+++ b/doc/guide/files/Makefile  Wed Jun 08 13:59:30 2005 +0000
@@ -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+= build.xml
 SRCS+= buildlink.xml
 SRCS+= components.xml
+SRCS+= configuring.xml
 SRCS+= debug.xml
 SRCS+= examples.xml
 SRCS+= faq.xml
diff -r 2d2b4429bfd7 -r b4fabd6a0319 doc/guide/files/chapters.ent
--- a/doc/guide/files/chapters.ent      Wed Jun 08 13:20:04 2005 +0000
+++ b/doc/guide/files/chapters.ent      Wed Jun 08 13:59:30 2005 +0000
@@ -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 -r 2d2b4429bfd7 -r b4fabd6a0319 doc/guide/files/configuring.xml
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/guide/files/configuring.xml   Wed Jun 08 13:59:30 2005 +0000
@@ -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 -r 2d2b4429bfd7 -r b4fabd6a0319 doc/guide/files/pkgsrc.xml
--- a/doc/guide/files/pkgsrc.xml        Wed Jun 08 13:20:04 2005 +0000
+++ b/doc/guide/files/pkgsrc.xml        Wed Jun 08 13:59:30 2005 +0000
@@ -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@localhost";>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>