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

[Mathieu Arnold]

Author: mat
Date: Mon Aug 24 13:11:23 2015
New Revision: 47304
URL: https://svnweb.freebsd.org/changeset/doc/47304

Log:
  Document the opt_IMPLIES/opt_PREVENTS/opt_PREVENTS_MSG helpers.
  
  Sponsored by:	Absolight
  Differential Revision:	https://reviews.freebsd.org/D3409

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	Mon Aug 24 08:23:54 2015	(r47303)
+++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml	Mon Aug 24 13:11:23 2015	(r47304)
@@ -4390,6 +4390,112 @@ QMAKE_ARGS+=	-DTEST:BOOL=false
 .endif</programlisting>
       </sect3>
 
+      <sect3 xml:id="options-implies">
+	<title><varname><replaceable>OPT</replaceable>_IMPLIES</varname></title>
+
+	<para>Provides a way to add dependencies between
+	  options.</para>
+
+	<para>When <replaceable>OPT</replaceable> is selected, all the
+	  options listed in this variable will be selected too.  Using
+	  the <link
+	    linkend="options-configure_enable"><varname><replaceable>OPT</replaceable>_CONFIGURE_ENABLE</varname></link>
+	  described earlier to illustrate:</para>
+
+	<programlisting>OPTIONS_DEFINE=	OPT1 OPT2
+OPT1_IMPLIES=	OPT2
+
+OPT1_CONFIGURE_ENABLE=	opt1
+OPT2_CONFIGURE_ENABLE=	opt2</programlisting>
+
+	<para>Is equivalent to:</para>
+
+	<programlisting>OPTIONS_DEFINE=	OPT1 OPT2
+
+.include <bsd.port.options.mk>
+
+.if ${PORT_OPTIONS:MOPT1}
+CONFIGURE_ARGS+=	--enable-opt1
+.else
+CONFIGURE_ARGS+=	--disable-opt1
+.endif
+
+.if ${PORT_OPTIONS:MOPT2} || ${PORT_OPTIONS:MOPT1}
+CONFIGURE_ARGS+=	--enable-opt2
+.else
+CONFIGURE_ARGS+=	--disable-opt2
+.endif</programlisting>
+
+	<example xml:id="options-implies-ex1">
+	  <title>Simple Use of
+	    <varname><replaceable>OPT</replaceable>_IMPLIES</varname></title>
+
+	  <para>This port has a <literal>X11</literal> option, and a
+	    <literal>GNOME</literal> option that needs the
+	    <literal>X11</literal> option to be selected to
+	    build.</para>
+
+	  <programlisting>OPTIONS_DEFINE=	X11 GNOME
+OPTIONS_DEFAULT=	X11
+
+X11_USE=	xorg=xi,xextproto
+GNOME_USE=	gnome=gtk30
+GNOME_IMPLIES=	X11</programlisting>
+	</example>
+      </sect3>
+
+      <sect3 xml:id="options-prevents">
+	<title><varname><replaceable>OPT</replaceable>_PREVENTS</varname>
+	  and
+	  <varname><replaceable>OPT</replaceable>_PREVENTS_MSG</varname></title>
+
+	<para>Provides a way to add conflicts between options.</para>
+
+	<para>When <replaceable>OPT</replaceable> is selected, all the
+	  options listed in this variable must be un-selected.  If
+	  <varname><replaceable>OPT</replaceable>_PREVENTS_MSG</varname>
+	  is also selected, its content will be shown, explaining why
+	  they conflict.  For example:</para>
+
+	<programlisting>OPTIONS_DEFINE=	OPT1 OPT2
+OPT1_PREVENTS=	OPT2
+OPT1_PREVENTS_MSG=	OPT1 and OPT2 enable conflicting options</programlisting>
+
+	<para>Is roughly equivalent to:</para>
+
+	<programlisting>OPTIONS_DEFINE=	OPT1 OPT2
+
+.include <bsd.port.options.mk>
+
+.if ${PORT_OPTIONS:MOPT2} || ${PORT_OPTIONS:MOPT1}
+BROKEN=	Option OPT1 conflicts with OPT2 (select only one)
+.endif</programlisting>
+
+	<para>The only difference is that the first one will write an
+	  error after running <command>make config</command>,
+	  suggesting changing the selected options.</para>
+
+	<example xml:id="options-prevents-ex1">
+	  <title>Simple Use of
+	    <varname><replaceable>OPT</replaceable>_PREVENTS</varname></title>
+
+	  <para>This port has <literal>X509</literal> and
+	    <literal>SCTP</literal> options.  Both options add
+	    patches, but the patches conflict with each other, so they
+	    cannot be selected at the same time.</para>
+
+	  <programlisting>OPTIONS_DEFINE=	X509 SCTP
+
+SCTP_PATCHFILES=	${PORTNAME}-6.8p1-sctp-2573.patch.gz:-p1
+SCTP_CONFIGURE_WITH=	sctp
+
+X509_PATCH_SITES=	http://www.roumenpetrov.info/openssh/x509/:x509
+X509_PATCHFILES=	${PORTNAME}-7.0p1+x509-8.5.diff.gz:-p1:x509
+X509_PREVENTS=		SCTP
+X509_PREVENTS=		X509 and SCTP patches conflict</programlisting>
+	</example>
+      </sect3>
+
       <sect3 xml:id="options-dependencies">
 	<title>Dependencies</title>