guide: Document TOOL_DEPENDS

Document TOOL_DEPENDS and clarify the differencies with BUILD_DEPENDS.
Adjust previous BUILD_DEPENDS examples (all of them were actually
TOOL_DEPENDS).

XXX: No BUILD_DEPENDS example is provided, if you have any good and common
XXX: BUILD_DEPENDS example please add it (a TODO comment was added regarding
XXX: that).  At least according a quick grep of BUILD_DEPENDS probably most of
XXX: them are actually BUILD_DEPENDS and maybe all real BUILD_DEPENDS are via
XXX: buildlink3.mk inclusion.

3 files changed, 45 insertions, 15 deletions

diff --git a/doc/guide/files/creating.xml b/doc/guide/files/creating.xml
index 4744f2b5b36..056064a0390 100644
--- a/doc/guide/files/creating.xml
+++ b/doc/guide/files/creating.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: creating.xml,v 1.27 2018/06/04 23:55:00 minskim Exp $ -->
+<!-- $NetBSD: creating.xml,v 1.28 2019/05/20 18:14:24 leot Exp $ -->
 
 <chapter id="creating">
 <title>Creating a new pkgsrc package from scratch</title>
@@ -43,13 +43,22 @@ created first. The <filename>buildlink3.mk</filename> file makes sure that the p
 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
 needed for building the package, but not when using it, use
-<varname>BUILD_DEPENDS</varname> instead of <varname>DEPENDS</varname>.
+<varname>TOOL_DEPENDS</varname> or <varname>BUILD_DEPENDS</varname>
+instead of <varname>DEPENDS</varname>.
+The difference between <varname>TOOL_DEPENDS</varname> and
+<varname>BUILD_DEPENDS</varname> occurs when cross-compiling:
+<varname>TOOL_DEPENDS</varname> are <emphasis>native</emphasis>
+packages, i.e. packages for the architecture where the package
+is built;
+<varname>BUILD_DEPENDS</varname> are <emphasis>target</emphasis>
+packages, i.e. packages for the architecture for which the package
+is built.
 Your package may then look like this:</para>
 
 <programlisting>
 [...]
 
-BUILD_DEPENDS+= libxslt-[0-9]*:../../textproc/libxslt
+TOOL_DEPENDS+=  libxslt-[0-9]*:../../textproc/libxslt
 DEPENDS+=       screen-[0-9]*:../../misc/screen
 DEPENDS+=       screen>=4.0:../../misc/screen
 
diff --git a/doc/guide/files/fixes.xml b/doc/guide/files/fixes.xml
index 76170642636..f2d04112943 100644
--- a/doc/guide/files/fixes.xml
+++ b/doc/guide/files/fixes.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: fixes.xml,v 1.147 2019/01/02 18:48:21 tnn Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.148 2019/05/20 18:14:24 leot Exp $ -->
 
 <chapter id="fixes"> <?dbhtml filename="fixes.html"?>
 <title>Making your package work</title>
@@ -291,7 +291,8 @@ ACCEPTABLE_LICENSES+=xv-license
     <para>Your package may depend on some other package being present
     - and there are various ways of expressing this dependency.
     pkgsrc supports the <varname>BUILD_DEPENDS</varname> and
-    <varname>DEPENDS</varname> definitions, the
+    <varname>DEPENDS</varname> and
+    <varname>TOOL_DEPENDS</varname> definitions, the
     <varname>USE_TOOLS</varname> definition, as well as dependencies
     via <filename>buildlink3.mk</filename>, which is the preferred way
     to handle dependencies, and which uses the variables named above.
@@ -301,15 +302,24 @@ ACCEPTABLE_LICENSES+=xv-license
     follows: The <varname>DEPENDS</varname> definition registers
     that pre-requisite in the binary package so it will be pulled in
     when the binary package is later installed, whilst the
-    <varname>BUILD_DEPENDS</varname> definition does not, marking a
-    dependency that is only needed for building the package.</para>
+    <varname>BUILD_DEPENDS</varname> and <varname>TOOL_DEPENDS</varname>
+    definitions does not, marking a dependency that is only needed for
+    building the package.</para>
 
     <para>This means that if you only need a package present whilst
     you are building, it should be noted as a
-    <varname>BUILD_DEPENDS</varname>.</para>
-
-    <para>The format for a <varname>BUILD_DEPENDS</varname> and a
-    <varname>DEPENDS</varname> definition is:</para>
+    <varname>TOOL_DEPENDS</varname> or
+    <varname>BUILD_DEPENDS</varname>.  When cross-compiling,
+    <varname>TOOL_DEPENDS</varname> are <emphasis>native</emphasis>
+    packages, i.e. packages for the architecture where the package
+    is built;
+    <varname>BUILD_DEPENDS</varname> are <emphasis>target</emphasis>
+    packages, i.e. packages for the architecture for which the package
+    is built.</para>
+
+    <para>The format for <varname>BUILD_DEPENDS</varname>,
+    <varname>DEPENDS</varname> and <varname>TOOL_DEPENDS</varname>
+    definition is:</para>
 
 <programlisting>
 &lt;pre-req-package-name&gt;:../../&lt;category&gt;/&lt;pre-req-package&gt;
@@ -346,14 +356,25 @@ ACCEPTABLE_LICENSES+=xv-license
 
       <listitem>
 	<para>If your package needs binaries from another package to build,
-	use the <varname>BUILD_DEPENDS</varname> definition:</para>
+	use the <varname>TOOL_DEPENDS</varname> definition:</para>
 
 <programlisting>
-BUILD_DEPENDS+= itstool-[0-9]*:../../textproc/itstool
+TOOL_DEPENDS+= itstool-[0-9]*:../../textproc/itstool
 </programlisting>
       </listitem>
 
       <listitem>
+	<para>If your package needs static libraries to link against, header
+	files to include, etc. from another package to build,
+	use the <varname>BUILD_DEPENDS</varname> definition.</para>
+
+<!--
+<programlisting>
+BUILD_DEPENDS+= TODO: find a good example
+</programlisting> -->
+      </listitem>
+
+      <listitem>
 	<para>If your package needs a library with which to link and
 	there is no <filename>buildlink3.mk</filename> file
 	available, create one. Using
diff --git a/doc/guide/files/tools.xml b/doc/guide/files/tools.xml
index 6a86eadda79..0148b7f603a 100644
--- a/doc/guide/files/tools.xml
+++ b/doc/guide/files/tools.xml
@@ -1,11 +1,11 @@
-<!-- $NetBSD: tools.xml,v 1.7 2016/06/11 20:19:36 rillig Exp $ -->
+<!-- $NetBSD: tools.xml,v 1.8 2019/05/20 18:14:24 leot Exp $ -->
 
 <chapter id="tools">
 <title>Tools needed for building or running</title>
 
 <para>The <varname>USE_TOOLS</varname> definition is used both internally
 by pkgsrc and also for individual packages to define what commands
-are needed for building a package (like <varname>BUILD_DEPENDS</varname>)
+are needed for building a package (like <varname>TOOL_DEPENDS</varname>)
 or for later run-time of an installed packaged (such as
 <varname>DEPENDS</varname>).
 If the native system provides an adequate tool, then in many cases, a pkgsrc