svn commit: r47394 - head/en_US.ISO8859-1/books/porters-handbook/makefiles

[Mathieu Arnold]

Author: mat
Date: Wed Sep  9 13:01:54 2015
New Revision: 47394
URL: https://svnweb.freebsd.org/changeset/doc/47394

Log:
  Add documentation about opt_VARS.
  
  Reviewed by:	wblock
  Sponsored by:	Absolight
  Differential Revision:	https://reviews.freebsd.org/D3516

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml

Modified: head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml	Wed Sep  9 13:01:45 2015	(r47393)
+++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml	Wed Sep  9 13:01:54 2015	(r47394)
@@ -4429,6 +4429,66 @@ X509_PREVENTS_MSG=	X509 and SCTP patches
 	</example>
       </sect3>
 
+      <sect3 xml:id="options-vars">
+	<title><varname><replaceable>OPT</replaceable>_VARS</varname>
+	  and
+	  <varname><replaceable>OPT</replaceable>_VARS_OFF</varname></title>
+
+	<para>Provides a generic way to set and append to
+	  variables.</para>
+
+	<warning><para>Before using
+	  <varname><replaceable>OPT</replaceable>_VARS</varname> and
+	  <varname><replaceable>OPT</replaceable>_VARS_OFF</varname>,
+	  see if there is already a more specific helper available in
+	  <xref linkend="options-variables"/>.</para></warning>
+
+	<para>When option <replaceable>OPT</replaceable> is selected,
+	  and <varname><replaceable>OPT</replaceable>_VARS</varname>
+	  defined,
+	  <literal><replaceable>key</replaceable>=<replaceable>value</replaceable></literal>
+	  and
+	  <literal><replaceable>key</replaceable>+=<replaceable>value</replaceable></literal>
+	  pairs are evaluated from
+	  <varname><replaceable>OPT</replaceable>_VARS</varname>.  An
+	  <literal>=</literal> cause the existing value of
+	  <literal>KEY</literal> to be overwritten, an
+	  <literal>+=</literal> appends to the value.
+	  <varname><replaceable>OPT</replaceable>_VARS_OFF</varname>
+	  works the same way, but when <literal>OPT</literal> is
+	  <emphasis>not</emphasis> selected.</para>
+
+	<programlisting>OPTIONS_DEFINE=	OPT1 OPT2 OPT3
+OPT1_VARS=	also_build+=bin1
+OPT2_VARS=	also_build+=bin2
+OPT3_VARS=	bin3_build=yes
+OPT3_VARS_OFF=	bin3_build=no
+
+MAKE_ARGS=	ALSO_BUILD="${ALSO_BUILD}" BIN3_BUILD="${BIN3_BUILD}"</programlisting>
+
+	<para>is equivalent to:</para>
+
+	<programlisting>OPTIONS_DEFINE=	OPT1 OPT2
+
+MAKE_ARGS=	ALSO_BUILD="${ALSO_BUILD}" BIN3_BUILD="${BIN3_BUILD}"
+
+.include <bsd.port.options.mk>
+
+.if ${PORT_OPTIONS:MOPT1}
+ALSO_BUILD+=	bin1
+.endif
+
+.if ${PORT_OPTIONS:MOPT2}
+ALSO_BUILD+=	bin2
+.endif
+
+.if ${PORT_OPTIONS:MOPT2}
+BIN3_BUILD=	yes
+.else
+BIN3_BUILD=	no
+.endif</programlisting>
+      </sect3>
+
       <sect3 xml:id="options-dependencies">
 	<title>Dependencies,
 	  <varname><replaceable>OPT</replaceable>_<replaceable>DEPTYPE</replaceable></varname>