docs/76472: [patch] tell porters handbook about OPTIONS

[Edwin Groothuis]

>Number:         76472
>Category:       docs
>Synopsis:       [patch] tell porters handbook about OPTIONS
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Wed Jan 19 21:10:24 GMT 2005
>Closed-Date:
>Last-Modified:
>Originator:     Edwin Groothuis
>Release:        FreeBSD 5.2.1-RELEASE i386
>Organization:
-
>Environment:
System: FreeBSD k7.mavetju 5.2.1-RELEASE FreeBSD 5.2.1-RELEASE #8: Wed Dec 15 16:58:01 EST 2004 edwin at k7.mavetju:/usr/src-5.2.1/sys/i386/compile/k7 i386


>Description:

Despite being there as a feature for nearly a year now, there is
no mentioning of the OPTIONS features in the Porters Handbook.

Thanks to Florent Thoumie <flz at xbsd.org> for docbookifying it.

>How-To-Repeat:
>Fix:


--- book.sgml.old	Wed Jan 19 13:30:08 2005
+++ book.sgml	Wed Jan 19 14:21:38 2005
@@ -3538,6 +3538,84 @@
 	  </table>
 
       </sect2>
+
+      <sect2>
+	<title><makevar>OPTIONS</makevar></title>
+
+	<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/portname/options</filename>. Next
+	    time when the port has to be rebuild, the options are reused. Never
+	    again you 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>
+	</sect3>
+
+	<sect3>
+	  <title>Syntax</title>
+	  <para>The syntax for the <makevar>OPTIONS</makevar> variable is:
+
+<programlisting>OPTIONS=	option	"descriptive text" default ...
+</programlisting>
+
+	  The value for default is either <literal>ON</literal> or
+	  <literal>OFF</literal>. Multiple repetitions of these three fields
+	  is allowed.</para>
+
+	  <para>When the user runs the <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 it doesn't exist, it will use the values of
+	  <makevar>OPTIONS</makevar> to create a dialogbox where the options
+	  can be enabled or disabled. Then the options file is saved and the
+	  selected variables are set.</para>
+
+	  <para>Use <command>make showconfig</command> to see the saved
+	  configuration. Use <command>make rmconfig</command> to remove the saved
+	  configuration.</para>
+
+	<sect3>
+	  <title>Example</title>
+	  <example id="ports-options-simple-use">
+	    <title>Simple use of <makevar>OPTIONS</makevar></title>
+	    <para><programlisting>OPTIONS=	foo "Enable option foo" On \
+			bar "Support feature bar" Off
+
+.include <bsd.port.pre.mk>
+
+.if defined(WITH_FOO)
+CONFIGURE_ARGS+=	--with-foo
+.else
+CONFIGURE_ARGS+=	--without-foo
+.endif
+
+.if defined(WITH_BAR)
+RUN_DEPENDS+=	bar:${PORTSDIR}/bar/bar
+.endif
+
+.include <bsd.port.post.mk></programlisting></para>
+	  </example>
+
+	<sect3>
+	  <title>Brokeness</title>
+	  <itemizedlist>
+	    <listitem>
+	      <para><command>make index</command> doesn't follow
+	      <makevar>OPTIONS</makevar> yet (ports/75727)</para>
+	    </listitem>
+	    <listitem>
+	      <para><makevar>PACKAGE_BUILDING</makevar> is ignoring
+	      <makevar>OPTIONS</makevar> (ports/75727?)</para>
+	    </listitem>
+	  </itemizedlist>
+	</sect3>
+	
+      </sect2>
+
     </sect1>
 
     <sect1 id="makefile-wrkdir">

>Release-Note:
>Audit-Trail:
>Unformatted: