Add a "tools" chapter. Documents the USE_TOOLS.

4 files changed, 125 insertions, 4 deletions

diff --git a/doc/guide/files/Makefile b/doc/guide/files/Makefile
index 074a4999860..262e9669905 100644
--- a/doc/guide/files/Makefile
+++ b/doc/guide/files/Makefile
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.4 2005/06/08 13:59:30 dillo Exp $
+# $NetBSD: Makefile,v 1.5 2006/01/13 17:42:33 reed Exp $
 
 WEB_PREFIX?=	${.CURDIR}/../htdocs
 
@@ -24,6 +24,7 @@ SRCS+=	plist.xml
 SRCS+=	pkginstall.xml
 SRCS+=	submit.xml
 SRCS+=	using.xml
+SRCS+=	tools.xml
 
 # entities
 SRCS+=	chapters.ent
diff --git a/doc/guide/files/chapters.ent b/doc/guide/files/chapters.ent
index e270106467f..8900e6d6f95 100644
--- a/doc/guide/files/chapters.ent
+++ b/doc/guide/files/chapters.ent
@@ -1,7 +1,7 @@
 <!--
 	Creates entities for each chapter in the pkgsrc book.
 
-	$NetBSD: chapters.ent,v 1.6 2005/10/17 06:19:31 hubertf Exp $
+	$NetBSD: chapters.ent,v 1.7 2006/01/13 17:42:33 reed Exp $
 -->
 
 <!ENTITY chap.intro			SYSTEM "introduction.xml">
@@ -22,6 +22,7 @@
 <!ENTITY chap.pkginstall		SYSTEM "pkginstall.xml">
 <!ENTITY chap.options			SYSTEM "options.xml">
 <!ENTITY chap.build			SYSTEM "build.xml">
+<!ENTITY chap.tools			SYSTEM "tools.xml">
 <!ENTITY chap.fixes			SYSTEM "fixes.xml">
 <!ENTITY chap.debug			SYSTEM "debug.xml">
 <!ENTITY chap.submit			SYSTEM "submit.xml">
diff --git a/doc/guide/files/pkgsrc.xml b/doc/guide/files/pkgsrc.xml
index 4c363a2266c..1bff11ad75f 100644
--- a/doc/guide/files/pkgsrc.xml
+++ b/doc/guide/files/pkgsrc.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: pkgsrc.xml,v 1.10 2005/10/05 13:59:56 dillo Exp $ -->
+<!-- $NetBSD: pkgsrc.xml,v 1.11 2006/01/13 17:42:33 reed Exp $ -->
 
 
 <?xml version="1.0"?>
@@ -45,7 +45,7 @@
       <holder role="mailto:www@NetBSD.org">The NetBSD Foundation, Inc</holder>
     </copyright>
 
-    <pubdate>$NetBSD: pkgsrc.xml,v 1.10 2005/10/05 13:59:56 dillo Exp $</pubdate>
+    <pubdate>$NetBSD: pkgsrc.xml,v 1.11 2006/01/13 17:42:33 reed Exp $</pubdate>
 
     <abstract>
       <para>Information about using the NetBSD package system (pkgsrc)
@@ -78,6 +78,7 @@
     &chap.pkginstall;
     &chap.options;
     &chap.build;
+    &chap.tools;
     &chap.fixes;
     &chap.debug;
     &chap.submit;
diff --git a/doc/guide/files/tools.xml b/doc/guide/files/tools.xml
new file mode 100644
index 00000000000..7ea0087ae21
--- /dev/null
+++ b/doc/guide/files/tools.xml
@@ -0,0 +1,118 @@
+<!-- $NetBSD: tools.xml,v 1.1 2006/01/13 17:42:33 reed 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>)
+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
+package will not be used.
+</para>
+
+<para>
+When building a package, the replacement tools are
+made available in a directory (as symlinks or wrapper scripts)
+that is early in the executable search path. Just like the buildlink
+system, this helps with consistent builds.
+</para>
+
+<para>
+A tool may be needed to help build a specific package. For example,
+perl, GNU make (gmake) or yacc may be needed.
+</para>
+
+<para>
+Also a tool may be needed, for example, because the native system's supplied
+tool may be inefficient for building a package with pkgsrc.
+For example, a package may need GNU awk, bison (instead of
+yacc) or a better sed.
+</para>
+
+<para>
+The tools used by a package can be listed by running
+<command>make show-tools</command>.
+</para>
+
+<sect1 id="pkgsrc-tools">
+<title>Tools for pkgsrc builds</title>
+
+<para>
+The default set of tools used by pkgsrc is defined in
+<filename>bsd.pkg.mk</filename>. This includes standard Unix tools,
+such as: <command>cat</command>, <command>awk</command>,
+<command>chmod</command>, <command>test</command>, and so on.
+These can be seen by running:
+<command>make show-var VARNAME=USE_TOOLS</command>.
+</para>
+
+<para>
+If a package needs a specific program to build
+then the <varname>USE_TOOLS</varname> variable can be used
+to define the tools needed.
+</para>
+
+</sect1>
+
+<sect1 id="package-tools">
+<title>Tools needed by packages</title>
+
+<para>
+In the following examples, the :pkgsrc means to use the pkgsrc version
+and not the native version for a build dependency.
+And the :run means that it is used for a
+run-time dependencies also (and becomes a DEPENDS).
+The default is a build dependency which can be set with
+:build. (So in this example, it is the same as gmake:build
+and pkg-config:build.)
+</para>
+
+<programlisting>
+USE_TOOLS+=	mktemp:pkgsrc
+USE_TOOLS+=	gmake perl:run pkg-config
+</programlisting>
+
+<para>
+When using the tools framework, a
+<varname>TOOLS_PATH.foo</varname> variable is defined
+which contains the full path to the appropriate tool. For example,
+<varname>TOOLS_PATH.bash</varname> could be <quote>/bin/bash</quote>
+on Linux systems.
+</para>
+
+<para>
+If you always need a pkgsrc version of the
+tool at run-time, then just use <varname>DEPENDS</varname> instead.
+<!-- jlam said: This is not to
+say that we can't extend the tools framework to do that, but it hasn't been
+something that's come up frequently enough to make it worthwhile to do.
+-->
+</para>
+
+</sect1>
+<sect1 id="platform-tools">
+<title>Tools provided by platforms</title>
+
+<para>
+When improving or porting pkgsrc to a new platform, have a look
+at (or create) the corresponding platform specific make file fragment under
+<filename>pkgsrc/mk/tools/tools.${OPSYS}.mk</filename> which defines
+the name of the common tools. For example:
+<programlisting>
+.if exists(/usr/bin/bzcat)
+TOOLS_PLATFORM.bzcat?=          /usr/bin/bzcat
+.elif exists(/usr/bin/bzip2)
+TOOLS_PLATFORM.bzcat?=          /usr/bin/bzip2 -cd
+.endif
+
+TOOLS_PLATFORM.true?=           true                    # shell builtin
+</programlisting>
+
+</sect1>
+
+<!-- todo: also document how to add a new tool -->
+
+</chapter>