[pkgsrc/trunk]: pkgsrc/doc/guide/files Updated the documentation on the PKG_O...

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

details:   https://anonhg.NetBSD.org/pkgsrc/rev/af10a560b987
branches:  trunk
changeset: 494179:af10a560b987
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Fri May 20 10:02:03 2005 +0000

description:
Updated the documentation on the PKG_OPTIONS framework.

diffstat:

 doc/guide/files/options.xml |  78 ++++++++++++++++++++------------------------
 1 files changed, 36 insertions(+), 42 deletions(-)

diffs (142 lines):

diff -r e486c7bdec25 -r af10a560b987 doc/guide/files/options.xml
--- a/doc/guide/files/options.xml       Fri May 20 09:00:17 2005 +0000
+++ b/doc/guide/files/options.xml       Fri May 20 10:02:03 2005 +0000
@@ -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 @@
 .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 @@
             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 @@
         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 @@
           <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>
+
+        <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>
+
       </orderedlist>
 
-      <para> After the inclusion of bsd.options.mk, the following
-        variables are set: </para>
-
-      <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>
+      <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