Mercurial > hg > xemacs-beta

changeset 2647:89e2f8e3f660

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[xemacs-hg @ 2005-03-10 11:44:17 by malcolmp] Autoconf 2.5 documentation updates.
author malcolmp
date Thu, 10 Mar 2005 11:44:22 +0000
parents 5e4893b16f7c
children 68a5da07c189
files man/ChangeLog man/beta.texi man/internals/internals.texi
diffstat 3 files changed, 190 insertions(+), 134 deletions(-) [+]
line wrap: on
line diff
--- a/man/ChangeLog	Thu Mar 10 09:19:16 2005 +0000
+++ b/man/ChangeLog	Thu Mar 10 11:44:22 2005 +0000
@@ -1,3 +1,10 @@
+2005-03-05  Malcolm Purvis  <malcolmp@xemacs.org>
+
+	* beta.texi : Change configure arguments to the new autoconf 2.5
+	style configure.
+	* internals/internals.texi (The Build Configuration System):  Fill
+	out the details.
+
 2005-01-19  Aidan Kehoe  <kehoea@parhasard.net>
 
 	* lispref/mule.texi (CCL Example): Detail an implementation of the
--- a/man/beta.texi	Thu Mar 10 09:19:16 2005 +0000
+++ b/man/beta.texi	Thu Mar 10 11:44:22 2005 +0000
@@ -377,10 +377,9 @@
 It's a good idea to use
 
 @example
---extra-verbose
---debug
---memory-usage-stats
---error-checking=all
+--enable-debug
+--enable-memory-usage-stats
+--enable-error-checking=all
 @end example
 
 These turn on extra debugging info and checks.  The last one in particular
@@ -392,10 +391,10 @@
 You should also strongly consider
 
 @example
---with-mule
---use-pkcc
---pdump
---with-clash-detection
+--enable-mule
+--enable-kkcc
+--enable-pdump
+--enable-clash-detection
 --with-wmcommand
 --with-xfs
 @end example
@@ -406,8 +405,8 @@
 If you have gcc, consider using
 
 @example
---compiler=gcc
---xemacs-compiler=g++
+--with-compiler=gcc
+--with-xemacs-compiler=g++
 @end example
 
 This will compile XEmacs using g++, which will turn on a lot of additional
@@ -418,7 +417,7 @@
 line like
 
 @example
---package-path=~/.xemacs::/xemacs/site-packages:/xemacs/xemacs-packages:/xemacs/mule-packages
+--with-package-path=~/.xemacs::/xemacs/site-packages:/xemacs/xemacs-packages:/xemacs/mule-packages
 @end example
 
 @item
@@ -435,12 +434,12 @@
 populate your build directory.
 
 @item
-Use --site-prefixes (or --site-includes and --site-libraries) if you have
-some packages that XEmacs can compile with that are located in an unusual
-place.  For example:
+Use --with-site-prefixes (or --with-site-includes and
+---with-site-libraries) if you have some packages that XEmacs can
+compile with that are located in an unusual place.  For example:
 
 @example
---site-prefixes=/usr/local/pgsql:/usr/local/BerkeleyDB.4.1
+--with-site-prefixes=/usr/local/pgsql:/usr/local/BerkeleyDB.4.1
 @end example
 
 @item
@@ -455,33 +454,41 @@
 the command @kbd{M-x describe-installation RET}).
 
 @example
-uname -a: Linux eicq 2.4.20 #1 Wed Dec 18 02:14:29 EST 2002 i586 unknown
+uname -a: Darwin laptop.local 7.7.0 Darwin Kernel Version 7.7.0: Sun Nov  7 16:06:51 PST 2004; root:xnu/xnu-517.9.5.obj~1/RELEASE_PPC  Power Macintosh powerpc
 
-./configure  '--extra-verbose' '--site-prefixes=/usr/local/pgsql:/usr/local/BerkeleyDB.4.1' '--dynamic=yes' '--with-gtk=no' '--with-gnome=no' '--with-toolbars' '--with-wmcommand' '--with-athena=next' '--with-menubars=lucid' '--with-scrollbars=athena' '--with-dialogs=athena' '--with-widgets=athena' '--with-gif' '--with-sound=native,noesd' '--with-site-lisp=no' '--with-site-modules' '--pdump' '--with-mule' '--with-xfs' '--debug' '--error-checking=all' '--memory-usage-stats' '--use-kkcc' '--with-clash-detection'
-
-
-XEmacs 21.5-b10 "burdock" (+CVS-20030131) configured for `i586-pc-linux'.
+./configure '--with-site-prefixes=/sw' '--without-ldap' '--with-dynamic=yes' '--with-gtk=no' '--with-gnome=no' '--enable-toolbars' '--with-wmcommand' '--with-athena=3d' '--enable-menubars=lucid' '--enable-scrollbars=athena' '--enable-dialogs=athena' '--enable-widgets=athena' '--with-gif' '--enable-sound=native,noesd' '--with-site-lisp=no' '--with-site-modules' '--enable-pdump' '--enable-mule' '--with-xfs' '--enable-debug' '--enable-error-checking=all' '--enable-memory-usage-stats' '--enable-kkcc' '--enable-clash-detection'
 
 
-Compilation / Installation:
+XEmacs 21.5-b19 "chives" (+CVS-20050226) configured for `powerpc-apple-darwin7.7.0'.
+
+  WARNING: --------------------------------------------------------------
+  WARNING: This was produced from a new autoconf-2.5 based configuration.
+  WARNING: If this configuration seems buggy then copy etc/configure-2.13
+  WARNING: to configure and try again.  Also please report the bug.
+  WARNING: --------------------------------------------------------------
+
+Compilation Environment and Installation Defaults:
   Source code location:              /usr/local/src/xemacs
   Installation prefix:               /usr/local
-  Additional prefixes:               /usr/local/pgsql /usr/local/BerkeleyDB.4.1
-  Operating system description file: `s/linux.h'
-  Machine description file:          `m/intel386.h'
-  Compiler:                          gcc -Wall -Wno-switch -Winline -Wmissing-prototypes -Wsign-compare -Wundef -Wstrict-prototypes -Wshadow -Wmissing-declarations -O1 -ggdb3 -Wall -Wchar-subscripts -Wunused -Wundef -Wshadow -Wsign-compare -Wmissing-declarations -march=k6
+  Additional prefixes:               /sw
+  Operating system description file: `s/darwin.h'
+  Machine description file:          `m/powerpc.h'
+  Compiler version:                  gcc (GCC) 3.3 20030304 (Apple Computer, Inc. build 1671)
+    - GCC specs file:                /usr/libexec/gcc/darwin/ppc/3.3/specs
+    - Compiler command:              gcc -Wall -Wno-switch -Wundef -Wsign-compare -Wno-char-subscripts -Wpacked -Wpointer-arith -Wunused-parameter -g  
+  libc version:                      
   Relocating allocator for buffers:  no
-  GNU version of malloc:             yes
-    - Using Doug Lea's new malloc from the GNU C Library.
+  GNU version of malloc:             no
+    - The GNU allocators don't work with this system configuration.
 
 Window System:
   Compiling in support for the X window system:
-    - X Windows headers location:                 /usr/X11/include
-    - X Windows libraries location:               /usr/X11/lib
+    - X Windows headers location:                 /usr/X11R6/include
+    - X Windows libraries location:               /usr/X11R6/lib
     - Handling WM_COMMAND properly.
   Compiling in support for the Athena widget set:
-    - Athena headers location:                    X11/neXtaw
-    - Athena library to link:                     neXtaw
+    - Athena headers location:                    X11/Xaw3d
+    - Athena library to link:                     Xaw3d
   Using Lucid menubars.
   Using Athena scrollbars.
   Using Athena dialog boxes.
@@ -489,7 +496,6 @@
 
 TTY:
   Compiling in support for ncurses.
-  Compiling in support for GPM (General Purpose Mouse).
 
 Images:
   Compiling in support for GIF  images (builtin).
@@ -500,12 +506,12 @@
   Compiling in support for X-Face message headers.
 
 Sound:
-  Compiling in support for sound (native).
 
 Databases:
   Compiling in support for Berkeley database.
+  Compiling in support for GNU DBM.
   Compiling in support for PostgreSQL.
-    - Using PostgreSQL header file:  libpq-fe.h
+    - Using PostgreSQL header file:  postgresql/libpq-fe.h
     - Using PostgreSQL V7 bindings.
 
 Internationalization:
@@ -515,7 +521,7 @@
     - Using XFontSet to provide bilingual menubar.
 
 Mail:
-  Compiling in support for "dot-locking" mail spool file locking method.
+  Compiling in support for "file" mail spool file locking method.
 
 Other Features:
   Inhibiting IPv6 canonicalization at startup.
@@ -523,10 +529,11 @@
   Using the new GC algorithms.
   Using the new portable dumper.
   Compiling in support for extra debugging code.
-  WARNING:   WARNING: Compiling in support for runtime error checking.
+  Compiling in support for runtime error checking.
+  WARNING: ---------------------------------------------------------
   WARNING: XEmacs will run noticeably more slowly as a result.
   WARNING: Error checking is on by default for XEmacs beta releases.
-  WARNING: 
+  WARNING: ---------------------------------------------------------
 @end example
 @end enumerate
 
--- a/man/internals/internals.texi	Thu Mar 10 09:19:16 2005 +0000
+++ b/man/internals/internals.texi	Thu Mar 10 11:44:22 2005 +0000
@@ -4159,11 +4159,10 @@
 @cindex build configuration
 @cindex configuration, build
 
-@strong{Please write this node!} @c ####
-
-This node should describe XEmacs-specific techniques and idioms in the
-configuration system.  A particular example is the set of @samp{XE_}
-macros in @file{configure.in} and @file{configure.ac}.
+XEmacs makes extensive use of the external features provided by the
+system it is running on.  Determining which features are present and
+where they are located is the responsibility of the build configuration
+system.
 
 @menu
 * The version.sh Script::
@@ -4271,11 +4270,17 @@
 @cindex configurable features, adding
 @cindex features, adding configurable
 
-Adding a configurable feature requires at least adding an option to the
-@file{configure} script and a macro definition to @file{src/config.h.in}
-(@pxref{The configure Script}), and often changes to Makefile precursors
-(@pxref{The Makefile Precursors}).
-
+Adding a configurable feature requires at the very least adding an
+option to the @file{configure} script and a macro definition to
+@file{src/config.h.in} (@pxref{The configure Script}), and often changes
+to Makefile precursors (@pxref{The Makefile Precursors}).
+
+Be prepared for the feature to be absent (even if you think that is
+always present for a particular OS release) and work with
+@code{--with-site-prefixes} to handle libraries and headers that are in
+unusual locations.  There is no end to the strange ways in which systems
+can be configured and XEmacs is expected to cope with anything thrown at
+it.
 
 
 @node The configure Script, The Makefile Precursors, Adding Configurable Features, The Build Configuration System
@@ -4286,26 +4291,37 @@
 At the heart of the XEmacs build configuration system is the
 @file{configure} script.  This beast is maintained using the Autoconf
 system, which is a truly terrifying monstrosity based on a fundamentally
-flawed programming model (extensive use of macros), with an
-implementation about which I've never heard a nice word (GNU @file{m4}),
-used to string together a large set of @emph{ad hoc} tests, to implement
-a configuration language with conventions that are unimportant in simple
-cases and counterintuitive when things get complicated.  If that doesn't
-scare you off, Welcome! I think you're ready to become a configure
-hacker!  (But be prepared for things to go downhill from here.)
+flawed programming model (extensive use of macros), with an unpleasant
+implementation (GNU @file{m4}), used to string together a large set of
+@emph{ad hoc} tests, to implement a configuration language with
+conventions that are unimportant in simple cases and counterintuitive
+when things get complicated.  If that doesn't scare you off, Welcome! I
+think you're ready to become a configure hacker!  (But be prepared for
+things to go downhill from here.)
+
+Unless you plan to develop autoconf macros, much of this complexity can
+be removed by following the following rule:
+
+@quotation
+Always quote (ie surround with @samp{[]}) every argument to every
+macro.  This includes macros that appear in the argument list of other
+macros.
+@end quotation
+
+If this rule is followed and the macro produces incorrect results then
+the macro is buggy.
 
 @file{configure} is, of course, is written in POSIX shell language, and
-autogenerated from a precursor (see? the first step was a doozy!)
-Currently that precursor is called @file{configure.ac}, but in the
-previous generation it was called @file{configure.in}.  As of February
-2005, @file{configure.ac} is used in the development mainline, but
-because the semantics of many predefined macros changed drastically
-between @file{autoconf} 2.13 and @file{autoconf} 2.50 (why not ``3.0''? 
-you got me), the XEmacs Project chose to stick with the devil it knew
-for the stable line of XEmacs 21.4 releases.
-
-One reason for worrying about the semantic changes is the fact that
-XEmacs uses a lot of homebrew code, including @file{m4} macros, to
+autogenerated from a precursor.  As of March 2005 on the mainline the
+precursor is called @file{configure.ac} and it is built using
+@code{autoconf} 2.59.  Prior to that, and with XEmacs 21.4 and earlier
+it was called @file{configure.in} and build using @code{autoconf} 2.13.
+@code{autoconf} 2.5X is not completely backward compatible with
+@code{autoconf} 2.13 so the XEmacs Project chose to stick with the devil
+it knew for the stable line of XEmacs 21.4 releases.
+
+One reason for worrying about the level of compatibility is the fact
+that XEmacs uses a lot of homebrew code, including @file{m4} macros, to
 implement special features in its @file{configure} script.  Here are
 some of the important features:
 
@@ -4326,85 +4342,116 @@
 @c #### @var{}-ize the formal parameters of these functions?
 @table @code
 @item USAGE_ERROR(string)
-prints a usage error and dies
+Prints a usage error and dies.
 
 @item PRINT_VAR(var var ...)
-prints values of shell variables
-
-@item XE_ADD_OBJS(foo.o ...)
-@strong{#### Please document me!}
+Prints the name and value of the list of shell variables.
+
+@item XE_ADD_OBJS(foo.o)
+Appends the argument to the variable @code{extra_objs}.  This variable
+goes to make up part of the link command line.  If the command line
+argument @code{--verbose} is supplied a message is printed out.
 
 @item XE_APPEND(value, varname)
-@strong{#### Please document me!}
+Append the value (separated by a space) to the shell variable
+@var{varname}.  @var{varname} should not be prefixed with a @samp{$}.
+If the command line argument @code{--verbose} is supplied a message is
+printed out.
 
 @item XE_PREPEND(value, varname)
-@strong{#### Please document me!}
+Prepend the value (separated by a space) to the shell variable
+@var{varname}.  @var{varname} should not be prefixed with a @samp{$}.
+If the command line argument @code{--verbose} is supplied a message is
+printed out.
 
 @item XE_DIE(message)
-used for situations that can't lead to a successful build, such as
+Used for situations that can't lead to a successful build, such as
 missing include files or conflicts between requested features.
 
 @item XE_CHECK_FEATURE_DEPENDENCY(feature1, feature2)
-@strong{#### Please document me!}
+@code{--with-@var{feature1}} requires that @code{--with-@var{feature2}}
+be also set and will die if the latter is not specified.
 
 @item XE_STRIP_4TH_COMPONENT(var)
-@strong{#### Please document me!}
+Converts the four part system name (eg @code{i986-pc-linux-gnu}) in
+@var{var} to a three part names (eg @code{i986-pc-linux}).
 
 @item CANONICALIZE_PATH(varname)
-@strong{#### Please document me!}
+Strips automount brokenness from the path in @var{varname}.
 
 @item XE_PROTECT_LINKER_FLAGS(shell_var)
-@strong{#### Please document me!}
+Wrap the command line arguments in @var{shell_var} with suitable
+incantations to ensure that the compiler front end passes them to the
+linker.  Currently the magic is added only for gcc.
 
 @item COLON_TO_SPACE(path)
-Allow use of either @samp{:} or spaces for lists of directories.
+Converts a colon separated list of paths into a space separated list of paths.
 
 @item XE_ADD_RUNPATH_DIR(directory)
-@strong{#### Please document me!}
+Internal function used by @code{XE_COMPUTE_RUNPATH}.
 
 @item XE_COMPUTE_RUNPATH()
-@strong{#### Please document me!}
+Calculate the appropriate dynamic library run path for XEmacs and the
+value to the shell variable @code{ld_switch_run}.
 
 @item XE_SPACE(var, words)
-@strong{#### Please document me!}
+Append to @code{var} a space separated list of @code{words}.  
 
 @item XE_SHLIB_STUFF
-See @file{aclocal.m4}.
+Generate the appropriate shared library support black magic. This is
+implemented in the file @file{aclocal.m4}.
 @end table
 
 @heading XEmacs keyword option support
 
 A @dfn{keyword} option is one that accepts one of a number of
-pre-defined values (if support for sets of values is needed, see
+pre-defined values (if support for sets of values is needed, x1see
 ``complex options'' below).  For example,
 @samp{--with-mail-locking=flock}.
 
-Keyword options use expanded forms of @samp{AC_ARG_[WITH|ENABLE]} called
-@samp{XE_KEYWORD_ARG_[WITH|ENABLE]}, both taking 5 parameters.  The
-first 4 parameters of these macros are the same as original macros with
-the exception that all four parameters are @strong{required}.  The
-@var{action-if-true} code is run after the argument list has been
-parsed.
+Keyword options are defined with expanded forms of
+@samp{AC_ARG_[WITH|ENABLE]} called @samp{XE_KEYWORD_ARG_[WITH|ENABLE]},
+both taking 5 parameters.  The first 4 parameters of these macros are
+the same as original macros with the exception that all four parameters
+are @strong{required}.  The @var{action-if-true} code is run after the
+argument list has been parsed.
 
 The 5th parameter is a list of supported keywords.  The whole list must
-be quoted but the individual keywords should not.
+be quoted but the individual keywords should not.  Here is how the
+@samp{mail-locking} flag is defined:
+
+@example
+XE_KEYWORD_ARG_WITH([mail-locking],
+	AC_HELP_STRING([--with-mail-locking],[Specify the locking to be
+                        used by movemail to prevent concurrent updates
+                        of mail spool files. Valid types are `lockf',
+                        `flock', `dot', `locking' or `mmdf'.]),
+        [],
+        [],
+        [lockf,flock,file,locking,mmdf,pop])
+@end example
+
+(Note that the help string will be reformatted by @file{autoconf} so
+that all whitespace is first compressed to a single space, then folded
+to appear in the right-hand column as above.  Thus the help string may
+appear differently when @code{./configure --help} is invoked.)
 
 If the option value is a not a valid keyword then an error message is
 generated, otherwise the value is left untouched.
 
 This support is implemented via the following @file{GNU m4} macros.
-Macros labelled @dfn{internal} are not expected to be used by
+Macros labeled @dfn{internal} are not expected to be used by
 @file{configure.ac} programmers; they are part of the implementation of
 higher-level features.
 
 @table @code
 @item XE_KEYWORD_ARG_WITH(package, help-string, action-if-true, action-if-false, [keyword1, keyword2, ....])
-Expanded version of @samp{AC_ARG_WITH} for keyword options.  All the
+Expanded version of @code{AC_ARG_WITH} for keyword options.  All the
 parameters are required.  The last argument is a comma-separated list of
 supported keywords, @file{m4}-quoted with @samp{[]}.
 
 @item XE_KEYWORD_ARG_ENABLE(feature, help-string, action-if-true, action-if-false, [keyword1, keyword2, ....])
-Expanded version of @samp{AC_ARG_ENABLE} for keyword options.  All the
+Expanded version of @code{AC_ARG_ENABLE} for keyword options.  All the
 parameters are required.  The last argument is a comma-separated list of
 supported keywords, @file{m4}-quoted with @samp{[]}.
 
@@ -4413,26 +4460,25 @@
 found then an error is generated.
 
 @item XE_KEYWORD(keyword)
-Internal macro to declare an option value.
+Internal macro to convert the keyword list into the various forms needed
+by @code{XE_PARSE_KEYWORD_OPTION}.
 
 @end table
 
 @heading XEmacs complex option support
 
 A @dfn{complex option} is one that takes a number of related values, as
-a set.  For example, we might use "--with-xft=all,nomenubars" for
-compatibility with XFontSet i18n of menubars.  (The example is
-contrived, Xft looks much better than XFS.)  Processing such an option
-requires a number of auxiliary variables.
-
-Complex options use expanded forms of @samp{AC_ARG_[WITH|ENABLE]} called
-@samp{XE_COMPLEX_ARG_[WITH|ENABLE]}, both taking 5 parameters.  The
-first 4 parameters of these macros are the same as original macros with
-the exception that all four parameters are @strong{required}.  The
-@var{action-if-true} code is run after the argument list has been
-parsed.
-
-The 5th parameter is a list of @samp{XE_COMPLEX_OPTION} macro calls that
+a set.  For example, we might use @code{--with-sound=native,nas} to play
+sounds using the native libraries and via NAS.
+
+Complex options are defined with expanded forms of
+@samp{AC_ARG_[WITH|ENABLE]} called @samp{XE_COMPLEX_ARG_[WITH|ENABLE]},
+both taking 5 parameters.  The first 4 parameters of these macros are
+the same as original macros with the exception that all four parameters
+are @strong{required}.  The @var{action-if-true} code is run after the
+argument list has been parsed.
+
+The 5th parameter is a list of @code{XE_COMPLEX_OPTION} macro calls that
 define the valid components and their default values.  The list must be
 quoted but the individual macro calls should not.  Here is how the
 @samp{sound} flag is defined:
@@ -4454,23 +4500,18 @@
 	 XE_COMPLEX_OPTION([esd],[no])])
 @end example
 
-(Note that the help string will be reformatted by @file{autoconf} so
-that all whitespace is first compressed to a single space, then folded
-to appear in the right-hand column as above.  Thus the help string may
-appear differently when @code{./configure --help} is invoked.)
-
 @c #### verify for INSTALL and xemacs Texinfo.
-Each component is interpreted as a separate feature to be enabled or
+Each option is interpreted as a separate feature to be enabled or
 disabled.  As usual, the distinction between ``with'' and ``enable'' is
 that ``with'' features require specific support from the system, usually
 one or more optional libraries, and ``enable'' features are supported
 entirely by code in XEmacs, but the user might want to switch it off for
 some reason.  Option values are stored in the variables
-@samp{with_@var{package}_@var{component}} or
-@samp{enable_@var{feature}_@var{component}} (@i{e.g.} 
-@samp{with_xft_menubars}).
-
-The user of @file{configure} specifies the configuration by providing a
+@code{with_@var{package}_@var{component}} or
+@code{enable_@var{feature}_@var{component}} (@i{e.g.} 
+@code{enable_sound_native}).
+
+The user of @code{configure} specifies the configuration by providing a
 list of components.  The special components @samp{all} and @samp{none}
 may occur first in the list, setting the defaults for all components to
 @samp{yes} or @samp{no} respectively.
@@ -4482,7 +4523,7 @@
 value can also be the null string @samp{""}, usually meaning that
 @file{configure} will attempt to find support for the feature on the
 system, and will enable the configuration if it is available.  Sometimes
-the null string means that @file{configure}'s default is
+the null string means that @code{configure}'s default is
 system-dependent.  (This usage is not consistent, and depends on the
 implementation of the feature detector rather than the argument parser.)
 Users cannot specify the null string for an individual component from
@@ -4494,7 +4535,7 @@
 library which may or may not be supported by multiple components of
 XEmacs, as exemplified by Xft.  This latter usage may be more common
 during development of a feature.  Perhaps specialized APIs should be
-provided, see comment on @samp{XE_COMPLEX_OPTION_HELP_STRING} below.
+provided, see comment on @code{XE_COMPLEX_OPTION_HELP_STRING} below.
 
 @table @code
 @item XE_COMPLEX_OPTION(option, yesno)
@@ -4513,11 +4554,11 @@
 the API may be enhanced to deal with this in the future.
 
 @item XE_COMPLEX_ARG_WITH(PACKAGE, HELP-STRING, ACTION-IF-TRUE, ACTION-IF-FALSE, [XE_COMPLEX_OPTION(a,yes), ....])
-Extended version of @samp{AC_ARG_WITH} for complex options.  All the
+Extended version of @code{AC_ARG_WITH} for complex options.  All the
 parameters are required.
 
 @item XE_COMPLEX_ARG_ENABLE(FEATURE, HELP-STRING, ACTION-IF-TRUE, ACTION-IF-FALSE, [XE_COMPLEX_OPTION(a,yes), ....])
-Expanded version of @samp{AC_ARG_ENABLE} for complex options.  All the
+Expanded version of @code{AC_ARG_ENABLE} for complex options.  All the
 parameters are required.
 
 @item XE_EXPAND_COMPLEX_OPTION(prefix, component, yesno)
@@ -4548,21 +4589,22 @@
 @cindex Makefile precursors
 @cindex precursors, Makefile
 
-@strong{Please write this node!} @c ####
-
-As in other programs using a @file{configure} program, XEmacs's
-Makefiles are not written, they are generated.  The @file{configure}
-program uses Makefile precursors, or templates, to generate the actual
-Makefiles.  In fact, it is a multistage process.  The developer changes
-the file @file{Makefile.in.in}, then @file{configure} first generates an
+As with other @code{autoconf} based programs, XEmacs's Makefiles are not
+written, they are generated.  The @code{configure} program uses Makefile
+precursors, or templates, to generate the actual Makefiles.  Unlike
+other programs this is a multistage process.  The developer changes the
+file @file{Makefile.in.in}, then @code{configure} first generates an
 intermediate file @file{Makefile.in}, and finally produces a portable
-Makefile called @file{Makefile}, and a Makefile optimized for @file{GNU
+Makefile called @file{Makefile}, and a Makefile optimized for @code{GNU
 make} called @file{GNUmakefile}.
 
-This node describes XEmacs-specific techniques and idioms used in the
-@file{Makefile.in.in} files.
-
-
+@file{Makefile.in.in} is run through the C preprocessor as part of this
+process. This means that common files can be included and conditional
+construction of the Makefile can occur.  When @file{GNUmakefile} is
+being produced @code{USE_GNU_MAKE} is defined.
+
+Comments in @file{Makefile.in.in} must start with @samp{##} to avoid
+confusing the preprocessor.
 
 @node Rules When Writing New C Code, Regression Testing XEmacs, The Build Configuration System, Top
 @chapter Rules When Writing New C Code