diff options
author | rillig <rillig@pkgsrc.org> | 2005-05-20 10:02:03 +0000 |
---|---|---|
committer | rillig <rillig@pkgsrc.org> | 2005-05-20 10:02:03 +0000 |
commit | 1e94e065698ab16c27011c86782d6a41dc49248a (patch) | |
tree | 33c2ca1c62478136a7bea635444aa2b6a67335c4 | |
parent | 99deb5f710acc105fc3720242720c43dd2bd5278 (diff) | |
download | pkgsrc-1e94e065698ab16c27011c86782d6a41dc49248a.tar.gz |
Updated the documentation on the PKG_OPTIONS framework.
-rw-r--r-- | doc/guide/files/options.xml | 78 |
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 |