From nobody@FreeBSD.org  Thu Nov 30 13:27:09 2006
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [69.147.83.52])
	by hub.freebsd.org (Postfix) with ESMTP id 1965D16A407
	for <freebsd-gnats-submit@FreeBSD.org>; Thu, 30 Nov 2006 13:27:09 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (www.freebsd.org [69.147.83.33])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 002B943CA3
	for <freebsd-gnats-submit@FreeBSD.org>; Thu, 30 Nov 2006 13:27:00 +0000 (GMT)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.13.1/8.13.1) with ESMTP id kAUDR8Wc048126
	for <freebsd-gnats-submit@FreeBSD.org>; Thu, 30 Nov 2006 13:27:08 GMT
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.13.1/8.13.1/Submit) id kAUDR8xP048125;
	Thu, 30 Nov 2006 13:27:08 GMT
	(envelope-from nobody)
Message-Id: <200611301327.kAUDR8xP048125@www.freebsd.org>
Date: Thu, 30 Nov 2006 13:27:08 GMT
From: Ganael LAPLANCHE<ganael.laplanche@martymac.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: [Doc update] Auto-detected configure options (follows PR/105868)
X-Send-Pr-Version: www-3.0

>Number:         106065
>Category:       docs
>Synopsis:       [Doc update] Auto-detected configure options (follows PR/105868)
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    pav
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Thu Nov 30 13:30:19 GMT 2006
>Closed-Date:    Thu Nov 30 20:46:28 GMT 2006
>Last-Modified:  Thu Nov 30 21:00:26 GMT 2006
>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@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:
Responsible-Changed-From-To: freebsd-doc->pav 
Responsible-Changed-By: pav 
Responsible-Changed-When: Thu Nov 30 14:11:49 UTC 2006 
Responsible-Changed-Why:  
Take; the idea is good but I'd like to rewrite the wording first. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=106065 
State-Changed-From-To: open->closed 
State-Changed-By: pav 
State-Changed-When: Thu Nov 30 20:08:12 UTC 2006 
State-Changed-Why:  
Good idea to talk about this.  I took the liberty of rewriting the text, adding 
some examples. 

Also I have put it into the 5.11 Makefile Options section, where it belongs, 
instead of Dos and Don't section. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=106065 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/106065: commit references a PR
Date: Thu, 30 Nov 2006 20:51:37 +0000 (UTC)

 pav         2006-11-30 20:44:45 UTC
 
   FreeBSD doc repository
 
   Modified files:
     en_US.ISO8859-1/books/porters-handbook book.sgml 
   Log:
   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>
   
   Revision  Changes    Path
   1.770     +41 -0     doc/en_US.ISO8859-1/books/porters-handbook/book.sgml
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 
>Unformatted:
