[pkgsrc/trunk]: pkgsrc/doc/guide/files guide: Document TOOL_DEPENDS

[leot <leot%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/8f13b30cfb06
branches:  trunk
changeset: 334202:8f13b30cfb06
user:      leot <leot%pkgsrc.org@localhost>
date:      Mon May 20 18:14:24 2019 +0000

description:
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.

diffstat:

 doc/guide/files/creating.xml |  15 ++++++++++++---
 doc/guide/files/fixes.xml    |  39 ++++++++++++++++++++++++++++++---------
 doc/guide/files/tools.xml    |   4 ++--
 3 files changed, 44 insertions(+), 14 deletions(-)

diffs (128 lines):

diff -r ad4cb3e50634 -r 8f13b30cfb06 doc/guide/files/creating.xml
--- a/doc/guide/files/creating.xml      Mon May 20 16:58:29 2019 +0000
+++ b/doc/guide/files/creating.xml      Mon May 20 18:14:24 2019 +0000
@@ -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 @@
 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 -r ad4cb3e50634 -r 8f13b30cfb06 doc/guide/files/fixes.xml
--- a/doc/guide/files/fixes.xml Mon May 20 16:58:29 2019 +0000
+++ b/doc/guide/files/fixes.xml Mon May 20 18:14:24 2019 +0000
@@ -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 @@
     <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 @@
     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>
+    <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 a <varname>BUILD_DEPENDS</varname> and a
-    <varname>DEPENDS</varname> definition is:</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 @@
 
       <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 -r ad4cb3e50634 -r 8f13b30cfb06 doc/guide/files/tools.xml
--- a/doc/guide/files/tools.xml Mon May 20 16:58:29 2019 +0000
+++ b/doc/guide/files/tools.xml Mon May 20 18:14:24 2019 +0000
@@ -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