Document new OPTIONS framework

Reviewed by:	wblock

en_US.ISO8859-1/books/porters-handbook/book.sgml

@@ -3663,19 +3663,17 @@ ALWAYS_KEEP_DISTFILES=	yes
       <sect2 id="use-vars">
 	<title><makevar>USE_<replaceable>*</replaceable></makevar></title>
 
-	<para>A number of variables exist in order to encapsulate
+	<para>Several variables exist to define
-	  common dependencies that many ports have.  Although their
+	  common dependencies shared by many ports.  Their
-	  use is optional, they can help to reduce the verbosity of
+	  use is optional, but helps to reduce the verbosity of
 	  the port <filename>Makefile</filename>s.  Each of them is
 	  styled as
-	  <makevar>USE_<replaceable>*</replaceable></makevar>.  The
+	  <makevar>USE_<replaceable>*</replaceable></makevar>.
-	  usage of these variables is restricted to the port
+	  These variables may be used only in the port
 	  <filename>Makefile</filename>s and
-	  <filename>ports/Mk/bsd.*.mk</filename> and is not designed
+	  <filename>ports/Mk/bsd.*.mk</filename>.  They are not meant
-	  to encapsulate user-settable options &mdash; use
+	  for user-settable options &mdash; use
-	  <makevar>WITH_<replaceable>*</replaceable></makevar> and
+	  <makevar>PORT_OPTIONS</makevar> for that purpose.</para>
-	  <makevar>WITHOUT_<replaceable>*</replaceable></makevar> for
-	  that purpose.</para>
 
 	<note>
 	  <para>It is <emphasis>always</emphasis> incorrect to set any
@@ -3880,11 +3878,12 @@ LIB_DEPENDS=	bar:${PORTSDIR}/foo/bar
 	<example>
 	  <title>Correct Declaration of an Optional Dependency</title>
 
-	  <programlisting>OPTIONS=	BAR	"Enable bar support" off
+	  <programlisting>OPTIONS_DEFINE=	BAR
+BAR_DESC=	Enable bar support
 
-.include &lt;bsd.port.pre.mk&gt;
+.include &lt;bsd.port.options.mk&gt;
 
-.if defined(WITH_BAR) && !defined(WITHOUT_BAR)
+.if ${PORTOPTIONS:MBAR}
 LIB_DEPENDS=	bar:${PORTSDIR}/foo/bar
 .endif</programlisting>
 	</example>
@@ -4089,15 +4088,14 @@ ${MANPREFIX}/man/de/man3/baz.3.gz</programlisting>
     <sect1 id="makefile-options">
       <title>Makefile Options</title>
 
-      <para>Some large applications can be built in a number of
+      <para>Many applications can be built with optional or differing
-	configurations, adding functionality if one of a number of
+	configurations.  Examples include
-	libraries or applications is available.  Examples include
 	choice of natural (human) language, GUI versus command-line,
-	or type of database to support.  Since not all users want
+	or type of database to support.  Users may need a different
-	those libraries or applications, the ports system provides
+	configuration than the default, so the ports system provides
-	hooks that the port author can use to control which
+	hooks the port author can use to control which variation
-	configuration should be built.  Supporting these properly will
+	will be built.  Supporting these options properly will
-	make users happy, and effectively provide 2 or more ports for
+	make users happy, and effectively provide two or more ports for
 	the price of one.</para>
 
       <sect2>
@@ -4109,7 +4107,7 @@ ${MANPREFIX}/man/de/man3/baz.3.gz</programlisting>
 	    <makevar>WITHOUT_<replaceable>*</replaceable></makevar></title>
 
 	  <para>These variables are designed to be set by the system
-	    administrator.  There are many that are standardized in
+	    administrator.  There are many that are standardized in the
 	    <ulink
 	      url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/KNOBS?rev=HEAD&amp;content-type=text/x-cvsweb-markup"><filename>ports/KNOBS</filename></ulink>
 	    file.</para>
@@ -4131,7 +4129,7 @@ ${MANPREFIX}/man/de/man3/baz.3.gz</programlisting>
 	  <note>
 	    <para>Unless otherwise specified, these variables are only
 	      tested for being set or not set, rather than being set
-	      to some kind of variable such as <literal>YES</literal>
+	      to a specific value such as <literal>YES</literal>
 	      or <literal>NO</literal>.</para>
 	  </note>
 
@@ -4173,11 +4171,11 @@ ${MANPREFIX}/man/de/man3/baz.3.gz</programlisting>
 
 		<row>
 		  <entry><makevar>WITHOUT_X11</makevar></entry>
-		  <entry>If the port can be built both with and
+		  <entry>Ports that can be built both with and
-		    without X support, then it should normally be
+		    without X support are normally
 		    built with X support.  If this variable is
 		    defined, then the version that does not have X
-		    support should be built instead.</entry>
+		    support will be built instead.</entry>
 		</row>
 	      </tbody>
 	    </tgroup>
@@ -4187,7 +4185,7 @@ ${MANPREFIX}/man/de/man3/baz.3.gz</programlisting>
 	<sect3>
 	  <title>Knob Naming</title>
 
-	  <para>It is recommended that porters use like-named knobs,
+	  <para>Porters should use like-named knobs, both
 	    for the benefit of end-users and to help keep the number
 	    of knob names down.  A list of popular knob names can be
 	    found in the <ulink
@@ -4207,34 +4205,30 @@ ${MANPREFIX}/man/de/man3/baz.3.gz</programlisting>
 	<sect3>
 	  <title>Background</title>
 
-	  <para>The <makevar>OPTIONS</makevar> variable gives the user
+	  <para>The <makevar>OPTIONS_*</makevar> variables give the user
-	    who installs the port a dialog with the available options
+	    installing the port a dialog showing the available options,
-	    and saves them to
+	    and then saves those options to
-	    <filename>/var/db/ports/<replaceable>portname</replaceable>/options</filename>.
+	    <filename>/var/db/ports/<makevar>${UNIQUENAME}</makevar>/options</filename>.
-	    Next time when the port has to be rebuild, the options are
+	    The next time the port is built, the options are
-	    reused.  Never again you will have to remember all the
+	    reused.</para>
-	    twenty
-	    <makevar>WITH_<replaceable>*</replaceable></makevar> and
-	    <makevar>WITHOUT_<replaceable>*</replaceable></makevar>
-	    options you used to build this port!</para>
 
 	  <para>When the user runs <command>make config</command> (or
 	    runs <command>make build</command> for the first time),
-	    the framework will check for
+	    the framework checks for
-	    <filename>/var/db/ports/<replaceable>portname</replaceable>/options</filename>.
+	    <filename>/var/db/ports/<makevar>${UNIQUENAME}</makevar>/options</filename>.
-	    If that file does not exist, it will use the values of
+	    If that file does not exist, the values of
-	    <makevar>OPTIONS</makevar> to create a dialog box where
+	    <makevar>OPTIONS_*</makevar> are used, and a dialog box is displayed where
 	    the options can be enabled or disabled.  Then the
 	    <filename>options</filename> file is saved and the
-	    selected variables will be used when building the
+	    configured variables are used when building the
 	    port.</para>
 
 	  <para>If a new version of the port adds new
 	    <makevar>OPTIONS</makevar>, the dialog will be presented
-	    to the user, with the saved values of old
+	    to the user with the saved values of old
 	    <makevar>OPTIONS</makevar> prefilled.</para>
 
-	  <para>Use <command>make showconfig</command> to see the
+	  <para><command>make showconfig</command> shows the
 	    saved configuration.  Use <command>make rmconfig</command>
 	    to remove the saved configuration.</para>
 	</sect3>
@@ -4242,47 +4236,138 @@ ${MANPREFIX}/man/de/man3/baz.3.gz</programlisting>
 	<sect3>
 	  <title>Syntax</title>
 
-	  <para>The syntax for the <makevar>OPTIONS</makevar> variable
+	  <para><makevar>OPTIONS_DEFINE</makevar> contains a list of
-	    is:</para>
+	    <makevar>OPTIONS</makevar> to be used.  These are independent
+	    of each other and are not grouped:</para>
 
-	  <programlisting>OPTIONS=	OPTION	"descriptive text" default ...</programlisting>
+	  <programlisting>OPTIONS_DEFINE=	OPT1 OPT2</programlisting>
 
-	  <para>The value for default is either <literal>ON</literal>
+	  <para>Once defined, <makevar>OPTIONS</makevar> are
-	    or <literal>OFF</literal>.  Multiple repetitions of these
+	    described (optional, but strongly recommended):</para>
-	    three fields are allowed.</para>
 
-	  <para><makevar>OPTIONS</makevar> definition must appear
+	  <programlisting>OPT1_DESC=	Describe OPT1
+OPT2_DESC=	Describe OPT2
+OPT3_DESC=	Describe OPT3
+OPT4_DESC=	Describe OPT4
+OPT5_DESC=	Describe OPT5
+OPT6_DESC=	Describe OPT6</programlisting>
+
+	  <tip>
+	    <para><filename>ports/Mk/bsd.options.desc.mk</filename>
+	      has descriptions for many common
+	      <makevar>OPTIONS</makevar>; there is usually no need
+	      to override these.</para>
+	  </tip>
+
+	  <tip>
+	    <para>When describing options, view it from the
+	      perspective of the user: <quote>What does it do?</quote>
+	      and <quote>Why would I want to enable this?</quote> Do
+	      not just repeat the name.  For example, describing the
+	      <literal>NLS</literal> option as
+	      <quote>include NLS support</quote> does not help the
+	      user who can already see the option name but may not
+
+	      know what it means.  Describing it as <quote>Native
+		Language Support via gettext utilities</quote> is
+	      much more helpful.</para>
+	  </tip>
+
+	  <para><makevar>OPTIONS</makevar> can be grouped as radio
+	    choices, where only one choice from each group is
+	    allowed:</para>
+
+	  <programlisting>OPTIONS_SINGLE=		SG1
+OPTIONS_SINGLE_SG1=	OPT3 OPT4</programlisting>
+
+	  <para><makevar>OPTIONS</makevar> can also be grouped as
+	    <quote>multiple-choice</quote> lists, where
+	    <emphasis>at least one</emphasis> option must be
+	    enabled:</para>
+
+	  <programlisting>OPTIONS_MULTI=		MG1
+OPTIONS_MULTI_MG1=	OPT5 OPT6</programlisting>
+
+	  <para><makevar>OPTIONS</makevar> are unset by default,
+	    unless they are listed in
+	    <makevar>OPTIONS_DEFAULT</makevar>:</para>
+
+	  <programlisting>OPTIONS_DEFAULT=	OPT1 OPT3 OPT6</programlisting>
+
+	  <para><makevar>OPTIONS</makevar> definitions must appear
 	    before the inclusion of
 	    <filename>bsd.port.options.mk</filename>.  The
-	    <makevar>WITH_*</makevar> and <makevar>WITHOUT_*</makevar>
+	    <makevar>PORT_OPTIONS</makevar> variable can only be
-	    variables can only be tested after the inclusion of
+	    tested after the inclusion of
 	    <filename>bsd.port.options.mk</filename>.  Inclusion of
 	    <filename>bsd.port.pre.mk</filename> can be used instead,
 	    too, and is still widely used in ports written before the
 	    introduction of <filename>bsd.port.options.mk</filename>.
 	    But be aware that some variables will not work as expected
 	    after the inclusion of
-	    <filename>bsd.port.pre.mk</filename>, typically
+	    <filename>bsd.port.pre.mk</filename>, typically some
 	    <makevar>USE_*</makevar> flags.</para>
 
 	  <example id="ports-options-simple-use">
 	    <title>Simple Use of <makevar>OPTIONS</makevar></title>
 
-	    <programlisting>OPTIONS=	FOO "Enable option foo" On \
+	    <programlisting>OPTIONS_DEFINE=	FOO BAR
-		BAR "Support feature bar" Off
+FOO_DESC=	Enable option foo
+BAR_DESC=	Support feature bar
+
+OPTIONS_DEFAULT=FOO
 
 .include &lt;bsd.port.options.mk&gt;
 
-.if defined(WITHOUT_FOO)
+.if ${PORT_OPTIONS:MFOO}
-CONFIGURE_ARGS+=	--without-foo
+CONFIGURE_ARGS+=--without-foo
 .else
-CONFIGURE_ARGS+=	--with-foo
+CONFIGURE_ARGS+=--with-foo
 .endif
 
-.if defined(WITH_BAR)
+.if ${PORT_OPTIONS:MBAR}
 RUN_DEPENDS+=	bar:${PORTSDIR}/bar/bar
 .endif
 
+.include &lt;bsd.port.mk&gt;</programlisting>
+	  </example>
+
+	  <example id="ports-options-practical-use">
+	    <title>Practical Use of <makevar>OPTIONS</makevar></title>
+
+	    <programlisting>OPTIONS_DEFINE=		EXAMPLES
+
+OPTIONS_SINGLE=		BACKEND
+OPTIONS_SINGLE_BACKEND=	MYSQL PGSQL BDB
+
+OPTIONS_MULTI=		AUTH
+OPTIONS_MULTI_AUTH=	LDAP PAM SSL
+
+EXAMPLES_DESC=		Install extra examples
+MYSQL_DESC=		Use MySQL as backend
+PGSQL_DESC=		Use PostgreSQL as backend
+BDB_DESC=		Use Berkeley DB as backend
+LDAP_DESC=		Build with LDAP authentication support
+PAM_DESC=		Build with PAM support
+SSL_DESC=		Build with OpenSSL support
+
+OPTIONS_DEFAULT=	PGSQL LDAP SSL
+
+.include &lt;bsd.port.options.mk&gt;
+
+.if ${PORT_OPTIONS:MPGSQL}
+USE_PGSQL=		yes
+CONFIGURE_ARGS+=	--with-postgres
+.else
+CONFIGURE_ARGS+=	--without-postgres
+.endif
+
+.if ${PORT_OPTIONS:MICU}
+LIB_DEPENDS+=	icuuc:${PORTSDIR}/devel/icu
+.endif
+
+# Check other OPTIONS
+
 .include &lt;bsd.port.mk&gt;</programlisting>
 	  </example>
 
@@ -4301,6 +4386,12 @@ CONFIGURE_ARGS+=	--with-foo
 
 .include &lt;bsd.port.post.mk&gt;</programlisting>
 	  </example>
+
+	  <important>
+	    <para>This method of using <makevar>OPTIONS</makevar>
+	      is deprecated, and will be removed at some point.
+	      Do not use this method for new ports.</para>
+	  </important>
 	</sect3>
       </sect2>
 
@@ -4317,7 +4408,7 @@ CONFIGURE_ARGS+=	--with-foo
 	<example>
 	  <title>Wrong Handling of an Option</title>
 
-	  <programlisting>.if defined(WITH_FOO)
+	  <programlisting>.if ${PORT_OPTIONS:MFOO}
 LIB_DEPENDS+=		foo.0:${PORTSDIR}/devel/foo
 CONFIGURE_ARGS+=	--enable-foo
 .endif</programlisting>
@@ -4336,7 +4427,7 @@ CONFIGURE_ARGS+=	--enable-foo
 	<example>
 	  <title>Correct Handling of an Option</title>
 
-	  <programlisting>.if defined(WITH_FOO)
+	  <programlisting>.if ${PORT_OPTIONS:MFOO}
 LIB_DEPENDS+=		foo.0:${PORTSDIR}/devel/foo
 CONFIGURE_ARGS+=	--enable-foo
 .else
@@ -7987,7 +8078,7 @@ WX_COMPS=	wx contrib</programlisting>
 
 .include &lt;bsd.port.pre.mk&gt;
 
-.if defined(WITH_WX) || ${HAVE_WX:Mwx-2.4} != ""
+.if defined(WITH_WX) || !empty(PORT_OPTIONS:MWX) || !empty(HAVE_WX:Mwx-2.4)
 USE_WX=			2.4
 CONFIGURE_ARGS+=	--enable-wx
 .endif</programlisting>
@@ -8004,7 +8095,7 @@ WANT_WX=	2.6
 
 .include &lt;bsd.port.pre.mk&gt;
 
-.if defined(WITH_WXPYTHON) || ${HAVE_WX:Mpython} != ""
+.if defined(WITH_WXPYTHON) || !empty(PORT_OPTIONS:MWXPYTHON) || !empty(HAVE_WX:Mpython)
 WX_COMPS+=		python
 CONFIGURE_ARGS+=	--enable-wxpython
 .endif</programlisting>
@@ -8495,7 +8586,7 @@ LUA_COMPS=	lua ruby</programlisting>
 
 .include &lt;bsd.port.pre.mk&gt;
 
-.if defined(WITH_LUA5) || ${HAVE_LUA:Mlua-5.[01]} != ""
+.if defined(WITH_LUA5) || !empty(PORT_OPTIONS:MLUA5) || !empty(HAVE_LUA:Mlua-5.[01])
 USE_LUA=		5.0-5.1
 CONFIGURE_ARGS+=	--enable-lua5
 .endif</programlisting>
@@ -8512,7 +8603,7 @@ WANT_LUA=	4.0
 
 .include &lt;bsd.port.pre.mk&gt;
 
-.if defined(WITH_TOLUA) || ${HAVE_LUA:Mtolua} != ""
+.if defined(WITH_TOLUA) || !empty(PORT_OPTIONS:MTOLUA) || !empty(HAVE_LUA:Mtolua)
 LUA_COMPS+=		tolua
 CONFIGURE_ARGS+=	--enable-tolua
 .endif</programlisting>