[pkgsrc/trunk]: pkgsrc/doc/guide/files Documented the use of CONFIGURE_DIRS, ...

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

details:   https://anonhg.NetBSD.org/pkgsrc/rev/3539eea29a5f
branches:  trunk
changeset: 502266:3539eea29a5f
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Thu Nov 03 19:06:50 2005 +0000

description:
Documented the use of CONFIGURE_DIRS, as pkglint has got a new error
diagnostic that need this explanation.

diffstat:

 doc/guide/files/build.xml |  55 ++++++++++++++++++++++++----------------------
 1 files changed, 29 insertions(+), 26 deletions(-)

diffs (74 lines):

diff -r e6680d377f97 -r 3539eea29a5f doc/guide/files/build.xml
--- a/doc/guide/files/build.xml Thu Nov 03 18:49:32 2005 +0000
+++ b/doc/guide/files/build.xml Thu Nov 03 19:06:50 2005 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: build.xml,v 1.14 2005/11/03 18:15:47 rillig Exp $ -->
+<!-- $NetBSD: build.xml,v 1.15 2005/11/03 19:06:50 rillig Exp $ -->
 
 <chapter id="build">
 <title>The build process</title>
@@ -322,36 +322,39 @@
 <sect1 id="build.configure">
 <title>The <emphasis>configure</emphasis> phase</title>
 
-         <para>Most pieces of software need information on the header files,
-           system calls, and library routines which are available in &os;.
-           This is the process known as configuration, and is usually
-           automated.  In most cases, a script is supplied with the source,
-           and its invocation results in generation of header files,
-           Makefiles, etc.</para>
+<para>Most pieces of software need information on the header files,
+system calls, and library routines which are available on the platform
+they run on. The process of determining this information is known as
+configuration, and is usually automated. In most cases, a script is
+supplied with the distfiles, and its invocation results in generation of
+header files, Makefiles, etc.</para>
 
-         <para>If the program's distfile contains its own configure
-           script, this can be invoked by setting
-           <varname>HAS_CONFIGURE</varname>. If the configure script
-           is a GNU autoconf script, <varname>GNU_CONFIGURE</varname>
-           should be specified instead. In either case, any arguments
-           to the configure script can be specified in the
-           <varname>CONFIGURE_ARGS</varname> variable, and the
-           configure script's name can be set in
-           <varname>CONFIGURE_SCRIPT</varname> if it differs from the
-           default <quote>configure</quote>. Here's an example from
-           the <filename role="pkg">sysutils/top</filename> package:</para>
+<para>If the package contains a configure script, this can be invoked by
+setting <varname>HAS_CONFIGURE</varname> to <quote>yes</quote>. If the
+configure script is a GNU autoconf script, you should set
+<varname>GNU_CONFIGURE</varname> to <quote>yes</quote> instead. What
+happens in the <emphasis>configure</emphasis> phase is roughly:</para>
 
 <programlisting>
-    HAS_CONFIGURE=          yes
-    CONFIGURE_SCRIPT=       Configure
-    CONFIGURE_ARGS+=        netbsd13
+    .for d in ${CONFIGURE_DIRS}
+            cd ${WRKSRC} && cd ${d} && env ${CONFIGURE_ENV} \
+                ${CONFIGURE_SCRIPT} ${CONFIGURE_ARGS}
+    .endfor
 </programlisting>
 
-         <para>If the program uses an Imakefile for configuration, the appropriate
-           steps can be invoked by setting <varname>USE_IMAKE</varname> to
-           <quote>YES</quote>. (If you only want the package installed in
-           <varname>$X11PREFIX</varname> but xmkmf not being run, set
-           <varname>USE_X11BASE</varname> instead!)</para>
+<para><varname>CONFIGURE_DIRS</varname> is a list of pathnames relative
+to <varname>WRKSRC</varname>. In each of these directories, the
+configure script is run with the same environment and arguments. The
+variables <varname>CONFIGURE_ENV</varname>,
+<varname>CONFIGURE_SCRIPT</varname> (default:
+<quote>./configure</quote>) and <varname>CONFIGURE_ARGS</varname> may
+all be changed by the package.</para>
+
+<para>If the program uses an <filename>Imakefile</filename> for
+configuration, the appropriate steps can be invoked by setting
+<varname>USE_IMAKE</varname> to <quote>yes</quote>. (If you only want
+the package installed in <varname>${X11PREFIX}</varname> but xmkmf not
+being run, set <varname>USE_X11BASE</varname> instead.)</para>
 
 </sect1>