[pkgsrc/trunk]: pkgsrc Document how to use bsd.options.mk.

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

details:   https://anonhg.NetBSD.org/pkgsrc/rev/58e7cb8a9d67
branches:  trunk
changeset: 479131:58e7cb8a9d67
user:      jlam <jlam%pkgsrc.org@localhost>
date:      Thu Aug 05 20:55:11 2004 +0000

description:
Document how to use bsd.options.mk.

diffstat:

 Packages.txt |  249 ++++++++++++++++++++++++++++++++++++++++++----------------
 1 files changed, 181 insertions(+), 68 deletions(-)

diffs (truncated from 682 to 300 lines):

diff -r 05a791bb6d9e -r 58e7cb8a9d67 Packages.txt
--- a/Packages.txt      Thu Aug 05 17:50:05 2004 +0000
+++ b/Packages.txt      Thu Aug 05 20:55:11 2004 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: Packages.txt,v 1.347 2004/08/04 16:14:34 jschauma Exp $
+# $NetBSD: Packages.txt,v 1.348 2004/08/05 20:55:11 jlam Exp $
 ###########################################################################
 
                        ==========================
@@ -2105,8 +2105,122 @@
 otherwise it is simply ignored in that list.
 
 
- 9 Debugging
- ===========
+ 9 Options handling
+ ==================
+
+Many packages have the ability to be built to support different sets
+of features.  bsd.options.mk is a pkgsrc framework that provides
+generic handling of those options that determine different ways in
+which the packages can be built.  It's possible for the user to specify
+exactly which sets of options will be built into a package or to allow
+a set of global default options apply .
+
+
+ 9.1 Global default options
+ ==========================
+
+Global default options are listed in PKG_DEFAULT_OPTIONS, which is a
+list of the options that should be built into every package if that
+option is supported.  This variable should be set in /etc/mk.conf.
+
+
+ 9.2 Converting packages to use bsd.options.mk
+ =============================================
+
+The following example shows how bsd.options.mk should be use in a package
+Makefile, or in a file, e.g. options.mk, that is included by the main
+package Makefile.
+
+-------------8<-------------8<-------------8<-------------8<-------------
+# Global and legacy options
+.if defined(USE_OPENLDAP) || defined(USE_SASL2)
+.  if !defined(PKG_OPTIONS.wibble)
+.    if defined(USE_OPENLDAP) && !empty(USE_OPENLDAP:M[yY][eE][sS])
+PKG_OPTIONS.wibble+=   ldap
+.    endif
+.    if defined(USE_SASL2) && !empty(USE_SASL2:M[yY][eE][sS])
+PKG_OPTIONS.wibble+=   sasl
+.    endif
+.  endif
+.endif
+
+PKG_OPTIONS_VAR=       PKG_OPTIONS.wibble
+PKG_OPTIONS.wibble?=   sasl                    # package-specific default
+PKG_SUPPORTED_OPTIONS= ldap sasl
+.include "../../mk/bsd.options.mk"
+
+# Package-specific option-handling
+
+###
+### LDAP support
+###
+.if !empty(PKG_OPTIONS:Mldap)
+.  include "../../databases/openldap/buildlink3.mk"
+CONFIGURE_ARGS+=      --enable-ldap=${BUILDLINK_PREFIX.openldap}
+.endif
+
+###
+### SASL authentication
+###
+.if !empty(PKG_OPTIONS:Msasl)
+.  include "../../security/cyrus-sasl2/buildlink3.mk"
+CONFIGURE_ARGS+=       --enable-sasl=${BUILDLINK_PREFIX.sasl}
+.endif
+# -------------8<-------------8<-------------8<-------------8<-------------
+
+The first section only exists if you are converting a package that
+had its own ad-hoc options handling to use bsd.options.mk.  It converts
+global or legacy options variables into an equivalent PKG_OPTIONS.<pkg>
+value.  These sections will be removed over time as the old options
+are in turn deprecated and removed.
+
+The second section contains the information about which build options
+are supported by the package, and any default options settings if
+needed.
+
+  (1) PKG_OPTIONS_VAR is a list of the name of the make(1) variables
+      that contain the options the user wishes to select.  The
+      recommended value is "PKG_OPTIONS.<pkg>" but any package-specific
+      value may be used.  This variable should be set in a package
+      Makefile.
+
+  (2) PKG_SUPPORTED_OPTIONS is a list of build options supported by
+      the package.  This variable should be set in a package Makefile.
+
+  (3) ${PKG_OPTIONS_VAR} (the variables named in PKG_OPTIONS_VAR) are
+      variables that list the selected build options and override any
+      default options given in PKG_DEFAULT_OPTIONS.  If any of the
+      options begin with a '-', then that option is always removed
+      from the selected build options, e.g.
+
+       PKG_DEFAULT_OPTIONS=    kerberos ldap sasl
+       PKG_OPTIONS_VAR=        WIBBLE_OPTIONS
+       WIBBLE_OPTIONS=         ${PKG_DEFAULT_OPTIONS} -sasl
+       # implies PKG_OPTIONS == "kerberos ldap"
+
+      or
+
+       PKG_OPTIONS_VAR=        WIBBLE_OPTIONS
+       WIBBLE_OPTIONS=         kerberos -ldap ldap
+       # implies PKG_OPTIONS == "kerberos"
+
+      This variable should be set in /etc/mk.conf.
+
+After the inclusion of bsd.options.mk, the following variables are set:
+
+    * PKG_OPTIONS contains the list of the selected build options,
+      properly filtered to remove unsupported and duplicate options.
+
+The remaining sections contain the logic that is specific to each
+option.  There should be a check for every option listed in
+PKG_SUPPORTED_OPTIONS, and there should be clear documentation on what
+turning on the option will do in the comments preceding each section.
+The correct way to check for an option is to check whether it is listed
+in PKG_OPTIONS.
+
+
+ 11 Debugging
+ ============
 
 To check out all the gotchas when building a package, here are the steps
 that I do in order to get a package working. Please note this is basically
@@ -2177,10 +2291,10 @@
  * Submit (or commit, if you have cvs access); see section 11.
 
 
- 10 FAQs & features of the package system
+ 11 FAQs & features of the package system
  ========================================
 
- 10.1 Packages using GNU autoconf
+ 11.1 Packages using GNU autoconf
  ================================
 
 If your package uses GNU autoconf created configure scripts, add the following
@@ -2192,7 +2306,7 @@
 have to do that yourself, and this may not be what you want.
 
 
- 10.2 Other distrib methods than .tar.gz
+ 11.2 Other distrib methods than .tar.gz
  =======================================
 
 If your package uses a different distribution method from .tar.gz, take a
@@ -2204,7 +2318,7 @@
        EXTRACT_CMD=            zcat -d < ${DOWNLOADED_DISTFILE} | ${SH}
 
 
- 10.3 Packages not creating their own subdirectory
+ 11.3 Packages not creating their own subdirectory
  =================================================
 
 Your package doesn't create a subdirectory for itself (like GNU software
@@ -2220,7 +2334,7 @@
 has been deprecated and should not be used.
 
 
- 10.4 Custom configuration process
+ 11.4 Custom configuration process
  =================================
 
 Your package uses a weird Configure script: See the top package, but the
@@ -2231,7 +2345,7 @@
        CONFIGURE_ARGS+=        netbsd13
 
 
- 10.5 Packages not building in their DISTNAME directory
+ 11.5 Packages not building in their DISTNAME directory
  ======================================================
 
 Your package builds in a different directory from its base DISTNAME - see
@@ -2240,7 +2354,7 @@
        WRKSRC=         ${WRKDIR}/${DISTNAME}/unix
 
 
- 10.6 How to fetch all distfiles at once
+ 11.6 How to fetch all distfiles at once
  =======================================
 
 You would like to download all the distfiles in a single batch from work or
@@ -2277,7 +2391,7 @@
        % make fetch NO_SKIP=yes
 
 
- 10.7 How to fetch files from behind a firewall
+ 11.7 How to fetch files from behind a firewall
  ==============================================
 
 If you are sitting behind a firewall which does not allow direct connections
@@ -2291,13 +2405,13 @@
        http_proxy=http://orpheus.amdahl.com:80/
 
 
- 10.8 If your patch contains an RCS ID
+ 11.8 If your patch contains an RCS ID
  =====================================
 
 See section 4.3 on how to remove RCS IDs from patch files.
 
 
- 10.9 How to pull in variables from /etc/mk.conf
+ 11.9 How to pull in variables from /etc/mk.conf
  ===============================================
 
 The problem with package-defined variables that can be overridden via
@@ -2329,7 +2443,7 @@
 current CPU.
 
 
- 10.10 Is there a mailing list for pkg-related discussion?
+ 11.10 Is there a mailing list for pkg-related discussion?
  =========================================================
 
 Yes. We are using tech-pkg%NetBSD.org@localhost for discussing package related
@@ -2338,7 +2452,7 @@
        % echo subscribe tech-pkg | mail majordomo%netbsd.org@localhost
 
 
- 10.11 How do i tell "make fetch" to do passive FTP?
+ 11.11 How do i tell "make fetch" to do passive FTP?
  ===================================================
 
 This depends on which utility is used to retrieve distfiles. From
@@ -2358,7 +2472,7 @@
 active transfers.
 
 
- 10.12 Dependencies on other packages
+ 11.12 Dependencies on other packages
  ====================================
 
 Your package may depend on some other package being present - and there are
@@ -2465,7 +2579,7 @@
 pkgsrc/devel/gettext-m4 package.
 
 
- 10.13 Conflicts with other packages
+ 11.13 Conflicts with other packages
  ===================================
 
 Your package may conflict with other packages a user might already have
@@ -2489,7 +2603,7 @@
 with the older version "Xaw3d-1.3".
 
 
- 10.14 Software which has a WWW Home Page
+ 11.14 Software which has a WWW Home Page
  ========================================
 
 The NetBSD packages system now supports a variable called HOMEPAGE.
@@ -2499,7 +2613,7 @@
 variable.
 
 
- 10.15 How to handle modified distfiles with the 'old' name
+ 11.15 How to handle modified distfiles with the 'old' name
  ==========================================================
 
 Sometimes authors of a software package make some modifications after the
@@ -2514,7 +2628,7 @@
 crept in.
 
 
- 10.16 What does "Don't know how to make /usr/share/tmac/tmac.andoc" mean?
+ 11.16 What does "Don't know how to make /usr/share/tmac/tmac.andoc" mean?
  =========================================================================
 
 When compiling the pkgsrc/pkgtools/pkg_install package, you get the error
@@ -2526,7 +2640,7 @@
 NOMAN=YES either in the environment or in /etc/mk.conf.
 
 
- 10.17 How to handle incrementing versions when fixing an existing package
+ 11.17 How to handle incrementing versions when fixing an existing package
  =========================================================================
 
 When making fixes to an existing package it can be useful to change
@@ -2547,7 +2661,7 @@
 DISTNAME=      foo-17.43
 
 
- 10.18 "Could not find bsd.own.mk" - what's wrong?
+ 11.18 "Could not find bsd.own.mk" - what's wrong?
  =================================================
 
 You didn't install the compiler set, comp.tgz, when you installed your
@@ -2559,7 +2673,7 @@
 the release you have installed (determine via "uname -r").