Added the word "internals" to the title of part III. Added a chapter

with general design guidelines. Fixed the statement that there are only
two parts.

5 files changed, 173 insertions, 35 deletions

diff --git a/doc/guide/files/Makefile b/doc/guide/files/Makefile
index fc244285836..1aa3189e6ae 100644
--- a/doc/guide/files/Makefile
+++ b/doc/guide/files/Makefile
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.6 2006/05/10 20:56:00 rillig Exp $
+# $NetBSD: Makefile,v 1.7 2006/05/12 23:03:22 rillig Exp $
 
 WEB_PREFIX?=	${.CURDIR}/../htdocs
 
@@ -18,6 +18,7 @@ SRCS+=	faq.xml
 SRCS+=	fixes.xml
 SRCS+=	ftp-layout.xml
 SRCS+=	getting.xml
+SRCS+=	infr.design.xml
 SRCS+=	introduction.xml
 SRCS+=	logs.xml
 SRCS+=	makefile.xml
diff --git a/doc/guide/files/chapters.ent b/doc/guide/files/chapters.ent
index 43472607b53..6a9c76a0b15 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.10 2006/05/10 20:56:00 rillig Exp $
+	$NetBSD: chapters.ent,v 1.11 2006/05/12 23:03:22 rillig Exp $
 -->
 
 <!ENTITY chap.intro			SYSTEM "introduction.xml">
@@ -29,6 +29,7 @@
 <!ENTITY chap.devfaq			SYSTEM "devfaq.xml">
 
 <!-- The pkgsrc infrastructure -->
+<!ENTITY chap.infr.design		SYSTEM "infr.design.xml">
 <!ENTITY chap.regression		SYSTEM "regression.xml">
 <!ENTITY chap.porting			SYSTEM "porting.xml">
 
diff --git a/doc/guide/files/infr.design.xml b/doc/guide/files/infr.design.xml
new file mode 100644
index 00000000000..0ff861ea90c
--- /dev/null
+++ b/doc/guide/files/infr.design.xml
@@ -0,0 +1,144 @@
+<!-- $NetBSD: infr.design.xml,v 1.1 2006/05/12 23:03:22 rillig Exp $ -->
+
+<chapter id="infr.design"> <?dbhtml filename="infr.design.html"?>
+<title>Design of the pkgsrc infrastructure</title>
+
+	<para>The pkgsrc infrastructure consists of many small Makefile
+	fragments. Each such fragment needs a properly specified
+	interface. This chapter explains how such an interface looks
+	like.</para>
+
+<!--
+<sect1 id="infr.intro">
+<title>Introduction</title>
+
+</sect1>
+-->
+
+<sect1 id="infr.var">
+<title>Variable evaluation</title>
+
+<sect2 id="infr.var.load">
+<title>At load time</title>
+
+	<para>Variable evaluation takes place either at load time or at
+	runtime, depending on the context in which they occur. The
+	contexts where variables are evaluated at load time are:</para>
+
+	<itemizedlist>
+
+	<listitem><para>The right hand side of the <literal>:=</literal>
+	and <literal>!=</literal> operators,</para></listitem>
+
+	<listitem><para>Make directives like <literal>.if</literal> or
+	<literal>.for</literal>,</para></listitem>
+
+	<listitem><para>Dependency lines.</para></listitem>
+
+	</itemizedlist>
+
+	<para>A special exception are references to the iteration
+	variables of <literal>.for</literal> loops, which are expanded
+	inline, no matter in which context they appear.</para>
+
+	<para>As the values of variables may change during load time,
+	care must be taken not to evaluate them by accident. Typical
+	examples for variables that should not be evaluated at load time
+	are <varname>DEPENDS</varname> and
+	<varname>CONFIGURE_ARGS</varname>. To make the effect more
+	clear, here is an example:</para>
+
+	<programlisting>
+    CONFIGURE_ARGS=         # none
+    CFLAGS=                 -O
+    CONFIGURE_ARGS+=        CFLAGS=${CFLAGS:Q}
+
+    CONFIGURE_ARGS:=        ${CONFIGURE_ARGS}
+
+    CFLAGS+=                -Wall
+	</programlisting>
+
+	<para>This code shows how the use of the <literal>:=</literal>
+	operator can quickly lead to unexpected results. The first
+	paragraph is fairly common code. The second paragraph evaluates
+	the <varname>CONFIGURE_ARGS</varname> variable, which results in
+	<literal>CFLAGS=-O</literal>. In the third paragraph, the
+	<literal>-Wall</literal> is appended to the
+	<varname>CFLAGS</varname>, but this addition will not appear in
+	<varname>CONFIGURE_ARGS</varname>. In actual code, the three
+	paragraphs from above typically occur in completely unrelated
+	files.</para>
+
+</sect2>
+<sect2 id="infr.var.run">
+<title>At runtime</title>
+
+	<para>After all the files have been loaded, the values of the
+	variables cannot be changed anymore. Variables that are used in
+	the shell commands are expanded at this point.</para>
+
+</sect2>
+</sect1>
+
+<sect1 id="infr.design.intf">
+<title>Designing interfaces for Makefile fragments</title>
+
+	<para>Most of the <filename>.mk</filename> files fall into one
+	of the following classes. Cases where a file falls into more
+	than one class should be avoided as it often leads to subtle
+	bugs.</para>
+
+<sect2 id="infr.design.intf.proc">
+<title>Procedures with parameters</title>
+
+	<para>In a traditional imperative programming language some of
+	the <filename>.mk</filename> files could be described as
+	procedures. They take some input parameters and&mdash;after
+	inclusion&mdash;provide a result in output parameters. Since all
+	variables in <filename>Makefile</filename>s have global scope
+	care must be taken not to use parameter names that have already
+	another meaning. For example, <varname>PKGNAME</varname> is a
+	bad choice for a parameter name.</para>
+
+	<para>Procedures are completely evaluated at preprocessing time.
+	That is, when calling a procedure all input parameters must be
+	completely resolvable. For example,
+	<varname>CONFIGURE_ARGS</varname> should never be an input
+	parameter since it is very likely that further text will be
+	added after calling the procedure, which would effectively apply
+	the procedure to only a part of the variable. Also, references
+	to other variables wit will be modified after calling the
+	procedure.</para>
+
+	<para>A procedure can declare its output parameters either as
+	suitable for use in preprocessing directives or as only
+	available at runtime. The latter alternative is for variables
+	that contain references to other runtime variables.</para>
+
+	<para>Procedures shall be written such that it is possible to
+	call the procedure more than once. That is, the file must not
+	contain multiple-inclusion guards.</para>
+
+	<para>Examples for procedures are
+	<filename>mk/bsd.options.mk</filename> and
+	<filename>mk/buildlink3/bsd.builtin.mk</filename>. To express
+	that the parameters are evaluated at load time, they should be
+	assigned using the <literal>:=</literal> operator, which should
+	be used only for this purpose.</para>
+
+</sect2>
+<sect2 id="infr.design.intf.action">
+<title>Actions taken on behalf of parameters</title>
+
+	<para>Action files take some input parameters and may define
+	runtime variables. They shall not define loadtime variables.
+	There are action files that are included implicitly by the
+	pkgsrc infrastructure, while other must be included
+	explicitly.</para>
+
+	<para>An example for action files is
+	<filename>mk/subst.mk</filename>.</para>
+
+</sect2>
+</sect1>
+</chapter>
diff --git a/doc/guide/files/introduction.xml b/doc/guide/files/introduction.xml
index 5cfd26bd414..da2797b796f 100644
--- a/doc/guide/files/introduction.xml
+++ b/doc/guide/files/introduction.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: introduction.xml,v 1.10 2006/03/01 00:04:30 reed Exp $ -->
+<!-- $NetBSD: introduction.xml,v 1.11 2006/05/12 23:03:22 rillig Exp $ -->
 
 <chapter id="introduction">
   <title>What is pkgsrc?</title>
@@ -105,36 +105,27 @@
   <sect1 id="overview">
     <title>Overview</title>
 
-    <para>This document is divided into two parts.  The first,
-      <link linkend="users-guide" endterm="users-guide.title"/>,
-      describes how one can use one of the packages in the Package
-      Collection, either by installing a precompiled binary package, or
-      by building one's own copy using the &os; package system.  The
-      second part,
-      <link linkend="developers-guide" endterm="developers-guide.title"/>,
-      explains how to prepare
-      a package so it can be easily built by other &os; users without
-      knowing about the package's building details.</para>
+	<para>This document is divided into three parts. The first,
+	<link linkend="users-guide" endterm="users-guide.title"/>,
+	describes how one can use one of the packages in the Package
+	Collection, either by installing a precompiled binary package,
+	or by building one's own copy using the &os; package system. 
+	The second part, <link linkend="developers-guide"
+	endterm="developers-guide.title"/>, explains how to prepare a
+	package so it can be easily built by other &os; users without
+	knowing about the package's building details. The third part,
+	<link linkend="infrastructure" endterm="infrastructure.title"/>
+	is intended for those who want to understand how pkgsrc is
+	implemented.</para>
+
+	<para>This document is available in various formats:
+	<simplelist type="inline">
+	<member><ulink url="index.html">HTML</ulink></member>
+	<member><ulink url="pkgsrc.pdf">PDF</ulink></member>
+	<member><ulink url="pkgsrc.ps">PS</ulink></member>
+	<member><ulink url="pkgsrc.txt">TXT</ulink></member>
+	</simplelist>.</para>
 
-    <para>This document is available in various formats:</para>
-
-    <itemizedlist>
-      <listitem>
-	<para><ulink url="index.html">HTML</ulink></para>
-      </listitem>
-
-      <listitem>
-	<para><ulink url="pkgsrc.pdf">PDF</ulink></para>
-      </listitem>
-
-      <listitem>
-	<para><ulink url="pkgsrc.ps">PS</ulink></para>
-      </listitem>
-
-      <listitem>
-	<para><ulink url="pkgsrc.txt">TXT</ulink></para>
-      </listitem>
-    </itemizedlist>
   </sect1>
 
   <sect1 id="terminology">
diff --git a/doc/guide/files/pkgsrc.xml b/doc/guide/files/pkgsrc.xml
index bdebe4047d6..331a8067eee 100644
--- a/doc/guide/files/pkgsrc.xml
+++ b/doc/guide/files/pkgsrc.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: pkgsrc.xml,v 1.15 2006/05/10 22:42:30 rillig Exp $ -->
+<!-- $NetBSD: pkgsrc.xml,v 1.16 2006/05/12 23:03:22 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.15 2006/05/10 22:42:30 rillig Exp $</pubdate>
+    <pubdate>$NetBSD: pkgsrc.xml,v 1.16 2006/05/12 23:03:22 rillig Exp $</pubdate>
 
     <abstract>
       <para>Information about using the NetBSD package system (pkgsrc)
@@ -87,13 +87,14 @@
 
   <!-- The pkgsrc infrastructure -->
   <part id="infrastructure"><?dbhtml filename="infrastructure.html"?>
-    <title>The pkgsrc infrastructure internals</title>
+    <title id="infrastructure.title">The pkgsrc infrastructure internals</title>
 
 	<partintro><para>This part of the guide deals with everything
 	from the infrastructure that is behind the interfaces described
 	in the developer's guide. A casual package maintainer should not
 	need anything from this part.</para></partintro>
 
+    &chap.infr.design;
     &chap.regression;
     &chap.porting;
   </part>