New docs for OPTIONS
Warren Block
wblock at wonkity.com
Sun May 27 16:02:03 UTC 2012
On Sat, 26 May 2012, Chris Rees wrote:
> We have a new world order for OPTIONS in ports (exciting, isn't it??),
> and would very much like to document it.
>
> I've prepared the following patch which has had fairly extensive
> review, apart from not having a formal approval by a docs person.
>
> Would anyone mind giving it a check and approving it please? Bapt
> plans to commit the code later this week, and it'd be great to have
> approval by then!
>
> Thanks,
>
> Chris
>
>
> http://www.bayofrum.net/~crees/patches/optionsng-docs-patch.diff
>
> http://www.bayofrum.net/~crees/rendered/porters-optionsng.html
Attached is a full patch that builds on that. Some simplifications and
clarifications, and an added tip on helpful descriptions.
-------------- next part --------------
Index: doc/en_US.ISO8859-1/books/porters-handbook/book.sgml
===================================================================
--- doc/en_US.ISO8859-1/books/porters-handbook/book.sgml (revision 38891)
+++ doc/en_US.ISO8859-1/books/porters-handbook/book.sgml (working copy)
@@ -3663,19 +3663,17 @@
<sect2 id="use-vars">
<title><makevar>USE_<replaceable>*</replaceable></makevar></title>
- <para>A number of variables exist in order to encapsulate
- common dependencies that many ports have. Although their
- use is optional, they can help to reduce the verbosity of
+ <para>Several variables exist to define
+ common dependencies shared by many ports. Their
+ 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
- usage of these variables is restricted to the port
+ <makevar>USE_<replaceable>*</replaceable></makevar>.
+ These variables may be used only in the port
<filename>Makefile</filename>s and
- <filename>ports/Mk/bsd.*.mk</filename> and is not designed
- to encapsulate user-settable options — use
- <makevar>WITH_<replaceable>*</replaceable></makevar> and
- <makevar>WITHOUT_<replaceable>*</replaceable></makevar> for
- that purpose.</para>
+ <filename>ports/Mk/bsd.*.mk</filename>. They are not meant
+ for user-settable options — use
+ <makevar>PORT_OPTIONS</makevar> for that purpose.</para>
<note>
<para>It is <emphasis>always</emphasis> incorrect to set any
@@ -3880,11 +3878,12 @@
<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 <bsd.port.pre.mk>
+.include <bsd.port.options.mk>
-.if defined(WITH_BAR) && !defined(WITHOUT_BAR)
+.if ${PORTOPTIONS:MBAR}
LIB_DEPENDS= bar:${PORTSDIR}/foo/bar
.endif</programlisting>
</example>
@@ -4089,15 +4088,14 @@
<sect1 id="makefile-options">
<title>Makefile Options</title>
- <para>Some large applications can be built in a number of
- configurations, adding functionality if one of a number of
- libraries or applications is available. Examples include
+ <para>Many applications can be built with optional or differing
+ configurations. Examples include
choice of natural (human) language, GUI versus command-line,
- or type of database to support. Since not all users want
- those libraries or applications, the ports system provides
- hooks that the port author can use to control which
- configuration should be built. Supporting these properly will
- make users happy, and effectively provide 2 or more ports for
+ or type of database to support. Users may need a different
+ configuration than the default, so the ports system provides
+ hooks the port author can use to control which variation
+ will be built. Supporting these options properly will
+ make users happy, and effectively provide two or more ports for
the price of one.</para>
<sect2>
@@ -4109,7 +4107,7 @@
<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&content-type=text/x-cvsweb-markup"><filename>ports/KNOBS</filename></ulink>
file.</para>
@@ -4131,7 +4129,7 @@
<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 @@
<row>
<entry><makevar>WITHOUT_X11</makevar></entry>
- <entry>If the port can be built both with and
- without X support, then it should normally be
+ <entry>Ports that can be built both with and
+ 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 @@
<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 @@
<sect3>
<title>Background</title>
- <para>The <makevar>OPTIONS</makevar> variable gives the user
- who installs the port a dialog with the available options
- and saves them to
- <filename>/var/db/ports/<replaceable>portname</replaceable>/options</filename>.
- Next time when the port has to be rebuild, the options are
- reused. Never again you will have to remember all the
- twenty
- <makevar>WITH_<replaceable>*</replaceable></makevar> and
- <makevar>WITHOUT_<replaceable>*</replaceable></makevar>
- options you used to build this port!</para>
+ <para>The <makevar>OPTIONS_*</makevar> variables give the user
+ installing the port a dialog showing the available options,
+ and then saves those options to
+ <filename>/var/db/ports/<makevar>${UNIQUENAME}</makevar>/options</filename>.
+ The next time the port is built, the options are
+ reused.</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
- <filename>/var/db/ports/<replaceable>portname</replaceable>/options</filename>.
- If that file does not exist, it will use the values of
- <makevar>OPTIONS</makevar> to create a dialog box where
+ the framework checks for
+ <filename>/var/db/ports/<makevar>${UNIQUENAME}</makevar>/options</filename>.
+ If that file does not exist, the values of
+ <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,50 +4236,141 @@
<sect3>
<title>Syntax</title>
- <para>The syntax for the <makevar>OPTIONS</makevar> variable
- is:</para>
+ <para><makevar>OPTIONS_DEFINE</makevar> contains a list of
+ <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>
- or <literal>OFF</literal>. Multiple repetitions of these
- three fields are allowed.</para>
+ <para>Once defined, <makevar>OPTIONS</makevar> are
+ described (optional, but strongly recommended):</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>
- variables can only be tested after the inclusion of
+ <makevar>PORT_OPTIONS</makevar> variable can only be
+ 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 \
- BAR "Support feature bar" Off
+ <programlisting>OPTIONS_DEFINE= FOO BAR
+FOO_DESC= Enable option foo
+BAR_DESC= Support feature bar
+OPTIONS_DEFAULT=FOO
+
.include <bsd.port.options.mk>
-.if defined(WITHOUT_FOO)
-CONFIGURE_ARGS+= --without-foo
+.if ${PORT_OPTIONS:MFOO}
+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 <bsd.port.mk></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 <bsd.port.options.mk>
+
+.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 <bsd.port.mk></programlisting>
+ </example>
+
<example id="ports-options-old-style-use">
<title>Old-Style Use of <makevar>OPTIONS</makevar></title>
@@ -4301,6 +4386,12 @@
.include <bsd.port.post.mk></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 @@
<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 @@
<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 @@
.include <bsd.port.pre.mk>
-.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 @@
.include <bsd.port.pre.mk>
-.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 @@
.include <bsd.port.pre.mk>
-.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 @@
.include <bsd.port.pre.mk>
-.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>
More information about the freebsd-doc
mailing list