Add a text on feature auto-detection in configure script being harmfull

PR:		docs/106065 (based on)
Submitted by:	Ganael LAPLANCHE <ganael.laplanche@martymac.com>

1 files changed, 41 insertions, 0 deletions

diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml
index b9126d5709..fd8448e53a 100644
--- a/en_US.ISO8859-1/books/porters-handbook/book.sgml
+++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml
@@ -3865,6 +3865,47 @@ RUN_DEPENDS+=	bar:${PORTSDIR}/bar/bar
 
       </sect2>
 
+      <sect2>
+	<title>Feature auto-activation</title>
+
+	<para>When using a GNU configure script, keep an eye on which optional
+	  features are activated by auto-detection.  Explicitly disable
+	  optional features you do not wish to be used by passing respective
+	  <literal>--without-xxx</literal> or <literal>--disable-xxx</literal>
+	  in <makevar>CONFIGURE_ARGS</makevar>.</para>
+
+	<example>
+	  <title>Wrong handling of an option</title>
+	  <programlisting>.if defined(WITH_FOO)
+LIB_DEPENDS+=		foo.0:${PORTSDIR}/devel/foo
+CONFIGURE_ARGS+=	--enable-foo
+.endif</programlisting>
+	</example>
+
+	<para>In the example above, imagine a library libfoo is installed on
+	  the system.  User does not want this application to use libfoo, so he
+	  toggled the option off in the <literal>make config</literal> dialog.
+	  But the application's configure script detects the library present in
+	  the system and includes its support in the resulting executable.  Now
+	  when user decides to remove libfoo from the system, the ports system
+	  does not protest (no dependency on libfoo was recorded) but the
+	  application breaks.</para>
+
+	<example>
+	  <title>Correct handling of an option</title>
+	  <programlisting>.if defined(WITH_FOO)
+LIB_DEPENDS+=		foo.0:${PORTSDIR}/devel/foo
+CONFIGURE_ARGS+=	--enable-foo
+.else
+CONFIGURE_ARGS+=	--disable-foo
+.endif</programlisting>
+	</example>
+
+	<para>In the second example, the library libfoo is explicitly disabled.
+	  The configure script does not enable related features in the
+	  application, despite library's presence in the system.</para>
+      </sect2>
+
     </sect1>
 
     <sect1 id="makefile-wrkdir">