xemacs-beta: man/internals/internals.texi comparison

comparison man/internals/internals.texi @ 2647:89e2f8e3f660

[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	a4040d921acc
children	5d63eacf17f1

comparison

equal deleted inserted replaced

-:5e4893b16f7c
+:89e2f8e3f660
 @node The Build Configuration System, Rules When Writing New C Code, The Modules of XEmacs, Top
 @chapter The Build Configuration System
 @cindex build configuration
 @cindex configuration, build
-@strong{Please write this node!} @c ####
+XEmacs makes extensive use of the external features provided by the
+system it is running on.  Determining which features are present and
-This node should describe XEmacs-specific techniques and idioms in the
+where they are located is the responsibility of the build configuration
-configuration system.  A particular example is the set of @samp{XE_}
+system.
-macros in @file{configure.in} and @file{configure.ac}.
 @menu
 * The version.sh Script::
 * Adding Configurable Features::
 * The configure Script::
 @section Adding Configurable Features
 @cindex adding configurable features
 @cindex configurable features, adding
 @cindex features, adding configurable
-Adding a configurable feature requires at least adding an option to the
+Adding a configurable feature requires at the very least adding an
-@file{configure} script and a macro definition to @file{src/config.h.in}
+option to the @file{configure} script and a macro definition to
-(@pxref{The configure Script}), and often changes to Makefile precursors
+@file{src/config.h.in} (@pxref{The configure Script}), and often changes
-(@pxref{The Makefile Precursors}).
+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
 @section The configure Script
 @cindex configure script
 @cindex scripts, configure
 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
+flawed programming model (extensive use of macros), with an unpleasant
-implementation about which I've never heard a nice word (GNU @file{m4}),
+implementation (GNU @file{m4}), used to string together a large set of
-used to string together a large set of @emph{ad hoc} tests, to implement
+@emph{ad hoc} tests, to implement a configuration language with
-a configuration language with conventions that are unimportant in simple
+conventions that are unimportant in simple cases and counterintuitive
-cases and counterintuitive when things get complicated.  If that doesn't
+when things get complicated.  If that doesn't scare you off, Welcome! I
-scare you off, Welcome! I think you're ready to become a configure
+think you're ready to become a configure hacker!  (But be prepared for
-hacker!  (But be prepared for things to go downhill from here.)
+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!)
+autogenerated from a precursor.  As of March 2005 on the mainline the
-Currently that precursor is called @file{configure.ac}, but in the
+precursor is called @file{configure.ac} and it is built using
-previous generation it was called @file{configure.in}.  As of February
+@code{autoconf} 2.59.  Prior to that, and with XEmacs 21.4 and earlier
-2005, @file{configure.ac} is used in the development mainline, but
+it was called @file{configure.in} and build using @code{autoconf} 2.13.
-because the semantics of many predefined macros changed drastically
+@code{autoconf} 2.5X is not completely backward compatible with
-between @file{autoconf} 2.13 and @file{autoconf} 2.50 (why not ``3.0''?
+@code{autoconf} 2.13 so the XEmacs Project chose to stick with the devil
-you got me), the XEmacs Project chose to stick with the devil it knew
+it knew for the stable line of XEmacs 21.4 releases.
-for the stable line of XEmacs 21.4 releases.
+One reason for worrying about the level of compatibility is the fact
-One reason for worrying about the semantic changes is the fact that
+that XEmacs uses a lot of homebrew code, including @file{m4} macros, to
-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:
 @itemize
 @item
 provided for performing common operations:
 @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
+Prints the name and value of the list of shell variables.
-@item XE_ADD_OBJS(foo.o ...)
+@item XE_ADD_OBJS(foo.o)
-@strong{#### Please document me!}
+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
+Keyword options are defined with expanded forms of
-@samp{XE_KEYWORD_ARG_[WITH|ENABLE]}, both taking 5 parameters.  The
+@samp{AC_ARG_[WITH|ENABLE]} called @samp{XE_KEYWORD_ARG_[WITH|ENABLE]},
-first 4 parameters of these macros are the same as original macros with
+both taking 5 parameters.  The first 4 parameters of these macros are
-the exception that all four parameters are @strong{required}.  The
+the same as original macros with the exception that all four parameters
-@var{action-if-true} code is run after the argument list has been
+are @strong{required}.  The @var{action-if-true} code is run after the
-parsed.
+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{[]}.
 @item XE_PARSE_KEYWORD_OPTION(prefix, cmdline-flag)
 Internal macro to parse the option values.  If an undeclared option is
 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
+a set.  For example, we might use @code{--with-sound=native,nas} to play
-compatibility with XFontSet i18n of menubars.  (The example is
+sounds using the native libraries and via NAS.
-contrived, Xft looks much better than XFS.)  Processing such an option
-requires a number of auxiliary variables.
+Complex options are defined with expanded forms of
+@samp{AC_ARG_[WITH|ENABLE]} called @samp{XE_COMPLEX_ARG_[WITH|ENABLE]},
-Complex options use expanded forms of @samp{AC_ARG_[WITH|ENABLE]} called
+both taking 5 parameters.  The first 4 parameters of these macros are
-@samp{XE_COMPLEX_ARG_[WITH|ENABLE]}, both taking 5 parameters.  The
+the same as original macros with the exception that all four parameters
-first 4 parameters of these macros are the same as original macros with
+are @strong{required}.  The @var{action-if-true} code is run after the
-the exception that all four parameters are @strong{required}.  The
+argument list has been parsed.
-@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
-The 5th parameter is a list of @samp{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:
 @example
 	[XE_COMPLEX_OPTION([native],[""]),
 	 XE_COMPLEX_OPTION([nas],[""]),
 	 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
+@code{with_@var{package}_@var{component}} or
-@samp{enable_@var{feature}_@var{component}} (@i{e.g.}
+@code{enable_@var{feature}_@var{component}} (@i{e.g.}
-@samp{with_xft_menubars}).
+@code{enable_sound_native}).
-The user of @file{configure} specifies the configuration by providing a
+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.
 In @file{configure.ac}, default values of option values may be
 occur if there is a configuration problems (such as a missing library)
 or @samp{no} which means that the option must not be used.  The default
 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
 the command line.
 exemplified by sound: there are alternative protocols (native, ESD, NAS)
 and each is supported by a corresponding library.  The other is a single
 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)
 Declare a complex option and its default value.  The value @strong{must}
 be either @samp{yes} or @samp{no} or the null string @samp{""}.  The
 This was originally written for the Xft option, and doesn't read so well
 for options based on alternative libraries like sound.  Hackers beware:
 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)
 Internal macro create the option's shell variable containing the default
 value and to note the values in an option list.
 @node The Makefile Precursors, , The configure Script, The Build Configuration System
 @section The Makefile Precursors
 @cindex Makefile precursors
 @cindex precursors, Makefile
-@strong{Please write this node!} @c ####
+As with other @code{autoconf} based programs, XEmacs's Makefiles are not
+written, they are generated.  The @code{configure} program uses Makefile
-As in other programs using a @file{configure} program, XEmacs's
+precursors, or templates, to generate the actual Makefiles.  Unlike
-Makefiles are not written, they are generated.  The @file{configure}
+other programs this is a multistage process.  The developer changes the
-program uses Makefile precursors, or templates, to generate the actual
+file @file{Makefile.in.in}, then @code{configure} first generates an
-Makefiles.  In fact, it is a multistage process.  The developer changes
-the file @file{Makefile.in.in}, then @file{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} is run through the C preprocessor as part of this
-@file{Makefile.in.in} files.
+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
 @cindex writing new C code, rules when
 @cindex C code, rules when writing new

Mercurial > hg > xemacs-beta

comparison man/internals/internals.texi @ 2647:89e2f8e3f660