Updated the documentation on the PKG_OPTIONS framework.

1 files changed, 36 insertions, 42 deletions

diff --git a/doc/guide/files/options.xml b/doc/guide/files/options.xml
index 72b12484aac..1d860feea74 100644
--- a/doc/guide/files/options.xml
+++ b/doc/guide/files/options.xml
@@ -1,4 +1,8 @@
-<!-- $NetBSD: options.xml,v 1.3 2005/05/14 22:34:59 rillig Exp $ -->
+<!-- $NetBSD: options.xml,v 1.4 2005/05/20 10:02:03 rillig Exp $ -->
+
+<!-- based on:
+pkgsrc/mk/bsd.options.mk 1.23
+-->
 
 <chapter id="options">
   <title>Options handling</title>
@@ -25,7 +29,8 @@
       <title>Converting packages to use <filename>bsd.options.mk</filename></title>
 
       <para> The following example shows how
-        <filename>bsd.options.mk</filename> should be used in a package
+        <filename>bsd.options.mk</filename> should be used
+	by the hypothetical ``wibble'' package, either in the package
         <filename>Makefile</filename>, or in a file,
         e.g. <filename>options.mk</filename>, that is included by the
         main package <filename>Makefile</filename>.
@@ -33,21 +38,11 @@
 
       <programlisting>
 # Global and legacy options
-.if defined(WIBBLE_USE_OPENLDAP) && !empty(WIBBLE_USE_OPENLDAP:M[yY][eE][sS])
-PKG_DEFAULT_OPTIONS+=   ldap
-.endif
-.if defined(USE_SASL2) && !empty(USE_SASL2:M[yY][eE][sS])
-PKG_DEFAULT_OPTIONS+=   sasl
-.endif
-
 PKG_OPTIONS_VAR=        PKG_OPTIONS.wibble
 PKG_SUPPORTED_OPTIONS=  ldap sasl
-#
-# Default options for "wibble" package.
-#
-.if !defined(PKG_OPTIONS.wibble)
-PKG_DEFAULT_OPTIONS+=   sasl
-endif
+PKG_SUGGESTED_OPTIONS=  sasl
+PKG_OPTION_LEGACY_VARS= WIBBLE_USE_OPENLDAP:ldap USE_SASL2:sasl
+
 .include "../../mk/bsd.options.mk"
 
 # Package-specific option-handling
@@ -69,22 +64,14 @@ CONFIGURE_ARGS+=        --enable-sasl=${BUILDLINK_PREFIX.sasl}
 .endif
       </programlisting>
 
-      <para> The first section only exists if you are converting a
-        package that had its own ad-hoc options handling to use
-        <filename>bsd.options.mk</filename>.  It converts global or
-        legacy options variables into an equivalent
-        <varname>PKG_OPTIONS.<replaceable>pkg</replaceable></varname> 
-        value.  These sections will be removed over time as the old
-        options are in turn deprecated and removed. </para>
-
-      <para> The second section contains the information about which
+      <para> The first section contains the information about which
         build options are supported by the package, and any default
         options settings if needed. </para>
 
       <orderedlist>
         <listitem>
-	  <para> <varname>PKG_OPTIONS_VAR</varname> is a list of the
-            name of the &man.make.1; variables that contain the options the
+	  <para> <varname>PKG_OPTIONS_VAR</varname> is the
+            name of the &man.make.1; variable that contains the options the
             user wishes to select.  The recommended value is
             <quote>PKG_OPTIONS.<replaceable>pkg</replaceable></quote>
             but any package-specific value may be 
@@ -98,10 +85,15 @@ CONFIGURE_ARGS+=        --enable-sasl=${BUILDLINK_PREFIX.sasl}
             should be set in a package Makefile. </para>
         </listitem>
 
+	<listitem>
+	  <para><varname>PKG_SUGGESTED_OPTIONS</varname> is a list of
+	  build options which are enabled by default.</para>
+	</listitem>
+
         <listitem>
-	  <para> <varname>${PKG_OPTIONS_VAR}</varname> (the variables
-            named in <varname>PKG_OPTIONS_VAR</varname>) are variables
-            that list the selected build options and override any
+	  <para> <varname>${PKG_OPTIONS_VAR}</varname> (the variable
+            named in <varname>PKG_OPTIONS_VAR</varname>)
+            lists the selected build options and overrides any
             default options given in
             <varname>PKG_DEFAULT_OPTIONS</varname>.  If any of the
             options begin with a <quote>-</quote>, then that option is
@@ -112,7 +104,7 @@ CONFIGURE_ARGS+=        --enable-sasl=${BUILDLINK_PREFIX.sasl}
         PKG_DEFAULT_OPTIONS=    kerberos ldap sasl
         PKG_OPTIONS_VAR=        WIBBLE_OPTIONS
         WIBBLE_OPTIONS=         ${PKG_DEFAULT_OPTIONS} -sasl
-        # implies PKG_OPTIONS == "kerberos ldap"
+        # leads to PKG_OPTIONS = kerberos ldap
           </programlisting>
 
           <para>or</para>
@@ -120,25 +112,27 @@ CONFIGURE_ARGS+=        --enable-sasl=${BUILDLINK_PREFIX.sasl}
           <programlisting>
         PKG_OPTIONS_VAR=        WIBBLE_OPTIONS
         WIBBLE_OPTIONS=         kerberos -ldap ldap
-        # implies PKG_OPTIONS == "kerberos"
+        # leads to PKG_OPTIONS = kerberos
           </programlisting>
 
 	  <para> This variable should be set in
             <filename>/etc/mk.conf</filename>. </para>
         </listitem>
-      </orderedlist>
 
-      <para> After the inclusion of bsd.options.mk, the following
-        variables are set: </para>
+        <listitem><para>The <varname>PKG_OPTIONS_LEGACY_VARS</varname>
+	is only needed if you are converting a package that had its own
+	ad-hoc options handling to use
+        <filename>bsd.options.mk</filename>.  It converts global or
+        legacy options variables into an equivalent
+        <varname>PKG_OPTIONS.<replaceable>pkg</replaceable></varname> 
+        value.</para></listitem>
 
-      <itemizedlist>
-        <listitem>
-	  <para> <varname>PKG_OPTIONS</varname> contains the list of
-            the selected build options, properly filtered to remove
-            unsupported and duplicate options.
-	  </para>
-	</listitem>
-      </itemizedlist>
+      </orderedlist>
+
+      <para> After the inclusion of bsd.options.mk, the variable
+        <varname>PKG_OPTIONS</varname> contains the list of the selected
+	build options, properly filtered to remove unsupported and
+	duplicate options.</para>
 
       <para> The remaining sections contain the logic that is specific
         to each option.  There should be a check for every option