Date: Tue, 29 May 2012 18:07:56 +0000 (UTC) From: Chris Rees <crees@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r38931 - head/en_US.ISO8859-1/books/porters-handbook Message-ID: <201205291807.q4TI7uba094270@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: crees (ports committer) Date: Tue May 29 18:07:56 2012 New Revision: 38931 URL: http://svn.freebsd.org/changeset/doc/38931 Log: Document new OPTIONS framework Reviewed by: wblock Modified: head/en_US.ISO8859-1/books/porters-handbook/book.sgml Modified: head/en_US.ISO8859-1/books/porters-handbook/book.sgml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/book.sgml Tue May 29 15:07:17 2012 (r38930) +++ head/en_US.ISO8859-1/books/porters-handbook/book.sgml Tue May 29 18:07:56 2012 (r38931) @@ -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 - 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 @@ 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 <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 @@ ${MANPREFIX}/man/de/man3/baz.3.gz</progr <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 @@ ${MANPREFIX}/man/de/man3/baz.3.gz</progr <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 @@ ${MANPREFIX}/man/de/man3/baz.3.gz</progr <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</progr <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 @@ ${MANPREFIX}/man/de/man3/baz.3.gz</progr <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</progr <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 @@ ${MANPREFIX}/man/de/man3/baz.3.gz</progr <sect3> <title>Syntax</title> - <para>The syntax for the <makevar>OPTIONS</makevar> variable - is:</para> - - <programlisting>OPTIONS= OPTION "descriptive text" default ...</programlisting> + <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_DEFINE= OPT1 OPT2</programlisting> + + <para>Once defined, <makevar>OPTIONS</makevar> are + described (optional, but strongly recommended):</para> + + <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> - <para>The value for default is either <literal>ON</literal> - or <literal>OFF</literal>. Multiple repetitions of these - three fields are allowed.</para> + <programlisting>OPTIONS_DEFAULT= OPT1 OPT3 OPT6</programlisting> - <para><makevar>OPTIONS</makevar> definition must appear + <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 @@ CONFIGURE_ARGS+= --with-foo .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 @@ 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 <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 @@ WANT_WX= 2.6 .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 @@ LUA_COMPS= lua ruby</programlisting> .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 @@ WANT_LUA= 4.0 .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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201205291807.q4TI7uba094270>