Update severely outdated documentation about dependencies.

Inspired by patch from Francois Tigeot on pkgsrc-wip-discuss.

2 files changed, 36 insertions, 78 deletions

diff --git a/doc/guide/files/creating.xml b/doc/guide/files/creating.xml
index a557e8cc883..eb26ea981ae 100644
--- a/doc/guide/files/creating.xml
+++ b/doc/guide/files/creating.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: creating.xml,v 1.9 2009/09/07 18:22:10 joerg Exp $ -->
+<!-- $NetBSD: creating.xml,v 1.10 2011/05/21 16:39:03 wiz Exp $ -->
 
 <chapter id="creating">
 <title>Creating a new pkgsrc package from scratch</title>
@@ -35,7 +35,10 @@ these dependencies, look where it exists in pkgsrc, and if there is a
 file called <filename>buildlink3.mk</filename> in that directory, add a
 line to your package <filename>Makefile</filename> which includes that
 file just before the last line. If the
-<filename>buildlink3.mk</filename> file does not exist, add a
+<filename>buildlink3.mk</filename> file does not exist, it must be
+created first. The <filename>buildlink3.mk</filename> file makes sure that the package's include files and libraries are provided.</para>
+
+<para>If you just need binaries from a package, add a
 <varname>DEPENDS</varname> line to the Makefile, which specifies the
 version of the dependency and where it can be found in pkgsrc. This line
 should be placed in the third paragraph. If the dependency is only
diff --git a/doc/guide/files/fixes.xml b/doc/guide/files/fixes.xml
index 1c6c01c0806..a826a6bcd86 100644
--- a/doc/guide/files/fixes.xml
+++ b/doc/guide/files/fixes.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: fixes.xml,v 1.103 2011/01/16 08:40:28 wiz Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.104 2011/05/21 16:39:03 wiz Exp $ -->
 
 <chapter id="fixes"> <?dbhtml filename="fixes.html"?>
 <title>Making your package work</title>
@@ -327,38 +327,41 @@ ACCEPTABLE_LICENSES+=xv-license
       </listitem>
 
       <listitem>
-	<para>If your package needs to use another package to build
-	itself and there is no <filename>buildlink3.mk</filename>
-	file available, use the <varname>BUILD_DEPENDS</varname>
-	definition:</para>
+	<para>If your package needs binaries from another package to build,
+	use the <varname>BUILD_DEPENDS</varname> definition:</para>
 
 	<programlisting>
-BUILD_DEPENDS+= autoconf-2.13:../../devel/autoconf
+BUILD_DEPENDS+= scons-[0-9]*:../../devel/scons
 	</programlisting>
       </listitem>
 
       <listitem>
-
 	<para>If your package needs a library with which to link and
 	again there is no <filename>buildlink3.mk</filename> file
-	available, this is specified using the
-	<varname>DEPENDS</varname> definition. For example:</para>
-
-	<programlisting>
-DEPENDS+=       xpm-3.4j:../../graphics/xpm
-	</programlisting>
+	available, create one. Using
+	<varname>DEPENDS</varname> won't be sufficient because the
+	include files and libraries will be hidden from the compiler.</para>
+      </listitem>
 
-	<para>You can also use wildcards in package dependencies:</para>
+      <listitem>
+	<para>If your package needs some executable to be able to run
+	correctly and if there's no
+	<filename>buildlink3.mk</filename> file, this is specified
+	using the <varname>DEPENDS</varname> variable. The
+	<filename role="pkg">print/lyx</filename> package needs to
+	be able to execute the latex binary from the teTeX package
+	when it runs, and that is specified:</para>
 
 	<programlisting>
-DEPENDS+=       xpm-[0-9]*:../../graphics/xpm
+DEPENDS+=        teTeX-[0-9]*:../../print/teTeX
 	</programlisting>
-
-	<para>Note that such wildcard dependencies are retained when
-	creating binary packages.  The dependency is checked when
-	installing the binary package and any package which matches
-	the pattern will be used.  Wildcard dependencies should be
-	used with care.</para>
+      </listitem>
+      <listitem>
+	<para>You can use wildcards in package dependencies. Note that
+	such wildcard dependencies are retained when creating binary
+	packages. The dependency is checked when installing the binary
+	package and any package which matches the pattern will be
+	used. Wildcard dependencies should be used with care.</para>
 
 	<para>The <quote>-[0-9]*</quote> should be used instead of
 	<quote>-*</quote> to avoid potentially ambiguous matches
@@ -370,70 +373,22 @@ DEPENDS+=       xpm-[0-9]*:../../graphics/xpm
 	pre-requisite:</para>
 
 	<programlisting>
-DEPENDS+=       tiff>=3.5.4:../../graphics/tiff
+DEPENDS+=       ImageMagick>=6.0:../../graphics/ImageMagick
 	</programlisting>
 
-	<para>This means that the package will build against version
-	3.5.4 of the tiff library or newer.  Such a dependency may
-	be warranted if, for example, the API of the library has
-	changed with version 3.5.4 and a package would not compile
-	against an earlier version of tiff.</para>
-
-	<para>Please note that such dependencies should only be
-	updated if a package requires a newer pre-requisite, but
-	not to denote recommendations such as
-	ABI changes that do not prevent a package from building
-	correctly.  Such recommendations can be expressed using
-	<varname>ABI_DEPENDS</varname>:</para>
+	<para>This means that the package will build using version 6.0
+	of ImageMagick or newer. Such a dependency may be warranted
+	if, for example, the command line options of an executable
+	have changed.</para>
 
-	<programlisting>
-ABI_DEPENDS+=   tiff>=3.6.1:../../graphics/tiff
-	</programlisting>
-
-	<para>In addition to the above <varname>DEPENDS</varname>
-	line, this denotes that while a package will build against
-	tiff&gt;=3.5.4, at least version 3.6.1 is recommended.
-	<varname>ABI_DEPENDS</varname> entries will be turned into
-	dependencies unless explicitly ignored (in which case a
-	warning will be printed).</para>
-
-	<para>To ignore these ABI dependency recommendations and just
-	use the required <varname>DEPENDS</varname>, set
-	<varname>USE_ABI_DEPENDS=NO</varname>.   This may make
-	it easier and faster to update packages built using pkgsrc,
-	since older compatible dependencies can continue to be
-	used. This is useful for people who watch their rebuilds
-	very carefully; it is not very good as a general-purpose
-	hammer.  If you use it, you need to be mindful of possible
-	ABI changes, including those from the underlying OS.</para>
-
-	<para>Packages that are built with recommendations ignored
-	may not be uploaded to ftp.NetBSD.org by developers and
-	should not be used across different systems that may have
-	different versions of binary packages installed.</para>
+	<para>If you need to depend on minimum versions of libraries,
+	see the buildlink section of the pkgsrc guide.</para>
 
 	<para>For security fixes, please update the package
 	vulnerabilities file. See <xref
 	linkend="security-handling"/> for more
 	information.</para>
       </listitem>
-
-      <listitem>
-	<para>If your package needs some executable to be able to run
-	correctly and if there's no
-	<filename>buildlink3.mk</filename> file, this is specified
-	using the <varname>DEPENDS</varname> variable. The
-	<filename role="pkg">print/lyx</filename> package needs to
-	be able to execute the latex binary from the teTeX package
-	when it runs, and that is specified:</para>
-
-	<programlisting>
-DEPENDS+=        teTeX-[0-9]*:../../print/teTeX
-	</programlisting>
-
-	<para>The comment about wildcard dependencies from previous
-	paragraph applies here, too.</para>
-      </listitem>
     </orderedlist>
 
     <para>If your package needs files from another package to build,