freebsd-doc Digest, Vol 479, Issue 1
michael.gullberg@gmail.com
michael.gullberg at gmail.com
Wed May 30 14:24:35 UTC 2012
Sent from my HTC
----- Reply message -----
From: freebsd-doc-request at freebsd.org
To: <freebsd-doc at freebsd.org>
Subject: freebsd-doc Digest, Vol 479, Issue 1
Date: Mon, May 28, 2012 14:06
Send freebsd-doc mailing list submissions to
freebsd-doc at freebsd.org
To subscribe or unsubscribe via the World Wide Web, visit
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
or, via email, send a message with subject or body 'help' to
freebsd-doc-request at freebsd.org
You can reach the person managing the list at
freebsd-doc-owner at freebsd.org
When replying, please edit your Subject line so it is more specific
than "Re: Contents of freebsd-doc digest..."
Today's Topics:
1. Re: New docs for OPTIONS (Warren Block)
2. Re: docs/167020: Bad command-line example in handbook
(crees at FreeBSD.org)
3. Dear Customer:Andriod 2.3 Tablet PC 20% off (PriceAngels)
----------------------------------------------------------------------
Message: 1
Date: Sun, 27 May 2012 10:02:01 -0600 (MDT)
From: Warren Block <wblock at wonkity.com>
Subject: Re: New docs for OPTIONS
To: Chris Rees <utisoft at gmail.com>
Cc: doc at freebsd.org, portmgr at freebsd.org
Message-ID: <alpine.BSF.2.00.1205270946120.48564 at wonkity.com>
Content-Type: text/plain; charset="us-ascii"
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>
------------------------------
Message: 2
Date: Sun, 27 May 2012 18:15:18 GMT
From: crees at FreeBSD.org
Subject: Re: docs/167020: Bad command-line example in handbook
To: b.heidotting at yahoo.com, crees at FreeBSD.org, freebsd-doc at FreeBSD.org
Message-ID: <201205271815.q4RIFITd021085 at freefall.freebsd.org>
Synopsis: Bad command-line example in handbook
State-Changed-From-To: closed->open
State-Changed-By: crees
State-Changed-When: Sun May 27 18:15:17 UTC 2012
State-Changed-Why:
This can be more portable (work with csh and sh) using env;
http://www.bayofrum.net/~crees/patches/handbook-dump-over-ssh.diff
http://www.freebsd.org/cgi/query-pr.cgi?pr=167020
------------------------------
Message: 3
Date: Mon, 28 May 2012 05:00:26 +0200
From: "PriceAngels" <no-reply at priceangels.com>
Subject: Dear Customer:Andriod 2.3 Tablet PC 20% off
To: <doc at FreeBSD.org>
Message-ID: <0.1.11B.9BC.1CD3C7E08707C9A.0 at pmta41036.emsmtp.com>
Content-Type: text/plain; charset=iso-8859-1
To view the graphic version (HTML) of this e-mail, click on the
following link or copy it into your browser:
http://emaillink2.priceangels.com/u/gm.php?prm=aUv3Bnf3uC_143435532_217845_8293
About PriceAngels.com
Welcome!
Thank you for visiting PriceAngels.com, where you will find a wide
array of high-quality products at unbelievable wholesale prices, and
more important, we guarantee Free-Shipping all over the world!
Customer-Centric Company
PriceAngels.com is the next generation of online-shopping. Offering
our customers more type of products, more conveniently, and at even
lower wholesale prices has always been the focus of PriceAngels.com. We
provide a best-of-breed online-shopping platform to our customers all
over the world, no matter you�re a wholesaler who is looking for new
merchandise and high profits , a retailer who wants to empower your
commerce offerings, or an individual shopper who is looking for the
latest products with good quality and lower price, you will be satisfied
with us.
We�ve Only Just Begun
From the moment we founded PriceAngels, our vision has been to
empower the people worldwide in buying and selling online. We have
served customers from over 30 countries, and we�re still growing. In the
years to come, you�ll see priceangels.com create new technologies,
expand into more geographies and continue to improve the lives of
wholesalers, retailers and individual shoppers around the world
Our Promises
We promise to:
Free-shipping all over the world.
Source only the best consumer goods and ensure the highest
quality.
Streamline the buying and payment process, and make it as easy
as possible.
Help the customers all over the world discover products and
manufacturers in China.
Deliver the goods to the customers all over the world with
speed and precision
Provide 24-hour customer support on weekdays.
Learn More
To learn more about PriceAngels.com today, explore our website the
products, special offers, and you can also read some customer reviews.
If you want to unsubscribe from our mailing list, use the following
link:
http://emaillink2.priceangels.com/u/un.php?par=aUv3Bnf3uC_217845_8293_$sid$
------------------------------
_______________________________________________
freebsd-doc at freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscribe at freebsd.org"
End of freebsd-doc Digest, Vol 479, Issue 1
*******************************************
More information about the freebsd-doc
mailing list