docs/106065: [Doc update] Auto-detected configure options (follows PR/105868)

[Ganael LAPLANCHE]

>Number:         106065
>Category:       docs
>Synopsis:       [Doc update] Auto-detected configure options (follows PR/105868)
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Thu Nov 30 13:30:19 GMT 2006
>Closed-Date:
>Last-Modified:
>Originator:     Ganael LAPLANCHE
>Release:        FreeBSD 6.2-PRERELEASE amd64
>Organization:
http://contribs.martymac.com
>Environment:
System: FreeBSD home.martymac.com 6.2-PRERELEASE FreeBSD 6.2-PRERELEASE #0: Sat Oct 21 10:24:44 CEST 2006 root at martymac.com:/usr/src/sys/amd64/compile/MYKERNEL amd64
>Description:
Here is a new page for 'Dos and don'ts' describing the problem encountered in PR/105868 related to auto-detections in a configure script. It explains why it is important for a porter to explicitly add --without- or --disable- options when a functionality is disabled.
>How-To-Repeat:

>Fix:


Patch attached with submission follows:

--- en_US.ISO8859-1/books/porters-handbook/book.sgml.orig	Thu Nov 30 09:36:46 2006
+++ en_US.ISO8859-1/books/porters-handbook/book.sgml	Thu Nov 30 10:42:42 2006
@@ -8784,6 +8784,78 @@
 	  them.</para>
       </sect1>
 
+      <sect1 id="porting-configure">
+	<title>Configure script and feature auto-activation</title>
+
+      <sect2 id="configure-control">
+	<title>Control your port</title>
+
+	<para>When using a configure script, keep control on what feature is activated 
+      or not. Avoid using auto-detection of libraries that would silently activate
+      something you wouldn't be aware of. Say, explicitly disable options when you
+      do not want them activated (do not just activate them when you want them).</para>
+      </sect2>
+      
+      <sect2 id="configure-example">
+	<title>Example</title>
+
+      <para>Silently-activated features can bring you in trouble, let's give an example :</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>I have libxxx installed on my system (not used by any program)</para>
+        </listitem>
+
+        <listitem>
+          <para>I don't want the application yyy to be built with xxx support so I disable the xxx option in the port's 'make config' or by defining the WITHOUT_XXX option</para>
+        </listitem>
+
+        <listitem>
+          <para>Unfortunately, the port manages the option by *only* adding a --with-xxx (or --enable-xxx) option to <makevar>CONFIGURE_ARGS</makevar> when <makevar>WITH_XXX</makevar> is defined (so nothing happens here)</para>
+        </listitem>
+
+        <listitem>
+          <para>The configure script is run and detects the library. It silently activates the option since our machine *can* run the xxx option</para>
+        </listitem>
+
+        <listitem>
+          <para>The application is built with the xxx option</para>
+        </listitem>
+      </itemizedlist>
+
+      </sect2>
+
+      <sect2 id="configure-bad">
+	<title>The bad things</title>
+
+      <para>Why is it so bad ?</para>
+     
+      <itemizedlist>
+        <listitem>
+          <para>I have a feature I didn't want (that I have explicitly disabled)</para>
+        </listitem>
+
+        <listitem>
+          <para>I can uninstall libxxx and break my application yyy, since no dependency is recorded in the database</para>
+        </listitem>
+      </itemizedlist>
+
+      </sect2>
+
+      <sect2 id="configure-solution">
+	<title>A solution</title>
+
+      <para>So, what can I do ?</para>
+
+      <para>When possible, add (force) the corresponding --disable- or --without- option
+      for *each* --enable- or --with one you are using in the port's Makefile (if 
+      supported by the configure script). This will ensure that each dependency is
+      recorded and that the port installs *exactly* the features users want.</para>
+
+      </sect2>
+
+      </sect1>
+
       <sect1 id="porting-wrkdir">
 	<title><makevar>WRKDIR</makevar></title>
 

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