pkgsrc-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[pkgsrc/trunk]: pkgsrc/doc/guide/files Add a "tools" chapter. Documents the U...
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>
Home |
Main Index |
Thread Index |
Old Index