CVS commit: pkgsrc/doc/guide/files

["Leonardo Taccari" <leot%netbsd.org@localhost>]

Module Name:    pkgsrc
Committed By:   leot
Date:           Mon May 20 18:14:24 UTC 2019

Modified Files:
        pkgsrc/doc/guide/files: creating.xml fixes.xml tools.xml

Log Message:
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.


To generate a diff of this commit:
cvs rdiff -u -r1.27 -r1.28 pkgsrc/doc/guide/files/creating.xml
cvs rdiff -u -r1.147 -r1.148 pkgsrc/doc/guide/files/fixes.xml
cvs rdiff -u -r1.7 -r1.8 pkgsrc/doc/guide/files/tools.xml

Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.

Modified files:

Index: pkgsrc/doc/guide/files/creating.xml
diff -u pkgsrc/doc/guide/files/creating.xml:1.27 pkgsrc/doc/guide/files/creating.xml:1.28
--- pkgsrc/doc/guide/files/creating.xml:1.27    Mon Jun  4 23:55:00 2018
+++ pkgsrc/doc/guide/files/creating.xml Mon May 20 18:14:24 2019
@@ -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.
 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
 

Index: pkgsrc/doc/guide/files/fixes.xml
diff -u pkgsrc/doc/guide/files/fixes.xml:1.147 pkgsrc/doc/guide/files/fixes.xml:1.148
--- pkgsrc/doc/guide/files/fixes.xml:1.147      Wed Jan  2 18:48:21 2019
+++ pkgsrc/doc/guide/files/fixes.xml    Mon May 20 18:14:24 2019
@@ -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

Index: pkgsrc/doc/guide/files/tools.xml
diff -u pkgsrc/doc/guide/files/tools.xml:1.7 pkgsrc/doc/guide/files/tools.xml:1.8
--- pkgsrc/doc/guide/files/tools.xml:1.7        Sat Jun 11 20:19:36 2016
+++ pkgsrc/doc/guide/files/tools.xml    Mon May 20 18:14:24 2019
@@ -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