[pkgsrc/trunk]: pkgsrc/doc/guide/files Add a "tools" chapter. Documents the U...

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

details:   https://anonhg.NetBSD.org/pkgsrc/rev/9f05642f7c36
branches:  trunk
changeset: 506262:9f05642f7c36
user:      reed <reed%pkgsrc.org@localhost>
date:      Fri Jan 13 17:42:33 2006 +0000

description:
Add a "tools" chapter. Documents the USE_TOOLS.

diffstat:

 doc/guide/files/Makefile     |    3 +-
 doc/guide/files/chapters.ent |    3 +-
 doc/guide/files/pkgsrc.xml   |    5 +-
 doc/guide/files/tools.xml    |  118 +++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 125 insertions(+), 4 deletions(-)

diffs (185 lines):

diff -r 1f4833264705 -r 9f05642f7c36 doc/guide/files/Makefile
--- a/doc/guide/files/Makefile  Fri Jan 13 17:40:43 2006 +0000
+++ b/doc/guide/files/Makefile  Fri Jan 13 17:42:33 2006 +0000
@@ -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+= pkginstall.xml
 SRCS+= submit.xml
 SRCS+= using.xml
+SRCS+= tools.xml
 
 # entities
 SRCS+= chapters.ent
diff -r 1f4833264705 -r 9f05642f7c36 doc/guide/files/chapters.ent
--- a/doc/guide/files/chapters.ent      Fri Jan 13 17:40:43 2006 +0000
+++ b/doc/guide/files/chapters.ent      Fri Jan 13 17:42:33 2006 +0000
@@ -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 -r 1f4833264705 -r 9f05642f7c36 doc/guide/files/pkgsrc.xml
--- a/doc/guide/files/pkgsrc.xml        Fri Jan 13 17:40:43 2006 +0000
+++ b/doc/guide/files/pkgsrc.xml        Fri Jan 13 17:42:33 2006 +0000
@@ -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@localhost";>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 -r 1f4833264705 -r 9f05642f7c36 doc/guide/files/tools.xml
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/guide/files/tools.xml Fri Jan 13 17:42:33 2006 +0000
@@ -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>