From nobody@FreeBSD.org  Wed Apr 11 18:33:19 2012
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 54EFE1065672
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 11 Apr 2012 18:33:19 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from red.freebsd.org (red.freebsd.org [IPv6:2001:4f8:fff6::22])
	by mx1.freebsd.org (Postfix) with ESMTP id 13B088FC18
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 11 Apr 2012 18:33:19 +0000 (UTC)
Received: from red.freebsd.org (localhost [127.0.0.1])
	by red.freebsd.org (8.14.4/8.14.4) with ESMTP id q3BIXIpr034327
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 11 Apr 2012 18:33:18 GMT
	(envelope-from nobody@red.freebsd.org)
Received: (from nobody@localhost)
	by red.freebsd.org (8.14.4/8.14.4/Submit) id q3BIXILU034322;
	Wed, 11 Apr 2012 18:33:18 GMT
	(envelope-from nobody)
Message-Id: <201204111833.q3BIXILU034322@red.freebsd.org>
Date: Wed, 11 Apr 2012 18:33:18 GMT
From: "A.J. Kehoe IV (Nanoman)" <zxMbzY3e@nanoman.ca>
To: freebsd-gnats-submit@FreeBSD.org
Subject: [patch] Automatic Detection of Dependencies Addendum for Porter's Handbook
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         166855
>Category:       docs
>Synopsis:       [patch] Automatic Detection of Dependencies Addendum for Porter's Handbook
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    wblock
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Wed Apr 11 18:40:11 UTC 2012
>Closed-Date:    Mon Apr 16 02:33:47 UTC 2012
>Last-Modified:  Mon Apr 16 02:40:09 UTC 2012
>Originator:     A.J. Kehoe IV (Nanoman)
>Release:        9.0
>Organization:
Nanoman's Company
>Environment:
FreeBSD localhost 9.0-RELEASE FreeBSD 9.0-RELEASE #0: Tue Jan  3 07:15:25 UTC 2012     root@obrian.cse.buffalo.edu:/usr/obj/usr/src/sys/GENERIC  i386
>Description:
The automatic detection of dependencies causes inconsistent indexing, and therefore makes it very difficult to automate port and package management.  A rule forbidding this method should be included in the Porter's Handbook.
>How-To-Repeat:

>Fix:
I've attached an update for doc/en_US.ISO8859-1/books/porters-handbook/book.sgml.

Patch attached with submission follows:

--- book.sgml.old	2012-04-11 13:34:36.000000000 -0400
+++ book.sgml	2012-04-11 14:27:09.000000000 -0400
@@ -3843,6 +3843,56 @@
 	  may be able to save a large number of people&mdash;including
 	  yourself&mdash; a lot of grief in the process.</para>
       </sect2>
+
+      <sect2>
+	<title>Automatic Detection Causes Problems</title>
+
+	<para>Dependencies must be declared either explicitly or by
+	  using the <link
+	    linkend="makefile-options">OPTIONS framework</link>.
+	  Using other methods like automatic detection complicates
+	  indexing, which causes problems for port and package
+	  management.</para>
+
+	<example>
+	  <title>Wrong Declaration of an Optional Dependency</title>
+
+	  <programlisting>.include &lt;bsd.port.pre.mk&gt;
+
+.if exists(${LOCALBASE}/bin/foo)
+LIB_DEPENDS=	bar:${PORTSDIR}/foo/bar
+.endif</programlisting>
+	</example>
+
+	<para>The problem with the above method is that it declares a
+	  dependency based on the existence of a file that may have
+	  been installed by another port.  If all options were
+	  recursively defined for a batch of ports and an index of
+	  these ports was built, then the index would become
+	  inconsistent during the installation of this batch if one of
+	  its ports installed that file.  A new index would need to be
+	  created, but it too may be inconsistent if there are other
+	  ports that use this same method.</para>
+
+	<example>
+	  <title>Correct Declaration of an Optional Dependency</title>
+
+	  <programlisting>OPTIONS=		BAR	"Enable bar support" on
+
+.include &lt;bsd.port.pre.mk&gt;
+
+.if defined(WITH_BAR) && !defined(WITHOUT_BAR)
+LIB_DEPENDS=	bar:${PORTSDIR}/foo/bar
+.endif</programlisting>
+	</example>
+
+	<para>This second method is correct because it would not cause
+	  inconsistencies in the index of a batch of ports, provided
+	  the batch's options were defined prior to the index's build.
+	  This makes it possible to use simple scripts to automate the
+	  building, installation, and updating of these ports and
+	  their packages.</para>
+      </sect2>
     </sect1>
 
     <sect1 id="makefile-masterdir">


>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->wblock 
Responsible-Changed-By: wblock 
Responsible-Changed-When: Thu Apr 12 19:41:36 UTC 2012 
Responsible-Changed-Why:  
Take. 

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

From: Max Brazhnikov <makc@freebsd.org>
To: freebsd-doc@freebsd.org
Cc: "A.J. Kehoe IV (Nanoman)" <zxMbzY3e@nanoman.ca>,
        freebsd-gnats-submit@freebsd.org
Subject: Re: docs/166855: [patch] Automatic Detection of Dependencies Addendum for Porter's Handbook
Date: Thu, 12 Apr 2012 22:26:35 +0000

 On Wed, 11 Apr 2012 18:33:18 GMT, A.J. Kehoe IV (Nanoman) wrote:
 > +       <example>
 > +         <title>Correct Declaration of an Optional Dependency</title>
 > +
 > +         <programlisting>OPTIONS=              BAR     "Enable bar support" on
 > +
 > +.include &lt;bsd.port.pre.mk&gt;
 > +
 > +.if defined(WITH_BAR) && !defined(WITHOUT_BAR)
 > +LIB_DEPENDS=   bar:${PORTSDIR}/foo/bar
 > +.endif</programlisting>
 > +       </example>
 
 It's not enough. You also need to add something like --disable-bar to configure arguments and of course configure script should respect the switch.

From: "A.J. Kehoe IV (Nanoman)" <zxMbzY3e@nanoman.ca>
To: "Max Brazhnikov" <makc@freebsd.org>
Cc: freebsd-doc@freebsd.org,
 freebsd-gnats-submit@freebsd.org
Subject: Re: docs/166855: [patch] Automatic Detection of Dependencies 
     Addendum for Porter's Handbook
Date: Thu, 12 Apr 2012 19:19:24 -0400 (EDT)

 > On Wed, 11 Apr 2012 18:33:18 GMT, A.J. Kehoe IV (Nanoman) wrote:
 >> +       <example>
 >> +         <title>Correct Declaration of an Optional Dependency</title>
 >> +
 >> +         <programlisting>OPTIONS=              BAR     "Enable bar
 >> support" on
 >> +
 >> +.include &lt;bsd.port.pre.mk&gt;
 >> +
 >> +.if defined(WITH_BAR) && !defined(WITHOUT_BAR)
 >> +LIB_DEPENDS=   bar:${PORTSDIR}/foo/bar
 >> +.endif</programlisting>
 >> +       </example>
 >
 > It's not enough. You also need to add something like --disable-bar to
 > configure arguments and of course configure script should respect the
 > switch.
 
 This is needed only if it's required by the configure script.  If support
 for a dependency doesn't need to be compiled in, then simply including it
 in the dependency list would suffice.
 
 My examples included only the elements that were needed to illustrate my
 point.  Anyone wanting to use optional dependencies should read the
 "makefile-options" section that I linked to, along with any other sections
 that are relevant to their port.
 
State-Changed-From-To: open->closed 
State-Changed-By: wblock 
State-Changed-When: Mon Apr 16 02:33:03 UTC 2012 
State-Changed-Why:  
Revised version of original patch committed.  Thanks! 

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

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/166855: commit references a PR
Date: Mon, 16 Apr 2012 02:31:47 +0000 (UTC)

 wblock      2012-04-16 02:31:31 UTC
 
   FreeBSD doc repository
 
   Modified files:
     en_US.ISO8859-1/books/porters-handbook book.sgml 
   Log:
   Add a section describing automatic dependencies, the problems they
   cause, and the correct approach.  Patch is a modified version of the
   original in the PR.
   
   PR:             docs/166855
   Submitted by:   A.J. Kehoe IV
   
   Revision  Changes    Path
   1.1178    +50 -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:
