Added part III, which is about the pkgsrc infrastructure. It currently

contains the chapter about porting pkgsrc to new platforms (formerly in
part II) and a new chapter on regression tests.

5 files changed, 136 insertions, 10 deletions

diff --git a/doc/guide/files/Makefile b/doc/guide/files/Makefile
index 262e9669905..fc244285836 100644
--- a/doc/guide/files/Makefile
+++ b/doc/guide/files/Makefile
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.5 2006/01/13 17:42:33 reed Exp $
+# $NetBSD: Makefile,v 1.6 2006/05/10 20:56:00 rillig Exp $
 
 WEB_PREFIX?=	${.CURDIR}/../htdocs
 
@@ -11,6 +11,8 @@ SRCS+=	buildlink.xml
 SRCS+=	components.xml
 SRCS+=	configuring.xml
 SRCS+=	debug.xml
+SRCS+=	devfaq.xml
+SRCS+=	editing.xml
 SRCS+=	examples.xml
 SRCS+=	faq.xml
 SRCS+=	fixes.xml
@@ -18,13 +20,16 @@ SRCS+=	ftp-layout.xml
 SRCS+=	getting.xml
 SRCS+=	introduction.xml
 SRCS+=	logs.xml
+SRCS+=	makefile.xml
 SRCS+=	options.xml
+SRCS+=	pkginstall.xml
 SRCS+=	platforms.xml
 SRCS+=	plist.xml
-SRCS+=	pkginstall.xml
+SRCS+=	porting.xml
+SRCS+=	regression.xml
 SRCS+=	submit.xml
-SRCS+=	using.xml
 SRCS+=	tools.xml
+SRCS+=	using.xml
 
 # entities
 SRCS+=	chapters.ent
diff --git a/doc/guide/files/chapters.ent b/doc/guide/files/chapters.ent
index 69aa434dd00..43472607b53 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.9 2006/05/10 13:58:34 rillig Exp $
+	$NetBSD: chapters.ent,v 1.10 2006/05/10 20:56:00 rillig Exp $
 -->
 
 <!ENTITY chap.intro			SYSTEM "introduction.xml">
@@ -26,9 +26,12 @@
 <!ENTITY chap.fixes			SYSTEM "fixes.xml">
 <!ENTITY chap.debug			SYSTEM "debug.xml">
 <!ENTITY chap.submit			SYSTEM "submit.xml">
-<!ENTITY chap.porting			SYSTEM "porting.xml">
 <!ENTITY chap.devfaq			SYSTEM "devfaq.xml">
 
+<!-- The pkgsrc infrastructure -->
+<!ENTITY chap.regression		SYSTEM "regression.xml">
+<!ENTITY chap.porting			SYSTEM "porting.xml">
+
 <!-- appendix -->
 <!ENTITY chap.examples			SYSTEM "examples.xml">
 <!ENTITY chap.logs			SYSTEM "logs.xml">
diff --git a/doc/guide/files/pkgsrc.xml b/doc/guide/files/pkgsrc.xml
index cac49ca5d78..5330bf59ed6 100644
--- a/doc/guide/files/pkgsrc.xml
+++ b/doc/guide/files/pkgsrc.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: pkgsrc.xml,v 1.13 2006/05/10 13:58:34 rillig Exp $ -->
+<!-- $NetBSD: pkgsrc.xml,v 1.14 2006/05/10 20:56:00 rillig 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.13 2006/05/10 13:58:34 rillig Exp $</pubdate>
+    <pubdate>$NetBSD: pkgsrc.xml,v 1.14 2006/05/10 20:56:00 rillig Exp $</pubdate>
 
     <abstract>
       <para>Information about using the NetBSD package system (pkgsrc)
@@ -82,10 +82,17 @@
     &chap.fixes;
     &chap.debug;
     &chap.submit;
-    &chap.porting;
     &chap.devfaq;
   </part>
 
+  <!-- The pkgsrc infrastructure -->
+  <part id="infrastructure"><?dbhtml filename="infrastructure.html"?>
+    <title>The pkgsrc infrastructure</title>
+
+    &chap.regression;
+    &chap.porting;
+  </part>
+
   <!-- appendix -->
   &chap.examples;
   &chap.logs;
diff --git a/doc/guide/files/porting.xml b/doc/guide/files/porting.xml
index 80f501a98f5..2f3ae3ccfeb 100644
--- a/doc/guide/files/porting.xml
+++ b/doc/guide/files/porting.xml
@@ -1,6 +1,6 @@
-<!-- $NetBSD: porting.xml,v 1.1 2006/02/18 01:46:43 rillig Exp $ -->
+<!-- $NetBSD: porting.xml,v 1.2 2006/05/10 20:56:00 rillig Exp $ -->
 
-<chapter id="porting">
+<chapter id="porting"> <?dbhtml filename="porting.html"?>
 <title>Porting pkgsrc</title>
 
 	<para>The pkgsrc system has already been ported to many
diff --git a/doc/guide/files/regression.xml b/doc/guide/files/regression.xml
new file mode 100644
index 00000000000..48a9b35f0ef
--- /dev/null
+++ b/doc/guide/files/regression.xml
@@ -0,0 +1,111 @@
+<!-- $NetBSD: regression.xml,v 1.1 2006/05/10 20:56:00 rillig Exp $ -->
+
+<chapter id="regression"> <?dbhtml filename="regression.html"?>
+<title>Regression tests</title>
+
+	<para>The pkgsrc infrastructure consists of a large codebase,
+	and there are many corners where every little bit of a file is
+	well thought out, making pkgsrc likely to fail as soon as
+	anything is changed near those parts. To prevent most changes
+	from breaking anything, a suite of regression tests should go
+	along with every important part of the pkgsrc infrastructure.
+	This chapter describes how regression tests work in pkgsrc and
+	how you can add new tests.</para>
+
+<sect1 id="regression.descr">
+<title>The regression tests framework</title>
+
+<para></para>
+
+</sect1>
+
+<sect1 id="regression.run">
+<title>Running the regression tests</title>
+
+	<para>You first need to install the <filename
+	role="pkg">pkgtools/pkg_regress</filename> package, which
+	provides the <command>pkg_regress</command> command. Then you
+	can simply run that command, which will run all tests in the
+	<filename>regress</filename> category.</para>
+
+</sect1>
+
+<sect1 id="regression.new">
+<title>Adding a new regression test</title>
+
+	<para>Every directory in the <filename>regress</filename>
+	category that contains a file called <filename>spec</filename>
+	is considered a regression test. This file is a shell program
+	that is included by the <command>pkg_regress</command> command.
+	The following functions can be overridden to suit your
+	needs.</para>
+
+<sect2 id="regression.fun.override">
+<title>Overridable functions</title>
+
+	<para>These functions do not take any parameters. They are all
+	called in <quote>set -e</quote> mode, so you should be careful
+	to check the exitcodes of any commands you run in the
+	test.</para>
+
+	<variablelist>
+
+	<varlistentry><term><varname>do_setup()</varname></term>
+	<listitem><para>This function prepares the environment for the
+	test. By default it does nothing.</para></listitem>
+	</varlistentry>
+
+	<varlistentry><term><varname>do_test()</varname></term>
+	<listitem><para>This function runs the actual test. By default,
+	it calls <varname>TEST_MAKE</varname> with the arguments
+	<varname>MAKEARGS_TEST</varname> and writes its output including
+	error messages into the file
+	<varname>TEST_OUTFILE</varname>.</para></listitem>
+	</varlistentry>
+
+	<varlistentry><term><varname>check_result()</varname></term>
+	<listitem><para>This function is run after the test and is
+	typically used to compare the actual output from the one that is
+	expected. It can make use of the various helper functions from
+	the next section.</para></listitem>
+	</varlistentry>
+	
+	<varlistentry><term><varname>do_cleanup()</varname></term>
+	<listitem><para>This function cleans everything up after the
+	test has been run. By default it does nothing.</para></listitem>
+	</varlistentry>
+
+	</variablelist>
+</sect2>
+
+<sect2 id="regression.fun.helper">
+<title>Helper functions</title>
+
+<variablelist>
+
+	<varlistentry><term><varname>exit_status(expected)</varname></term>
+	<listitem><para>This function compares the exitcode of the
+	<command>do_test()</command> function with its first parameter.
+	If they differ, the test will fail.</para></listitem>
+	</varlistentry>
+
+	<varlistentry><term><varname>output_require(regex...)</varname></term>
+	<listitem><para>This function checks for each of its parameters
+	if the output from <command>do_test()</command> matches the
+	extended regular expression. If it does not, the test will
+	fail.</para></listitem>
+	</varlistentry>
+
+	<varlistentry><term><varname>output_prohibit(regex...)</varname></term>
+	<listitem><para>This function checks for each of its parameters
+	if the output from <command>do_test()</command> does
+	<emphasis>not</emphasis> match the extended regular expression.
+	If any of the regular expressions matches, the test will
+	fail.</para></listitem>
+	</varlistentry>
+
+	</variablelist>
+
+</sect2>
+</sect1>
+</chapter>