docs/166855: [patch] Automatic Detection of Dependencies Addendum for Porter's Handbook

[A.J. Kehoe IV (Nanoman)]

>Number:         166855
>Category:       docs
>Synopsis:       [patch] Automatic Detection of Dependencies Addendum for Porter's Handbook
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Wed Apr 11 18:40:11 UTC 2012
>Closed-Date:
>Last-Modified:
>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 at 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—including
 	  yourself— 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 <bsd.port.pre.mk>
+
+.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 <bsd.port.pre.mk>
+
+.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:
>Unformatted: