[AC sjt-xft] configure.ac doc fiddling

APPROVE COMMIT sjt-xft Malcolm, you can go ahead and sync configure.ac and src/config.h.in from sjt-xft to mainline now. Don't worry about the man/internals stuff, I'm doing that myself. If you have any more questions about synching, feel free, but I think that just copying the files across to a pristine 21.5 workspace and copy/pasting the logs is the right way to go. cvs diff ChangeLog configure.ac man/ChangeLog man/internals/internals.texi Index: ChangeLog =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/ChangeLog,v retrieving revision 1.418.2.6 diff -u -r1.418.2.6 ChangeLog --- ChangeLog 11 Feb 2005 12:19:31 -0000 1.418.2.6 +++ ChangeLog 19 Feb 2005 13:39:43 -0000 ＠＠ -0,0 +1,16 ＠＠ +2005-02-19 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * configure.ac (XE_EXPAND_COMPLEX_OPTION): Use same name in comment. + (XEmacs keyword option support): + (XEmacs complex option support): + Move long header comments to internals.texi(The configure Script). + +2005-02-03 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * configure.ac: Trap --with-style flags, now --enable. + +2005-02-03 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * configure.ac (Autodetect native sound): + Handle NetBSD per Aidan's patch. + Index: configure.ac =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/configure.ac,v retrieving revision 1.1.14.4 diff -u -r1.1.14.4 configure.ac --- configure.ac 11 Feb 2005 12:19:44 -0000 1.1.14.4 +++ configure.ac 19 Feb 2005 13:39:45 -0000 ＠＠ -231,20 +231,14 ＠＠ dnl ============================= dnl dnl A "keyword" option is one that accepts one of a number of pre-defined -dnl values (if more than one value is needed see "complex options" below). -dnl For example --with-mail-locking=flock. +dnl values. For example --with-mail-locking=flock. +dnl The descriptions below provide prototypes and little more. dnl -dnl Complex options used an expanded forms of AC_ARG_[WITH|ENABLE] called -dnl XE_KEYWORD_ARG_[WITH|ENABLE] both taking 5 parameters. The first 4 -dnl parameters of these macros are the same as original macros with the -dnl exception that all four paramaters are REQUIRED. The ACTION-IF-TRUE code -dnl is run after the argument list has been parsed. -dnl -dnl The 5th parameter is a list keywords. The list must be quoted but the -dnl individual macros should not. -dnl -dnl If the option value is a not a valid keyword then an error message is -dnl generated, otherwise rthe value is left untouched. +dnl For more information, +dnl (Info-goto-node "(internals)The configure Script") +dnl To edit the documentation, +dnl (progn (find-file "man/internals/internals.texi")) +dnl and search for "＠node The configure Script". dnl dnl XE_PARSE_KEYWORD_OPTION(prefix, cmdline-flag) dnl --------------------------------------------- ＠＠ -311,39 +305,19 ＠＠ dnl A "complex option" is one that takes a number of related values. dnl For example, we might use "--with-xft=all,nomenubars" for compatibility dnl with XFontSet i18n of menubars. (Silly, Xft looks much better than XFS.) -dnl Processing such an option requires a number of auxiliary variables. -dnl -dnl Complex options used an expanded forms of AC_ARG_[WITH|ENABLE] called -dnl XE_COMPLEX_ARG_[WITH|ENABLE] both taking 5 parameters. The first 4 -dnl parameters of these macros are the same as original macros with the -dnl exception that all four paramaters are REQUIRED. The ACTION-IF-TRUE code -dnl is run after the argument list has been parsed. dnl -dnl The 5th parameter is a list of XE_COMPLEX_OPTION macros that define the -dnl valid components and their default values. The list must be quoted but -dnl the individual macros should not. +dnl The descriptions below provide prototypes and little more. +dnl For more information, +dnl (Info-goto-node "(internals)The configure Script") +dnl To edit the documentation, +dnl (progn (find-file "man/internals/internals.texi")) +dnl and search for "＠node The configure Script". dnl -dnl Option values are stored in the variables with_<package>_<component> or -dnl enable_<feature>_<component> (eg with_xft_menubars). -dnl -dnl Option values are either 'yes' which means that the option must be used -dnl and an error must occur if there is a configuration problems (such as a -dnl missing library) or 'no' which means that the option must not be used. -dnl The default value can also be "", meaning maybe, which means 'yes' if the -dnl configuration is present otherwise no. Users cannot specify 'maybe' from -dnl the command line. -dnl -dnl There are two possible uses in XEmacs for this kind of facility. One is -dnl exemplified by sound: there are alternative protocols (native, ESD, NAS) -dnl and each is supported by a corresponding library. The other is a single -dnl library which may or may not be supported by multiple components of -dnl XEmacs, as exemplified by Xft. This latter usage may be more common -dnl during development of a feature. Perhaps specialized APIs should be -dnl provided, see comment on XE_COMPLEX_OPTION_HELP_STRING below. -dnl -dnl XE_COMPLEX_OPTION_DEFAULT(prefix, component, yesno) +dnl XE_EXPAND_COMPLEX_OPTION(prefix, component, yesno) dnl --------------------------------------------------- dnl +dnl #### documented as XE_COMPLEX_OPTION_DEFAULT(prefix, component, yesno) +dnl #### in Malcolm's version? dnl Internal macro create the option's shell variable containing the default dnl value and to note the values in an option list. dnl ＠＠ -492,7 +466,33 ＠＠ dnl Error-checking on old-style flags AC_ARG_WITH([mule],[],[XE_DIE([--enable-mule, NOT --with-mule])],[]) +AC_ARG_WITH([menubars],[],[XE_DIE([--enable-menubars, NOT --with-menubars])],[]) +AC_ARG_WITH([scrollbars],[],[XE_DIE([--enable-scrollbars, NOT --with-scrollbars])],[]) +AC_ARG_WITH([dialogs],[],[XE_DIE([--enable-dialogs, NOT --with-dialogs])],[]) +AC_ARG_WITH([widgets],[],[XE_DIE([--enable-widgets, NOT --with-widgets])],[]) +AC_ARG_WITH([sound],[],[XE_DIE([--enable-sound, NOT --with-sound])],[]) +AC_ARG_WITH([default-eol-detection],[],[XE_DIE([--enable-default-eol-detection, NOT --with-default-eol-detection])],[]) +AC_ARG_WITH([clash-detection],[],[XE_DIE([--enable-clash-detection, NOT --with-clash-detection])],[]) +AC_ARG_WITH([database],[],[XE_DIE([--enable-database, NOT --with-database])],[]) +AC_ARG_WITH([modules],[],[XE_DIE([--enable-modules, NOT --with-modules])],[]) +AC_ARG_WITH([toolbars],[],[XE_DIE([--enable-toolbars, NOT --with-toolbars])],[]) + +dnl I think these will be caught by autoconf internal checks, +dnl only --with-* are unchecked +dnl --external-widget --enable-external-widget +dnl --native-sound-lib=LIB --with-native-sound-lib +dnl --mail-locking=TYPE --with-mail-locking +dnl --rel-alloc --with-rel-alloc +dnl --use-number-lib --enable-bignum +dnl --debug --enable-debug +dnl --error-checking --enable-error-checking +dnl --memory-usage-stats --enable-memory-usage-stats +dnl --quick-build --enable-quick-build +dnl --use-union-type --enable-union-type +dnl --pdump --enable-pdump +dnl --use-kkcc --enable-kkcc +dnl parse flags AC_ARG_WITH([prefix], AC_HELP_STRING([--with-prefix=no],[Don't compile the value of --prefix into the executable.]), [true], [with_prefix=yes]) ＠＠ -4807,29 +4807,37 ＠＠ dnl Check for Linux/BSD native sound (also on recent Cygwins) if test -z "$sound_found"; then for dir in "machine" "sys" "linux"; do - AC_CHECK_HEADER(${dir}/soundcard.h, + AC_CHECK_HEADER(${dir}/soundcard.h, [ sound_found=yes - need_miscplay=yes - XE_ADD_OBJS(linuxplay.o) - [AC_DEFINE_UNQUOTED(SOUNDCARD_H_FILE, "${dir}/soundcard.h")] - break) + case "$canonical" in + *netbsd* ) + # #### this is probably not the right way to do this + # we should port to native NetBSD stuff + AC_CHECK_LIB(ossaudio, _oss_ioctl, + [native_sound_lib=-lossaudio + AC_MSG_WARN([Using NetBSD-deprecated -lossaudio])], + [sound_found=no]) + ;; + dnl Aidan sez: OpenBSD as well can use Linux's sound API, and needs + dnl the same library. Add here! + esac + break]) done + + if test "$sound_found" = "yes"; then + need_miscplay=yes + XE_ADD_OBJS(linuxplay.o) + [AC_DEFINE_UNQUOTED(SOUNDCARD_H_FILE, "${dir}/soundcard.h")] + fi fi if test "$sound_found" = "yes"; then - enable_sound_native=yes - - dnl NetBSD can use Linux's sound API, but it needs an extra library at - dnl link time to do so. (OpenBSD apparently needs the same; not written - dnl or tested.) - if test "$opsys" = "netbsd" ; then - AC_CHECK_LIB(ossaudio, _oss_ioctl, native_sound_lib="-lossaudio") - fi + enable_sound_native=yes else - if test "$enable_sound_native" = "yes" ; then - AC_MSG_WARN([No native libraries found. Disabling native sound support.]) - fi - enable_sound_native=no + if test "$enable_sound_native" = "yes" ; then + AC_MSG_WARN([No native libraries found. Disabling native sound support.]) + fi + enable_sound_native=no fi fi Index: man/ChangeLog =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/man/ChangeLog,v retrieving revision 1.269.2.3 diff -u -r1.269.2.3 ChangeLog --- man/ChangeLog 1 Feb 2005 15:46:42 -0000 1.269.2.3 +++ man/ChangeLog 19 Feb 2005 13:39:47 -0000 ＠＠ -0,0 +1,31 ＠＠ +2005-02-19 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * internals/internals.texi (Introduction to Writing C Code): + Change "mostly warning-free" to "warning-free" to encourage + reporting warnings as bugs. + (The configure Script): + Incorporate Malcolm Purvis's notes from configure.ac. Document + his implementations of keyword and complex options, and remove + descriptions of my obsolete code. + +2005-02-03 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + * internals/internals.texi (XEmacs from the Perspective of + Building): Mention autoconf. + (The Modules of XEmacs): Point Next the The Build Configuration + System and add Modules for Building XEmacs to the menu. + (A Summary of the Various XEmacs Modules): Add Modules for + Building XEmacs to menu, and Modules for Build Configuration, + Modules for Compiling XEmacs, and Modules for Preloading Lisp to + the table of sections. + (Low-Level Modules): Point Previous to Modules for Building XEmacs. + (Modules for Building XEmacs): + (Modules for Build Configuration): + (Modules for Compiling XEmacs): + (Modules for Preloading Lisp): + (The Build Configuration System): + (Adding Configurable Features): + (The configure Script): + (The Makefile Precursors): + New nodes. + (Rules When Writing New C Code): + Point Previous to The Build Configuration System. ＠＠ -386,7 +856,7 ＠＠ (Future Work -- Lisp Engine Replacement): Add pointers to new node. -04-11-16 Ben Wing <ben(a)xemacs.org&gt; +2004-11-16 Ben Wing <ben(a)xemacs.org&gt; * internals/internals.texi (Top): * internals/internals.texi (Introduction): Index: man/internals/internals.texi =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/man/internals/internals.texi,v retrieving revision 1.52.2.3 diff -u -r1.52.2.3 internals.texi --- man/internals/internals.texi 1 Feb 2005 15:46:44 -0000 1.52.2.3 +++ man/internals/internals.texi 19 Feb 2005 13:40:09 -0000 ＠＠ -311,6 +311,7 ＠＠ * XEmacs from the Perspective of Building:: * Build-Time Dependencies:: * The Modules of XEmacs:: +* The Build Configuration System:: * Rules When Writing New C Code:: * Regression Testing XEmacs:: * CVS Techniques:: ＠＠ -2331,7 +2410,9 ＠＠ The first step of building involves running the ＠file{configure} program and passing it various parameters to specify any optional features you want and compiler arguments and such, as described in the ＠file{INSTALL} -file. This determines what the build environment is, chooses the +file. (You may optionally run ＠file{autoconf} first to update the +＠file{configure} script. ＠xref{Modules for Build Configuration}.) +This determines what the build environment is, chooses the appropriate ＠file{s/} and ＠file{m/} file, and runs a series of tests to determine many details about your environment, such as which library functions are available and exactly how they work. The reason for ＠＠ -2442,12 +2523,13 ＠＠ ＠code{custom-declare-variable-list} to prevent the ＠samp{void-variable} error. (Currently this is only needed for ＠file{make-docfile.el}.) -＠node The Modules of XEmacs, Rules When Writing New C Code, Build-Time Dependencies, Top +＠node The Modules of XEmacs, The Build Configuration System, Build-Time Dependencies, Top ＠chapter The Modules of XEmacs ＠cindex modules of XEmacs ＠menu * A Summary of the Various XEmacs Modules:: +* Modules for Building XEmacs:: * Low-Level Modules:: * Basic Lisp Modules:: * Modules for Standard Editing Operations:: ＠＠ -2456,7 +2538,7 ＠＠ * Modules for Interfacing with the Operating System:: ＠end menu -＠node A Summary of the Various XEmacs Modules, Low-Level Modules, The Modules of XEmacs, The Modules of XEmacs +＠node A Summary of the Various XEmacs Modules, Modules for Building XEmacs, The Modules of XEmacs, The Modules of XEmacs ＠section A Summary of the Various XEmacs Modules ＠cindex summary of the various XEmacs modules ＠cindex modules, summary of the various XEmacs ＠＠ -2468,6 +2550,12 ＠＠ ＠itemize ＠bullet ＠item +＠ref{Modules for Build Configuration}. +＠item +＠ref{Modules for Compiling XEmacs}. +＠item +＠ref{Modules for Preloading Lisp}. +＠item ＠ref{Low-Level Modules}. ＠item ＠ref{Basic Lisp Modules}. ＠＠ -2944,7 +3032,65 ＠＠ -＠node Low-Level Modules, Basic Lisp Modules, A Summary of the Various XEmacs Modules, The Modules of XEmacs +＠node Modules for Building XEmacs, Low-Level Modules, A Summary of the Various XEmacs Modules, The Modules of XEmacs +＠section Modules for Building XEmacs +＠cindex modules for building XEmacs +＠cindex building XEmacs, modules for + +＠menu +* Modules for Build Configuration:: +* Modules for Compiling XEmacs:: +* Modules for Preloading Lisp:: +＠end menu + + + +＠node Modules for Build Configuration, Modules for Compiling XEmacs, Modules for Building XEmacs, Modules for Building XEmacs +＠subsection Modules for Build Configuration +＠cindex modules for build configuration +＠cindex build configuration, modules for + +＠example +＠file{configure} +(a)file{config.h.in} +(a)file{Makefile.in.in} +＠end example + +＠example +(a)file{configure.ac} +(a)file{configure.in} +＠end example + +＠xref{The configure Script}. + + + +＠node Modules for Compiling XEmacs, Modules for Preloading Lisp, Modules for Build Configuration, Modules for Building XEmacs +＠subsection Modules for Compiling XEmacs +＠cindex modules for compiling xemacs +＠cindex compiling xemacs, modules for + +＠strong{Please write this node!} ＠c #### + +This node should contain descriptions of files like the various +Makefiles, and I guess cross-references to ellcc etc. + + + +＠node Modules for Preloading Lisp, , Modules for Compiling XEmacs, Modules for Building XEmacs +＠subsection Modules for Preloading Lisp +＠cindex modules for preloading lisp +＠cindex preloading lisp, modules for + +＠strong{Please write this node!} ＠c #### + +This node should contain descriptions of files like dumped-lisp.el +(maybe that goes in Modules for Build Configuration supra?), +update-elcs.el, and so on. + + + +＠node Low-Level Modules, Basic Lisp Modules, Modules for Building XEmacs, The Modules of XEmacs ＠section Low-Level Modules ＠cindex low-level modules ＠cindex modules, low-level ＠＠ -3978,7 +4124,327 ＠＠ This module provides some terminal-control code necessary on versions of AIX prior to 4.1. -＠node Rules When Writing New C Code, Regression Testing XEmacs, The Modules of XEmacs, Top + + +＠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 #### + +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}. + +＠menu +* Adding Configurable Features:: +* The configure Script:: +* The Makefile Precursors:: +＠end menu + + + +＠node Adding Configurable Features, The configure Script, The Build Configuration System, The Build Configuration System +＠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 +＠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}). + + + +＠node The configure Script, The Makefile Precursors, Adding Configurable Features, The Build Configuration System +＠section The configure Script +＠cindex configure script +＠cindex script, 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 +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.) + +＠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 +implement special features in its ＠file{configure} script. Here are +some of the important features: + +＠itemize +＠item +Selectively enabling debugging, error checking, and tracing. +＠item +Complex options, which are set-valued (＠i{i.e.}, unordered; ordered +lists of options, for example ``take the first available from the +list,'' are neither used currently nor given special support). +＠end itemize + +Where these are implemented as ＠file{m4} macros, the prefix ＠samp{XE_} +is used to identify them as XEmacs features in the ＠file{configure} +precursor code. Here is a list of prototypes of the convenience macros +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 + +＠item PRINT_VAR(var var ...) +prints values of shell variables + +＠item XE_ADD_OBJS(foo.o ...) +＠strong{#### Please document me!} + +＠item XE_APPEND(value, varname) +＠strong{#### Please document me!} + +＠item XE_PREPEND(value, varname) +＠strong{#### Please document me!} + +＠item XE_DIE(message) +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!} + +＠item XE_STRIP_4TH_COMPONENT(var) +＠strong{#### Please document me!} + +＠item CANONICALIZE_PATH(varname) +＠strong{#### Please document me!} + +＠item XE_PROTECT_LINKER_FLAGS(shell_var) +＠strong{#### Please document me!} + +＠item COLON_TO_SPACE(path) +Allow use of either ＠samp{:} or spaces for lists of directories. + +＠item XE_ADD_RUNPATH_DIR(directory) +＠strong{#### Please document me!} + +＠item XE_COMPUTE_RUNPATH() +＠strong{#### Please document me!} + +＠item XE_SPACE(var, words) +＠strong{#### Please document me!} + +＠item XE_SHLIB_STUFF +See ＠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 +``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. + +The 5th parameter is a list of supported keywords. The whole list must +be quoted but the individual keywords should not. + +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 +(a)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 +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 +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. + +＠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 +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_ARG_ENABLE([sound], + AC_HELP_STRING([--enable-sound],[Compile with sound support. + Valid types are `native', `nas' and `esd'. + Prefix a type with 'no' to disable. + The first type can be `none' or `all'. `none' means + `nonative,nonas,noesd'. `all' means `native,nas,esd'. + Later options override earlier ones for the same TYPE. + The default is to autodetect all sound support except + for ESD which defaults to off.]), + [], + [enable_sound_nas=""], + [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 +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 +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 +＠samp{yes} which means that the option must be used and an error must +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 +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. + +There are two possible uses in XEmacs for this kind of facility. One is +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. + +＠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 +null string means ``maybe'', whose semantics are determined by the +implementation of the option, not by the parser. Typical semantics are +``use the library if found in the usual places'' or ``default is +platform-dependent''. + +＠item XE_COMPLEX_OPTION_HELP_STRING(flag, long, short, components, libraries) +Format a boilerplate help string for complex options. + +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 +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 +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. + +＠item XE_EXPAND_COMPLEX_OPTIONS(prefix, option_list) +Internal macro which recursively expands an option list. + +＠item XE_INIT_COMPLEX_OPTION(prefix, option_list) +Internal macro to initialise the complex option shell variables. + +Variables of the form ＠samp{＠var{prefix}_＠var{option}} contain the +default value for that option. ＠samp{＠var{prefix}_types} contains a +space-separated list of all the options and ＠samp{＠var{prefix}_default} +contains a comma-separated list of all the default values. + +＠item XE_PARSE_COMPLEX_OPTION(prefix, cmdline-flag) +Internal macro to parse the option values. If an undeclared option is +found then an error is generated. + +＠end table + + + +＠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 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 +intermediate file ＠file{Makefile.in}, and finally produces a portable +Makefile called ＠file{Makefile}, and a Makefile optimized for ＠file{GNU +make} called ＠file{GNUmakefile}. + +This node describes XEmacs-specific techniques and idioms used in the +(a)file{Makefile.in.in} files. + + + +＠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 ＠＠ -4012,8 +4478,8 ＠＠ ＠cindex coding conventions The C code is actually written in a dialect of C called ＠dfn{Clean C}, -meaning that it can be compiled, mostly warning-free, with either a C -or C++ compiler. Coding in Clean C has several advantages over plain +meaning that it can be compiled, warning-free, with either a C or C++ +compiler. Coding in Clean C has several advantages over plain C. C++ compilers are more nit-picking, and a number of coding errors have been found by compiling with C++. The ability to use both C and C++ tools means that a greater variety of development tools are ＠＠ -4024,6 +4490,7 ＠＠ classes, strictly limiting the permissible operations and catching illegal implicit casts and such. +＠c #### did Ben delete this, or just the CODING-STANDARDS file in ./etc? XEmacs follows the GNU coding standards, which are documented separately in ＠xref{top,,, standards, GNU Coding Standards}. This section mainly documents standards that are not included in that -- Institute of Policy and Planning Sciences http://turnbull.sk.tsukuba.ac.jp University of Tsukuba Tennodai 1-1-1 Tsukuba 305-8573 JAPAN Ask not how you can "do" free software business; ask what your business can "do for" free software.