pkgsrc-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[pkgsrc/trunk]: pkgsrc/doc/guide/files Added the word "internals" to the titl...
details: https://anonhg.NetBSD.org/pkgsrc/rev/4e38f9092fee
branches: trunk
changeset: 512643:4e38f9092fee
user: rillig <rillig%pkgsrc.org@localhost>
date: Fri May 12 23:03:22 2006 +0000
description:
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.
diffstat:
doc/guide/files/Makefile | 3 +-
doc/guide/files/chapters.ent | 3 +-
doc/guide/files/infr.design.xml | 144 +++++++++++++++++++++++++++++++++++++++
doc/guide/files/introduction.xml | 49 +++++-------
doc/guide/files/pkgsrc.xml | 7 +-
5 files changed, 172 insertions(+), 34 deletions(-)
diffs (284 lines):
diff -r aee9a6a19be9 -r 4e38f9092fee doc/guide/files/Makefile
--- a/doc/guide/files/Makefile Fri May 12 22:57:26 2006 +0000
+++ b/doc/guide/files/Makefile Fri May 12 23:03:22 2006 +0000
@@ -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+= fixes.xml
SRCS+= ftp-layout.xml
SRCS+= getting.xml
+SRCS+= infr.design.xml
SRCS+= introduction.xml
SRCS+= logs.xml
SRCS+= makefile.xml
diff -r aee9a6a19be9 -r 4e38f9092fee doc/guide/files/chapters.ent
--- a/doc/guide/files/chapters.ent Fri May 12 22:57:26 2006 +0000
+++ b/doc/guide/files/chapters.ent Fri May 12 23:03:22 2006 +0000
@@ -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 -r aee9a6a19be9 -r 4e38f9092fee doc/guide/files/infr.design.xml
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/guide/files/infr.design.xml Fri May 12 23:03:22 2006 +0000
@@ -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—after
+ inclusion—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 -r aee9a6a19be9 -r 4e38f9092fee doc/guide/files/introduction.xml
--- a/doc/guide/files/introduction.xml Fri May 12 22:57:26 2006 +0000
+++ b/doc/guide/files/introduction.xml Fri May 12 23:03:22 2006 +0000
@@ -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 available in various formats:</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>
- <itemizedlist>
- <listitem>
- <para><ulink url="index.html">HTML</ulink></para>
- </listitem>
-
- <listitem>
- <para><ulink url="pkgsrc.pdf">PDF</ulink></para>
- </listitem>
+ <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>
- <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 -r aee9a6a19be9 -r 4e38f9092fee doc/guide/files/pkgsrc.xml
--- a/doc/guide/files/pkgsrc.xml Fri May 12 22:57:26 2006 +0000
+++ b/doc/guide/files/pkgsrc.xml Fri May 12 23:03:22 2006 +0000
@@ -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@localhost";>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>
Home |
Main Index |
Thread Index |
Old Index