+A physicist, an engineer, and a computer scientist were discussing the
+nature of God. ``Surely a Physicist,'' said the physicist, ``because
+early in the Creation, God made Light; and you know, Maxwell's
+equations, the dual nature of electromagnetic waves, the relativistic
+consequences...'' ``An Engineer!,'' said the engineer, ``because
+before making Light, God split the Chaos into Land and Water; it takes a
+hell of an engineer to handle that big amount of mud, and orderly
+separation of solids from liquids...'' The computer scientist
+shouted: ``And the Chaos, where do you think it was coming from, hmm?''
+
+---Anonymous
+
+
+
+Autoconf is a tool for producing shell scripts that automatically
+configure software source code packages to adapt to many kinds of
+UNIX-like systems. The configuration scripts produced by Autoconf
+are independent of Autoconf when they are run, so their users do not
+need to have Autoconf.
+
+
+
+The configuration scripts produced by Autoconf require no manual user
+intervention when run; they do not normally even need an argument
+specifying the system type. Instead, they individually test for the
+presence of each feature that the software package they are for might need.
+(Before each check, they print a one-line message stating what they are
+checking for, so the user doesn't get too bored while waiting for the
+script to finish.) As a result, they deal well with systems that are
+hybrids or customized from the more common UNIX variants. There is
+no need to maintain files that list the features supported by each
+release of each variant of UNIX.
+
+
+
+For each software package that Autoconf is used with, it creates a
+configuration script from a template file that lists the system features
+that the package needs or can use. After the shell code to recognize
+and respond to a system feature has been written, Autoconf allows it to
+be shared by many software packages that can use (or need) that feature.
+If it later turns out that the shell code needs adjustment for some
+reason, it needs to be changed in only one place; all of the
+configuration scripts can be regenerated automatically to take advantage
+of the updated code.
+
+
+
+The Metaconfig package is similar in purpose to Autoconf, but the
+scripts it produces require manual user intervention, which is quite
+inconvenient when configuring large source trees. Unlike Metaconfig
+scripts, Autoconf scripts can support cross-compiling, if some care is
+taken in writing them.
+
+
+
+Autoconf does not solve all problems related to making portable software
+packages--for a more complete solution, it should be used in concert
+with other GNU build tools like Automake and Libtool. These other tools
+take on jobs like the creation of a portable, recursive `Makefile'
+with all of the standard targets, linking of shared libraries, and so
+on. See section The GNU build system, for more information.
+
+
+
+Autoconf imposes some restrictions on the names of macros used with
+#if in C programs (see section Preprocessor Symbol Index).
+
+
+
+Autoconf requires GNU M4 in order to generate the scripts. It uses
+features that some UNIX versions of M4, including GNU M4 1.3,
+do not have. You must use version 1.4 or later of GNU M4.
+
+
+
+See the @href{http://www.gnu.org/software/autoconf/autoconf.html,
+Autoconf web page} for up-to-date information, details on the mailing
+lists, pointers to a list of known bugs, etc.
+
+
+
+Bug reports should be preferably submitted to the
+@href{http://sources.redhat.com/cgi-bin/gnatsweb.pl?database=autoconf,
+Autoconf Gnats database}, or sent to the
+Autoconf Bugs mailing list. If possible, first check that your bug is
+not already solved in current development versions, and that it has not
+been reported yet. Be sure to include all the needed information and a
+short `configure.ac' that demonstrates the problem.
+
+
+
+Autoconf's development tree is accessible via CVS; see the Autoconf
+web page for details. There is also a
+@href{http://subversions.gnu.org/cgi-bin/cvsweb/autoconf/, CVSweb
+interface to the Autoconf development tree}. Patches relative to the
+current CVS version can be sent for review to the
+Autoconf Patches mailing list.
+
+
+
+Because of its mission, Autoconf includes only a set of often-used
+macros that have already demonstrated their usefulness. Nevertheless,
+if you wish to share your macros, or find existing ones, see the
+@href{http://www.gnu.org/software/ac-archive/, Autoconf Macro
+Archive}, which is kindly run by Peter Simons.
+
+
+
+
+
+Autoconf solves an important problem--reliable discovery of
+system-specific build and runtime information--but this is only one
+piece of the puzzle for the development of portable software. To this
+end, the GNU project has developed a suite of integrated utilities to
+finish the job Autoconf started: the GNU build system, whose most
+important components are Autoconf, Automake, and Libtool. In this
+chapter, we introduce you to those tools, point you to sources of more
+information, and try to convince you to use the entire GNU build system
+for your software.
+
+
+
+
+
+The ubiquity of make means that a Makefile is almost the
+only viable way to distribute automatic build rules for software, but
+one quickly runs into make's numerous limitations. Its lack of
+support for automatic dependency tracking, recursive builds in
+subdirectories, reliable timestamps (e.g. for network filesystems), and
+so on, mean that developers must painfully (and often incorrectly)
+reinvent the wheel for each project. Portability is non-trivial, thanks
+to the quirks of make on many systems. On top of all this is the
+manual labor required to implement the many standard targets that users
+have come to expect (make install, make distclean,
+make uninstall, etc.). Since you are, of course, using Autoconf,
+you also have to insert repetitive code in your Makefile.in to
+recognize @CC@, @CFLAGS@, and other substitutions
+provided by @command{configure}. Into this mess steps Automake.
+
+
+
+
+Automake allows you to specify your build needs in a Makefile.am
+file with a vastly simpler and more powerful syntax than that of a plain
+Makefile, and then generates a portable Makefile.in for
+use with Autoconf. For example, the Makefile.am to build and
+install a simple "Hello world" program might look like:
+
+
+
+
+bin_PROGRAMS = hello
+hello_SOURCES = hello.c
+
+
+
+The resulting Makefile.in (~400 lines) automatically supports all
+the standard targets, the substitutions provided by Autoconf, automatic
+dependency tracking, VPATH building, and so on. make will
+build the hello program, and make install will install it
+in `/usr/local/bin' (or whatever prefix was given to
+@command{configure}, if not `/usr/local').
+
+
+
+Automake may require that additional tools be present on the
+developer's machine. For example, the Makefile.in that
+the developer works with may not be portable (e.g. it might use special
+features of your compiler to automatically generate dependency
+information). Running make dist, however, produces a
+`hello-1.0.tar.gz' package (or whatever the program/version is)
+with a Makefile.in that will work on any system.
+
+
+
+The benefits of Automake increase for larger packages (especially ones
+with subdirectories), but even for small programs the added convenience
+and portability can be substantial. And that's not all...
+
+
+
+
+
+Very often, one wants to build not only programs, but libraries, so that
+other programs can benefit from the fruits of your labor. Ideally, one
+would like to produce shared (dynamically-linked) libraries,
+which can be used by multiple programs without duplication on disk or in
+memory and can be updated independently of the linked programs.
+Producing shared libraries portably, however, is the stuff of
+nightmares--each system has its own incompatible tools, compiler flags,
+and magic incantations. Fortunately, GNU provides a solution:
+Libtool.
+
+
+
+
+Libtool handles all the requirements of building shared libraries for
+you, and at this time seems to be the only way to do so with any
+portability. It also handles many other headaches, such as: the
+interaction of Makefile rules with the variable suffixes of
+shared libraries, linking reliably to shared libraries before they are
+installed by the superuser, and supplying a consistent versioning system
+(so that different versions of a library can be installed or upgraded
+without breaking binary compatibility). Although Libtool, like
+Autoconf, can be used on its own, it is most simply utilized in
+conjunction with Automake--there, Libtool is used automatically
+whenever shared libraries are needed, and you need not know its syntax.
+
+
+
+
+
+Developers who are used to the simplicity of make for small
+projects on a single system might be daunted at the prospect of learning
+to use Automake and Autoconf. As your software is distributed to more
+and more users, however, you will otherwise quickly find yourself
+putting lots of effort into reinventing the services that the GNU build
+tools provide, and making the same mistakes that they once made and
+overcame. (Besides, since you're already learning Autoconf, Automake
+will be a piece of cake.)
+
+
+
+There are a number of places that you can go to for more information on
+the GNU build tools.
+
+
+
+
+
+
Web
+
+The home pages for
+@href{http://www.gnu.org/software/autoconf/,Autoconf},
+@href{http://www.gnu.org/software/automake/,Automake}, and
+@href{http://www.gnu.org/software/libtool/,Libtool}.
+
+
Automake Manual
+
+See section `Automake' in GNU Automake, for more
+information on Automake.
+
+
Books
+
+The book GNU Autoconf, Automake and Libtool(1)
+describes the complete GNU build environment. You can also find the
+entire book on-line at @href{http://sources.redhat.com/autobook/,"The
+Goat Book" home page}.
+
+
Tutorials and Examples
+
+The @href{http://sources.redhat.com/autoconf/,Autoconf Developer Page}
+maintains links to a number of Autoconf/Automake tutorials online, and
+also links to the @href{http://www.gnu.org/software/ac-archive/,
+Autoconf Macro Archive}.
+
+
+The configuration scripts that Autoconf produces are by convention
+called @command{configure}. When run, @command{configure} creates several
+files, replacing configuration parameters in them with appropriate
+values. The files that @command{configure} creates are:
+
+
+
+
+
+
+one or more `Makefile' files, one in each subdirectory of the
+package (see section Substitutions in Makefiles);
+
+
+
+optionally, a C header file, the name of which is configurable,
+containing #define directives (see section Configuration Header Files);
+
+
+
+a shell script called `config.status' that, when run, will recreate
+the files listed above (see section Recreating a Configuration);
+
+
+
+an optional shell script normally called `config.cache'
+(created when using `configure --config-cache') that
+saves the results of running many of the tests (see section Cache Files);
+
+
+
+a file called `config.log' containing any messages produced by
+compilers, to help debugging if @command{configure} makes a mistake.
+
+
+
+
+
+To create a @command{configure} script with Autoconf, you need to write an
+Autoconf input file `configure.ac' (or `configure.in') and run
+@command{autoconf} on it. If you write your own feature tests to
+supplement those that come with Autoconf, you might also write files
+called `aclocal.m4' and `acsite.m4'. If you use a C header
+file to contain #define directives, you might also run
+@command{autoheader}, and you will distribute the generated file
+`config.h.in' with the package.
+
+
+
+Here is a diagram showing how the files that can be used in
+configuration are produced. Programs that are executed are suffixed by
+`*'. Optional files are enclosed in square brackets (`[]').
+@command{autoconf} and @command{autoheader} also read the installed Autoconf
+macro files (by reading `autoconf.m4').
+
+
+
+Files used in preparing a software package for distribution:
+
+
+To produce a @command{configure} script for a software package, create a
+file called `configure.ac' that contains invocations of the
+Autoconf macros that test the system features your package needs or can
+use. Autoconf macros already exist to check for many features; see
+section Existing Tests, for their descriptions. For most other features,
+you can use Autoconf template macros to produce custom checks; see
+section Writing Tests, for information about them. For especially tricky
+or specialized features, `configure.ac' might need to contain some
+hand-crafted shell commands; see section Portable Shell Programming. The
+@command{autoscan} program can give you a good start in writing
+`configure.ac' (see section Using @command{autoscan} to Create @file{configure.ac}, for more information).
+
+
+
+Previous versions of Autoconf promoted the name `configure.in',
+which is somewhat ambiguous (the tool needed to produce this file is not
+described by its extension), and introduces a slight confusion with
+`config.h.in' and so on (for which `.in' means "to be
+processed by @command{configure}"). Using `configure.ac' is now
+preferred.
+
+
+
+
+
+Just as for any other computer language, in order to properly program
+`configure.ac' in Autoconf you must understand what problem
+the language tries to address and how it does so.
+
+
+
+The problem Autoconf addresses is that the world is a mess. After all,
+you are using Autoconf in order to have your package compile easily on
+all sorts of different systems, some of them being extremely hostile.
+Autoconf itself bears the price for these differences: @command{configure}
+must run on all those systems, and thus @command{configure} must limit itself
+to their lowest common denominator of features.
+
+
+
+Naturally, you might then think of shell scripts; who needs
+@command{autoconf}? A set of properly written shell functions is enough to
+make it easy to write @command{configure} scripts by hand. Sigh!
+Unfortunately, shell functions do not belong to the least common
+denominator; therefore, where you would like to define a function and
+use it ten times, you would instead need to copy its body ten times.
+
+
+
+So, what is really needed is some kind of compiler, @command{autoconf},
+that takes an Autoconf program, `configure.ac', and transforms it
+into a portable shell script, @command{configure}.
+
+
+
+How does @command{autoconf} perform this task?
+
+
+
+There are two obvious possibilities: creating a brand new language or
+extending an existing one. The former option is very attractive: all
+sorts of optimizations could easily be implemented in the compiler and
+many rigorous checks could be performed on the Autoconf program
+(e.g. rejecting any non-portable construct). Alternatively, you can
+extend an existing language, such as the sh (Bourne shell)
+language.
+
+
+
+Autoconf does the latter: it is a layer on top of sh. It was
+therefore most convenient to implement @command{autoconf} as a macro
+expander: a program that repeatedly performs macro expansions on
+text input, replacing macro calls with macro bodies and producing a pure
+sh script in the end. Instead of implementing a dedicated
+Autoconf macro expander, it is natural to use an existing
+general-purpose macro language, such as M4, and implement the extensions
+as a set of M4 macros.
+
+
+
+
+
+The Autoconf language is very different from many other computer
+languages because it treats actual code the same as plain text. Whereas
+in C, for instance, data and instructions have very different syntactic
+status, in Autoconf their status is rigorously the same. Therefore, we
+need a means to distinguish literal strings from text to be expanded:
+quotation.
+
+
+
+When calling macros that take arguments, there must not be any blank
+space between the macro name and the open parenthesis. Arguments should
+be enclosed within the M4 quote characters `[' and `]', and be
+separated by commas. Any leading spaces in arguments are ignored,
+unless they are quoted. You may safely leave out the quotes when the
+argument is simple text, but always quote complex arguments such
+as other macro calls. This rule applies recursively for every macro
+call, including macros called from other macros.
+
+
+
+For instance:
+
+
+
+
+AC_CHECK_HEADER([stdio.h],
+ [AC_DEFINE([HAVE_STDIO_H])],
+ [AC_MSG_ERROR([Sorry, can't do anything for you])])
+
+
+
+is quoted properly. You may safely simplify its quotation to:
+
+
+
+
+AC_CHECK_HEADER(stdio.h,
+ [AC_DEFINE(HAVE_STDIO_H)],
+ [AC_MSG_ERROR([Sorry, can't do anything for you])])
+
+
+
+Notice that the argument of AC_MSG_ERROR is still quoted;
+otherwise, its comma would have been interpreted as an argument separator.
+
+
+
+The following example is wrong and dangerous, as it is underquoted:
+
+
+
+
+AC_CHECK_HEADER(stdio.h,
+ AC_DEFINE(HAVE_STDIO_H),
+ AC_MSG_ERROR([Sorry, can't do anything for you]))
+
+
+
+In other cases, you may have to use text that also resembles a macro
+call. You must quote that text even when it is not passed as a macro
+argument:
+
+
+
+
+echo "Hard rock was here! --[AC_DC]"
+
+
+
+which will result in
+
+
+
+
+echo "Hard rock was here! --AC_DC"
+
+
+
+When you use the same text in a macro argument, you must therefore have
+an extra quotation level (since one is stripped away by the macro
+substitution). In general, then, it is a good idea to use double
+quoting for all literal string arguments:
+
+
+
+
+AC_MSG_WARN([[AC_DC stinks --Iron Maiden]])
+
+
+
+You are now able to understand one of the constructs of Autoconf that
+has been continually misunderstood... The rule of thumb is that
+whenever you expect macro expansion, expect quote expansion;
+i.e., expect one level of quotes to be lost. For instance:
+
+
+
+
+is incorrect: here, the first argument of AC_COMPILE_IFELSE is
+`char b[10];' and will be expanded once, which results in
+`char b10;'. (There was an idiom common in Autoconf's past to
+address this issue via the M4 changequote primitive, but do not
+use it!) Let's take a closer look: the author meant the first argument
+to be understood as a literal, and therefore it must be quoted twice:
+
+
+
+
+Voil`a, you actually produce `char b[10];' this time!
+
+
+
+The careful reader will notice that, according to these guidelines, the
+"properly" quoted AC_CHECK_HEADER example above is actually
+lacking three pairs of quotes! Nevertheless, for the sake of readability,
+double quotation of literals is used only where needed in this manual.
+
+
+
+Some macros take optional arguments, which this documentation represents
+as @ovar{arg} (not to be confused with the quote characters). You may
+just leave them empty, or use `[]' to make the emptiness of the
+argument explicit, or you may simply omit the trailing commas. The
+three lines below are equivalent:
+
+
+
+
+It is best to put each macro call on its own line in
+`configure.ac'. Most of the macros don't add extra newlines; they
+rely on the newline after the macro call to terminate the commands.
+This approach makes the generated @command{configure} script a little
+easier to read by not inserting lots of blank lines. It is generally
+safe to set shell variables on the same line as a macro call, because
+the shell allows assignments without intervening newlines.
+
+
+
+You can include comments in `configure.ac' files by starting them
+with the `#'. For example, it is helpful to begin
+`configure.ac' files with a line like this:
+
+
+
+
+# Process this file with autoconf to produce a configure script.
+
+The order in which `configure.ac' calls the Autoconf macros is not
+important, with a few exceptions. Every `configure.ac' must
+contain a call to AC_INIT before the checks, and a call to
+AC_OUTPUT at the end (see section Outputting Files). Additionally, some macros
+rely on other macros having been called first, because they check
+previously set values of some variables to decide what to do. These
+macros are noted in the individual descriptions (see section Existing Tests), and they also warn you when @command{configure} is created if they
+are called out of order.
+
+
+
+To encourage consistency, here is a suggested order for calling the
+Autoconf macros. Generally speaking, the things near the end of this
+list are those that could depend on things earlier in it. For example,
+library functions could be affected by types and libraries.
+
+
+
+
+Autoconf requirements
+AC_INIT(package, version, bug-report-address)
+information on the package
+checks for programs
+checks for libraries
+checks for header files
+checks for types
+checks for structures
+checks for compiler characteristics
+checks for library functions
+checks for system services
+AC_CONFIG_FILES([file...])
+AC_OUTPUT
+
+The @command{autoscan} program can help you create and/or maintain a
+`configure.ac' file for a software package. @command{autoscan}
+examines source files in the directory tree rooted at a directory given
+as a command line argument, or the current directory if none is given.
+It searches the source files for common portability problems and creates
+a file `configure.scan' which is a preliminary `configure.ac'
+for that package, and checks a possibly existing `configure.ac' for
+completeness.
+
+
+
+When using @command{autoscan} to create a `configure.ac', you
+should manually examine `configure.scan' before renaming it to
+`configure.ac'; it will probably need some adjustments.
+Occasionally, @command{autoscan} outputs a macro in the wrong order
+relative to another macro, so that @command{autoconf} produces a warning;
+you need to move such macros manually. Also, if you want the package to
+use a configuration header file, you must add a call to
+AC_CONFIG_HEADERS (see section Configuration Header Files). You might
+also have to change or add some #if directives to your program in
+order to make it work with Autoconf (see section Using @command{ifnames} to List Conditionals, for
+information about a program that can help with that job).
+
+
+
+When using @command{autoscan} to maintain a `configure.ac', simply
+consider adding its suggestions. The file `autoscan.log' will
+contain detailed information on why a macro is requested.
+
+
+
+@command{autoscan} uses several data files (installed along with Autoconf)
+to determine which macros to output when it finds particular symbols in
+a package's source files. These data files all have the same format:
+each line consists of a symbol, whitespace, and the Autoconf macro to
+output if that symbol is encountered. Lines starting with `#' are
+comments.
+
+
+
+@command{autoscan} accepts the following options:
+
+
+
+
+
@option{--help}
+
+
@option{-h}
+
+Print a summary of the command line options and exit.
+
+
@option{--version}
+
+
@option{-V}
+
+Print the version number of Autoconf and exit.
+
+
@option{--verbose}
+
+
@option{-v}
+
+Print the names of the files it examines and the potentially interesting
+symbols it finds in them. This output can be voluminous.
+
+
@option{--include=dir}
+
+
@option{-I dir}
+
+Also look for input files in dir. Multiple invocations
+accumulate. Directories are browsed from last to first.
+
+@command{ifnames} can help you write `configure.ac' for a software
+package. It prints the identifiers that the package already uses in C
+preprocessor conditionals. If a package has already been set up to have
+some portability, @command{ifnames} can thus help you figure out what its
+@command{configure} needs to check for. It may help fill in some gaps in a
+`configure.ac' generated by @command{autoscan} (see section Using @command{autoscan} to Create @file{configure.ac}).
+
+
+
+@command{ifnames} scans all of the C source files named on the command line
+(or the standard input, if none are given) and writes to the standard
+output a sorted list of all the identifiers that appear in those files
+in #if, #elif, #ifdef, or #ifndef
+directives. It prints each identifier on a line, followed by a
+space-separated list of the files in which that identifier occurs.
+
+
+
+@command{ifnames} accepts the following options:
+
+
+
+
+
@option{--help}
+
+
@option{-h}
+
+Print a summary of the command line options and exit.
+
+
+To create @command{configure} from `configure.ac', run the
+@command{autoconf} program with no arguments. @command{autoconf} processes
+`configure.ac' with the m4 macro processor, using the
+Autoconf macros. If you give @command{autoconf} an argument, it reads that
+file instead of `configure.ac' and writes the configuration script
+to the standard output instead of to @command{configure}. If you give
+@command{autoconf} the argument @option{-}, it reads from the standard
+input instead of `configure.ac' and writes the configuration script
+to the standard output.
+
+
+
+The Autoconf macros are defined in several files. Some of the files are
+distributed with Autoconf; @command{autoconf} reads them first. Then it
+looks for the optional file `acsite.m4' in the directory that
+contains the distributed Autoconf macro files, and for the optional file
+`aclocal.m4' in the current directory. Those files can contain
+your site's or the package's own Autoconf macro definitions
+(see section Writing Autoconf Macros, for more information). If a macro is
+defined in more than one of the files that @command{autoconf} reads, the
+last definition it reads overrides the earlier ones.
+
+
+
+@command{autoconf} accepts the following options:
+
+
+
+
+
@option{--help}
+
+
@option{-h}
+
+Print a summary of the command line options and exit.
+
+
@option{--version}
+
+
@option{-V}
+
+Print the version number of Autoconf and exit.
+
+
@option{--verbose}
+
+
@option{-v}
+
+Report processing steps.
+
+
@option{--debug}
+
+
@option{-d}
+
+Don't remove the temporary files.
+
+
@option{--force}
+
+
@option{-f}
+
+Remake `configure' even if newer than its input files.
+
+
@option{--include=dir}
+
+
@option{-I dir}
+
+Also look for input files in dir. Multiple invocations
+accumulate. Directories are browsed from last to first.
+
+
@option{--output=file}
+
+
@option{-o file}
+
+Save output (script or trace) to file. The file @option{-} stands
+for the standard output.
+
+
@option{--warnings=category}
+
+
@option{-W category}
+
+
+Report the warnings related to category (which can actually be a
+comma separated list). See section Reporting Messages, macro
+AC_DIAGNOSE, for a comprehensive list of categories. Special
+values include:
+
+
+
+
`all'
+
+report all the warnings
+
+
`none'
+
+report none
+
+
`error'
+
+treats warnings as errors
+
+
`no-category'
+
+disable warnings falling into category
+
+
+Warnings about `syntax' are enabled by default, and the environment
+variable WARNINGS, a comma separated list of categories, is
+honored. @command{autoconf -W category} will actually
+behave as if you had run:
+
+
+
+autoconf --warnings=syntax,$WARNINGS,category
+
+
+If you want to disable @command{autoconf}'s defaults and WARNINGS,
+but (for example) enable the warnings about obsolete constructs, you
+would use @option{-W none,obsolete}.
+
+
+
+@command{autoconf} displays a back trace for errors, but not for
+warnings; if you want them, just pass @option{-W error}. For instance,
+on this `configure.ac':
+
+
+
+$ autoconf -Wcross
+configure.ac:8: warning: AC_TRY_RUN called without default \
+to allow cross compiling
+$ autoconf -Wcross,error
+configure.ac:8: error: AC_TRY_RUN called without default \
+to allow cross compiling
+acgeneral.m4:3044: AC_TRY_RUN is expanded from...
+configure.ac:2: INNER is expanded from...
+configure.ac:5: OUTER is expanded from...
+configure.ac:8: the top level
+
+
+
@option{--trace=macro[:format]}
+
+
@option{-t macro[:format]}
+
+Do not create the @command{configure} script, but list the calls to
+macro according to the format. Multiple @option{--trace}
+arguments can be used to list several macros. Multiple @option{--trace}
+arguments for a single macro are not cumulative; instead, you should
+just make format as long as needed.
+
+The format is a regular string, with newlines if desired, and
+several special escape codes. It defaults to `$f:$l:$n:$%'; see
+below for details on the format.
+
+
@option{--initialization}
+
+
@option{-i}
+
+By default, @option{--trace} does not trace the initialization of the
+Autoconf macros (typically the AC_DEFUN definitions). This
+results in a noticeable speedup, but can be disabled by this option.
+
+
+
+It is often necessary to check the content of a `configure.ac'
+file, but parsing it yourself is extremely fragile and error-prone. It
+is suggested that you rely upon @option{--trace} to scan
+`configure.ac'.
+
+
+
+The format of @option{--trace} can use the following special
+escapes:
+
+
+
+
+
`$$'
+
+The character `$'.
+
+
`$f'
+
+The filename from which macro is called.
+
+
`$l'
+
+The line number from which macro is called.
+
+
`$d'
+
+The depth of the macro call. This is an M4 technical detail that
+you probably don't want to know about.
+
+
`$n'
+
+The name of the macro.
+
+
`$num'
+
+The numth argument of the call to macro.
+
+
`$@'
+
+
`$sep@'
+
+
`${separator}@'
+
+All the arguments passed to macro, separated by the character
+sep or the string separator (`,' by default). Each
+argument is quoted, i.e. enclosed in a pair of square brackets.
+
+
`$*'
+
+
`$sep*'
+
+
`${separator}*'
+
+As above, but the arguments are not quoted.
+
+
`$%'
+
+
`$sep%'
+
+
`${separator}%'
+
+As above, but the arguments are not quoted, all new line characters in
+the arguments are smashed, and the default separator is `:'.
+
+The escape `$%' produces single-line trace outputs (unless you put
+newlines in the `separator'), while `$@' and `$*' do
+not.
+
+
+
+For instance, to find the list of variables that are substituted, use:
+
+
+
+
+A long separator can be used to improve the readability of complex
+structures, and to ease its parsing (for instance when no single
+character is suitable as a separator)):
+
+
+
+
+Installing the various components of the GNU Build System can be
+tedious: running @command{gettextize}, @command{automake} etc. in each
+directory. It may be needed either because some tools such as
+@command{automake} have been updated on your system, or because some of
+the sources such as `configure.ac' have been updated, or finally,
+simply in order to install the GNU Build System in a fresh tree.
+
+
+
+It runs @command{autoconf}, @command{autoheader}, @command{aclocal},
+@command{automake}, @command{libtoolize}, and @command{gettextize} (when
+appropriate) repeatedly to update the GNU Build System in specified
+directories, and their subdirectories (see section Configuring Other Packages in Subdirectories). By
+default, it only remakes those files that are older than their sources.
+
+
+
+If you install a new version of some tools, you can make
+@command{autoreconf} remake all of the files by giving it the
+@option{--force} option.
+
+
+
+See section Automatic Remaking, for `Makefile' rules to automatically
+remake @command{configure} scripts when their source files change. That
+method handles the timestamps of configuration header templates
+properly, but does not pass @option{--autoconf-dir=dir} or
+@option{--localdir=dir}.
+
+
+
+@command{autoreconf} accepts the following options:
+
+
+
+
+
@option{--help}
+
+
@option{-h}
+
+Print a summary of the command line options and exit.
+
+
@option{--version}
+
+
@option{-V}
+
+Print the version number of Autoconf and exit.
+
+
@option{--verbose}
+
+Print the name of each directory where @command{autoreconf} runs
+@command{autoconf} (and @command{autoheader}, if appropriate).
+
+
@option{--debug}
+
+
@option{-d}
+
+Don't remove the temporary files.
+
+
@option{--force}
+
+
@option{-f}
+
+Remake even `configure' scripts and configuration headers that are
+newer than their input files (`configure.ac' and, if present,
+`aclocal.m4').
+
+
@option{--install}
+
+
@option{-i}
+
+Copy missing auxiliary files. This option is similar to the option
+--add-missing in @command{automake}.
+
+
+Autoconf-generated @command{configure} scripts need some information about
+how to initialize, such as how to find the package's source files; and
+about the output files to produce. The following sections describe
+initialization and the creation of output files.
+
+
+
+
+
+Every @command{configure} script must call AC_INIT before doing
+anything else. The only other required macro is AC_OUTPUT
+(see section Outputting Files).
+
+
+
+
+Process any command-line arguments and perform various initializations
+and verifications.
+
+
+
+Set the name of the package and its version. These are
+typically used in @option{--version} support, including that of
+@command{configure}. The optional argument bug-report should be
+the email to which users should send bug reports. The package
+tarname differs from package: the latter designates the full
+package name (e.g., `GNU Autoconf'), while the latter is meant for
+distribution tar ball names (e.g., `autoconf'). It defaults to
+package once `GNU ' strip, lower cased, and all non
+alphanumeric character mapped onto `-'.
+
+
+
+It is preferable that these arguments be static, i.e., there should not
+be any shell computation, but they can be computed by M4. The following
+M4 macros (e.g., AC_PACKAGE_NAME), output variables (e.g.,
+PACKAGE_NAME), and preprocessor symbols (e.g.,
+PACKAGE_NAME) are then defined:
+
+
+
+The following macros manage version numbers for @command{configure}
+scripts. Using them is optional.
+
+
+
+
+
Macro:AC_PREREQ(version)
+
+
+
+Ensure that a recent enough version of Autoconf is being used. If the
+version of Autoconf being used to create @command{configure} is earlier
+than version, print an error message to the standard error output
+and do not create @command{configure}. For example:
+
+
+
+
+AC_PREREQ(2.53)
+
+
+
+This macro is the only macro that may be used before AC_INIT, but
+for consistency, you are invited not to do so.
+
+
+
+
+
+
Macro:AC_COPYRIGHT(copyright-notice)
+
+
+
+State that, in addition to the Free Software Foundation's copyright on
+the Autoconf macros, parts of your @command{configure} are covered by the
+copyright-notice.
+
+
+
+The copyright-notice will show up in both the head of
+@command{configure} and in `configure --version'.
+
+
+
+
+
+
Macro:AC_REVISION(revision-info)
+
+
+
+Copy revision stamp revision-info into the @command{configure}
+script, with any dollar signs or double-quotes removed. This macro lets
+you put a revision stamp from `configure.ac' into @command{configure}
+without RCS or cvs changing it when you check in
+@command{configure}. That way, you can determine easily which revision of
+`configure.ac' a particular @command{configure} corresponds to.
+
+
+
+For example, this line in `configure.ac':
+
+
+
+
+
+unique-file-in-source-dir is some file that is in the package's
+source directory; @command{configure} checks for this file's existence to
+make sure that the directory that it is told contains the source code in
+fact does. Occasionally people accidentally specify the wrong directory
+with @option{--srcdir}; this is a safety check. See section @command{configure} Invocation, for more information.
+
+
+
+
+Packages that do manual configuration or use the install program
+might need to tell @command{configure} where to find some other shell
+scripts by calling AC_CONFIG_AUX_DIR, though the default places
+it looks are correct for most cases.
+
+
+
+
+
Macro:AC_CONFIG_AUX_DIR(dir)
+
+
+Use the auxiliary build tools (e.g., `install-sh',
+`config.sub', `config.guess', Cygnus @command{configure},
+Automake and Libtool scripts etc.) that are in directory dir.
+These are auxiliary files used in configuration. dir can be
+either absolute or relative to `srcdir'. The default is
+`srcdir' or `srcdir/..' or
+`srcdir/../..', whichever is the first that contains
+`install-sh'. The other files are not checked for, so that using
+AC_PROG_INSTALL does not automatically require distributing the
+other auxiliary files. It checks for `install.sh' also, but that
+name is obsolete because some @command{make} have a rule that creates
+`install' from it if there is no `Makefile'.
+
+Every Autoconf script, e.g., `configure.ac', should finish by
+calling AC_OUTPUT. It is the macro that generates
+`config.status', which will create the `Makefile's and any
+other files resulting from configuration. The only required macro is
+AC_INIT (see section Finding @command{configure} Input).
+
+
+
+
+
Macro:AC_OUTPUT
+
+
+
+Generate `config.status' and launch it. Call this macro once, at
+the end of `configure.ac'.
+
+
+
+Historically, the usage of AC_OUTPUT was somewhat different.
+See section Obsolete Macros, for a description of the arguments that
+AC_OUTPUT used to support.
+
+
+
+If you run make on subdirectories, you should run it using the
+make variable MAKE. Most versions of make set
+MAKE to the name of the make program plus any options it
+was given. (But many do not include in it the values of any variables
+set on the command line, so those are not passed on automatically.)
+Some old versions of make do not set this variable. The
+following macro allows you to use it even with those versions.
+
+
+
+
+
Macro:AC_PROG_MAKE_SET
+
+
+
+If make predefines the variable MAKE, define output
+variable SET_MAKE to be empty. Otherwise, define SET_MAKE
+to contain `MAKE=make'. Calls AC_SUBST for SET_MAKE.
+
+
+
+
+To use this macro, place a line like this in each `Makefile.in'
+that runs MAKE on other directories:
+
+
+
+
+`configure' is designed so that it appears to do everything itself,
+but there is actually a hidden slave: `config.status'.
+`configure' is in charge of examining your system, but it is
+`config.status' that actually takes the proper actions based on the
+results of `configure'. The most typical task of
+`config.status' is to instantiate files.
+
+
+
+This section describes the common behavior of the four standard
+instantiating macros: AC_CONFIG_FILES, AC_CONFIG_HEADERS,
+AC_CONFIG_COMMANDS and AC_CONFIG_LINKS. They all
+have this prototype:
+
+
+
+
+A whitespace-separated list of tags, which are typically the names of
+the files to instantiate.
+
+You are encouraged to use literals as tags. In particular, you
+should avoid
+
+
+
+
+The macros AC_CONFIG_FILES and AC_CONFIG_HEADERS use
+special tags: they may have the form `output' or
+`output:inputs'. The file output is instantiated
+from its templates, inputs (defaulting to `output.in').
+
+For instance
+`AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk)' asks for
+the creation of `Makefile' that will be the expansion of the
+output variables in the concatenation of `boiler/top.mk' and
+`boiler/bot.mk'.
+
+The special value `-' might be used to denote the standard output
+when used in output, or the standard input when used in the
+inputs. You most probably don't need to use this in
+`configure.ac', but it is convenient when using the command line
+interface of `./config.status', see section Recreating a Configuration,
+for more details.
+
+The inputs may be absolute or relative filenames. In the latter
+case they are first looked for in the build tree, and then in the source
+tree.
+
+
commands
+
+Shell commands output literally into `config.status', and
+associated with a tag that the user can use to tell `config.status'
+which the commands to run. The commands are run each time a tag
+request is given to `config.status'; typically, each time the file
+`tag' is created.
+
+The variable set during the execution of @command{configure} are
+not available here: you first need to set them via the
+init-cmds. Nonetheless the following variables are precomputed:
+
+
+
+
srcdir
+
+The path from the top build directory to the top source directory. This
+is what @command{configure}'s option @option{--srcdir} sets.
+
+
ac_top_srcdir
+
+The path from the current build directory to the top source directory.
+
+
ac_top_builddir
+
+The path from the current build directory to the top build directory.
+It can be empty, or else ends with a slash, so that you may concatenate
+it.
+
+
ac_srcdir
+
+The path from the current build directory to the corresponding source
+directory.
+
+
+The current directory refers to the directory (or
+pseudo-directory) containing the input part of tags. For
+instance, running
+
+
+
+
+ with @option{--srcdir=../package} produces the following values:
+
+
+
+# Argument of --srcdir
+srcdir='../package'
+# Reversing deep/dir
+ac_top_builddir='../../'
+# Concatenation of $ac_top_builddir and srcdir
+ac_top_srcdir='../../../package'
+# Concatenation of $ac_top_srcdir and deep/dir
+ac_srcdir='../../../package/deep/dir'
+
+
+independently of `in/in.in'.
+
+
init-cmds
+
+Shell commands output unquoted near the beginning of
+`config.status', and executed each time `config.status' runs
+(regardless of the tag). Because they are unquoted, for example,
+`$var' will be output as the value of var. init-cmds
+is typically used by `configure' to give `config.status' some
+variables it needs to run the commands.
+
+You should be extremely cautious in your variable names: all the
+init-cmds share the same name space and may overwrite each other
+in unpredictable ways. Sorry...
+
+
+
+All these macros can be called multiple times, with different
+tags, of course!
+
+
+
+
+
+
+Make AC_OUTPUT create each `file' by copying an input
+file (by default `file.in'), substituting the output variable
+values.
+This macro is one of the instantiating macros, see section Taking Configuration Actions. See section Substitutions in Makefiles, for more information on using
+output variables. See section Setting Output Variables, for more information
+on creating them. This macro creates the directory that the file is in
+if it doesn't exist. Usually, `Makefile's are created this way,
+but other files, such as `.gdbinit', can be specified as well.
+
+
+
+Typical calls to AC_CONFIG_FILES look like this:
+
+
+
+
+Each subdirectory in a distribution that contains something to be
+compiled or installed should come with a file `Makefile.in', from
+which @command{configure} will create a `Makefile' in that directory.
+To create a `Makefile', @command{configure} performs a simple variable
+substitution, replacing occurrences of `@variable@' in
+`Makefile.in' with the value that @command{configure} has determined
+for that variable. Variables that are substituted into output files in
+this way are called output variables. They are ordinary shell
+variables that are set in @command{configure}. To make @command{configure}
+substitute a particular variable into the output files, the macro
+AC_SUBST must be called with that variable name as an argument.
+Any occurrences of `@variable@' for other variables are
+left unchanged. See section Setting Output Variables, for more information
+on creating output variables with AC_SUBST.
+
+
+
+A software package that uses a @command{configure} script should be
+distributed with a file `Makefile.in', but no `Makefile'; that
+way, the user has to properly configure the package for the local system
+before compiling it.
+
+
+
+See section `Makefile Conventions' in The GNU Coding Standards, for more information on what to put in
+`Makefile's.
+
+
+
+
+
+Some output variables are preset by the Autoconf macros. Some of the
+Autoconf macros set additional output variables, which are mentioned in
+the descriptions for those macros. See section Output Variable Index, for a
+complete list of output variables. See section Installation Directory Variables, for the list of the preset ones related to installation
+directories. Below are listed the other preset ones. They all are
+precious variables (see section Setting Output Variables,
+AC_ARG_VAR).
+
+
+
+
+
Variable:CFLAGS
+
+
+Debugging and optimization options for the C compiler. If it is not set
+in the environment when @command{configure} runs, the default value is set
+when you call AC_PROG_CC (or empty if you don't). @command{configure}
+uses this variable when compiling programs to test for C features.
+
+
+
+
+
+
Variable:configure_input
+
+
+A comment saying that the file was generated automatically by
+@command{configure} and giving the name of the input file.
+AC_OUTPUT adds a comment line containing this variable to the top
+of every `Makefile' it creates. For other files, you should
+reference this variable in a comment at the top of each input file. For
+example, an input shell script should begin like this:
+
+
+
+
+#! /bin/sh
+# @configure_input@
+
+
+
+The presence of that line also reminds people editing the file that it
+needs to be processed by @command{configure} in order to be used.
+
+
+
+
+
+
Variable:CPPFLAGS
+
+
+Header file search directory (@option{-Idir}) and any other
+miscellaneous options for the C and C++ preprocessors and compilers. If
+it is not set in the environment when @command{configure} runs, the default
+value is empty. @command{configure} uses this variable when compiling or
+preprocessing programs to test for C and C++ features.
+
+
+
+
+
+
Variable:CXXFLAGS
+
+
+Debugging and optimization options for the C++ compiler. If it is not
+set in the environment when @command{configure} runs, the default value is
+set when you call AC_PROG_CXX (or empty if you don't).
+@command{configure} uses this variable when compiling programs to test for
+C++ features.
+
+
+
+
+
+
Variable:DEFS
+
+
+@option{-D} options to pass to the C compiler. If AC_CONFIG_HEADERS
+is called, @command{configure} replaces `@DEFS@' with
+@option{-DHAVE_CONFIG_H} instead (see section Configuration Header Files). This
+variable is not defined while @command{configure} is performing its tests,
+only when creating the output files. See section Setting Output Variables, for
+how to check the results of previous tests.
+
+
+
+
+
+
Variable:ECHO_C
+
+
Variable:ECHO_N
+
+
Variable:ECHO_T
+
+
+
+
+How does one suppress the trailing newline from echo for
+question-answer message pairs? These variables provide a way:
+
+
+
+
+Some old and uncommon echo implementations offer no means to
+achieve this, in which case ECHO_T is set to tab. You might not
+want to use it.
+
+
+
+
+
+
Variable:FFLAGS
+
+
+Debugging and optimization options for the Fortran 77 compiler. If it
+is not set in the environment when @command{configure} runs, the default
+value is set when you call AC_PROG_F77 (or empty if you don't).
+@command{configure} uses this variable when compiling programs to test for
+Fortran 77 features.
+
+
+
+
+
+
Variable:LDFLAGS
+
+
+Stripping (@option{-s}), path (@option{-L}), and any other miscellaneous
+options for the linker. Don't use this variable to pass library names
+(@option{-l}) to the linker, use LIBS instead. If it is not set
+in the environment when @command{configure} runs, the default value is empty.
+@command{configure} uses this variable when linking programs to test for
+C, C++ and Fortran 77 features.
+
+
+
+
+
+
Variable:LIBS
+
+
+@option{-l} options to pass to the linker. The default value is empty,
+but some Autoconf macros may prepend extra libraries to this variable if
+those libraries are found and provide necessary functions, see
+section Library Files. @command{configure} uses this variable when linking
+programs to test for C, C++ and Fortran 77 features.
+
+
+
+
+
+
Variable:builddir
+
+
+Rigorously equal to `.'. Added for symmetry only.
+
+
+
+
+
+
Variable:abs_builddir
+
+
+Absolute path of builddir.
+
+
+
+
+
+
Variable:top_builddir
+
+
+The relative path to the top-level of the current build tree. In the
+top-level directory, this is the same as srcbuild.
+
+
+
+
+
+
Variable:abs_top_builddir
+
+
+Absolute path of top_builddir.
+
+
+
+
+
+
Variable:srcdir
+
+
+The relative path to the directory that contains the source code for
+that `Makefile'.
+
+
+
+
+
+
Variable:abs_srcdir
+
+
+Absolute path of srcdir.
+
+
+
+
+
+
Variable:top_srcdir
+
+
+The relative path to the top-level source code directory for the
+package. In the top-level directory, this is the same as srcdir.
+
+The following variables specify the directories where the package will
+be installed, see section `Variables for Installation Directories' in The GNU Coding Standards, for more information.
+See the end of this section for details on when and how to use these
+variables.
+
+
+
+
+
Variable:bindir
+
+
+The directory for installing executables that users run.
+
+
+
+
+
+
Variable:datadir
+
+
+The directory for installing read-only architecture-independent data.
+
+
+
+
+
+
Variable:exec_prefix
+
+
+The installation prefix for architecture-dependent files. By default
+it's the same as prefix. You should avoid installing anything
+directly to exec_prefix. However, the default value for
+directories containing architecture-dependent files should be relative
+to exec_prefix.
+
+
+
+
+
+
Variable:includedir
+
+
+The directory for installing C header files.
+
+
+
+
+
+
Variable:infodir
+
+
+The directory for installing documentation in Info format.
+
+
+
+
+
+
Variable:libdir
+
+
+The directory for installing object code libraries.
+
+
+
+
+
+
Variable:libexecdir
+
+
+The directory for installing executables that other programs run.
+
+
+
+
+
+
Variable:localstatedir
+
+
+The directory for installing modifiable single-machine data.
+
+
+
+
+
+
Variable:mandir
+
+
+The top-level directory for installing documentation in man format.
+
+
+
+
+
+
Variable:oldincludedir
+
+
+The directory for installing C header files for non-gcc compilers.
+
+
+
+
+
+
Variable:prefix
+
+
+The common installation prefix for all files. If exec_prefix
+is defined to a different value, prefix is used only for
+architecture-independent files.
+
+
+
+
+
+
Variable:sbindir
+
+
+The directory for installing executables that system
+administrators run.
+
+
+
+
+
+
Variable:sharedstatedir
+
+
+The directory for installing modifiable architecture-independent data.
+
+
+
+
+
+
Variable:sysconfdir
+
+
+The directory for installing read-only single-machine data.
+
+
+
+
+Most of these variables have values that rely on prefix or
+exec_prefix. It is deliberate that the directory output
+variables keep them unexpanded: typically `@datadir@' will be
+replaced by `${prefix}/share', not `/usr/local/share'.
+
+
+
+This behavior is mandated by the GNU coding standards, so that when
+the user runs:
+
+
+
+
+
`make'
+
+she can still specify a different prefix from the one specified to
+@command{configure}, in which case, if needed, the package shall hard
+code dependencies corresponding to the make-specified prefix.
+
+
`make install'
+
+she can specify a different installation location, in which case the
+package must still depend on the location which was compiled in
+(i.e., never recompile when `make install' is run). This is an
+extremely important feature, as many people may decide to install all
+the files of a package grouped together, and then install links from
+the final locations to there.
+
+
+
+In order to support these features, it is essential that datadir
+remains being defined as `${prefix}/share' to depend upon the
+current value of prefix.
+
+
+
+A corollary is that you should not use these variables except in
+Makefiles. For instance, instead of trying to evaluate datadir
+in `configure' and hardcoding it in Makefiles using
+e.g. `AC_DEFINE_UNQUOTED(DATADIR, "$datadir")', you should add
+`-DDATADIR="$(datadir)"' to your CPPFLAGS.
+
+
+
+Similarly you should not rely on AC_OUTPUT_FILES to replace
+datadir and friends in your shell scripts and other files, rather
+let @command{make} manage their replacement. For instance Autoconf
+ships templates of its shell scripts ending with `.sh', and uses
+this Makefile snippet:
+
+
+
+
+You can support compiling a software package for several architectures
+simultaneously from the same copy of the source code. The object files
+for each architecture are kept in their own directory.
+
+
+
+To support doing this, make uses the VPATH variable to
+find the files that are in the source directory. GNU make
+and most other recent make programs can do this. Older
+make programs do not support VPATH; when using them, the
+source code must be in the same directory as the object files.
+
+
+
+To support VPATH, each `Makefile.in' should contain two
+lines that look like:
+
+
+
+
+srcdir = @srcdir@
+VPATH = @srcdir@
+
+
+
+Do not set VPATH to the value of another variable, for example
+`VPATH = $(srcdir)', because some versions of make do not do
+variable substitutions on the value of VPATH.
+
+
+
+@command{configure} substitutes in the correct value for srcdir when
+it produces `Makefile'.
+
+
+
+Do not use the make variable $<, which expands to the
+file name of the file in the source directory (found with VPATH),
+except in implicit rules. (An implicit rule is one such as `.c.o',
+which tells how to create a `.o' file from a `.c' file.) Some
+versions of make do not set $< in explicit rules; they
+expand it to an empty value.
+
+
+
+Instead, `Makefile' command lines should always refer to source
+files by prefixing them with `$(srcdir)/'. For example:
+
+
+
+
+You can put rules like the following in the top-level `Makefile.in'
+for a package to automatically update the configuration information when
+you change the configuration files. This example includes all of the
+optional files, such as `aclocal.m4' and those related to
+configuration header files. Omit from the `Makefile.in' rules for
+any of these files that your package does not use.
+
+
+
+The `$(srcdir)/' prefix is included because of limitations in the
+VPATH mechanism.
+
+
+
+The `stamp-' files are necessary because the timestamps of
+`config.h.in' and `config.h' will not be changed if remaking
+them does not change their contents. This feature avoids unnecessary
+recompilation. You should include the file `stamp-h.in' your
+package's distribution, so @command{make} will consider
+`config.h.in' up to date. Don't use @command{touch}
+(see section Limitations of Usual Tools), rather use @command{echo} (using
+@command{date} would cause needless differences, hence CVS
+conflicts etc.).
+
+
+
+
+(Be careful if you copy these lines directly into your Makefile, as you
+will need to convert the indented lines to start with the tab character.)
+
+
+
+In addition, you should use `AC_CONFIG_FILES([stamp-h], [echo
+timestamp > stamp-h])' so `config.status' will ensure that
+`config.h' is considered up to date. See section Outputting Files, for more
+information about AC_OUTPUT.
+
+
+
+See section Recreating a Configuration, for more examples of handling
+configuration-related dependencies.
+
+
+
+
+
+When a package tests more than a few C preprocessor symbols, the command
+lines to pass @option{-D} options to the compiler can get quite long.
+This causes two problems. One is that the make output is hard to
+visually scan for errors. More seriously, the command lines can exceed
+the length limits of some operating systems. As an alternative to
+passing @option{-D} options to the compiler, @command{configure} scripts can
+create a C header file containing `#define' directives. The
+AC_CONFIG_HEADERS macro selects this kind of output. It should
+be called right after AC_INIT.
+
+
+
+The package should `#include' the configuration header file before
+any other header files, to prevent inconsistencies in declarations (for
+example, if it redefines const). Use `#include <config.h>'
+instead of `#include "config.h"', and pass the C compiler a
+@option{-I.} option (or @option{-I..}; whichever directory contains
+`config.h'). That way, even if the source directory is configured
+itself (perhaps to make a distribution), other build directories can
+also be configured without finding the `config.h' from the source
+directory.
+
+
+
+
+
+This macro is one of the instantiating macros, see section Taking Configuration Actions. Make AC_OUTPUT create the file(s) in the
+whitespace-separated list header containing C preprocessor
+#define statements, and replace `@DEFS@' in generated
+files with @option{-DHAVE_CONFIG_H} instead of the value of DEFS.
+The usual name for header is `config.h'.
+
+
+
+If header already exists and its contents are identical to what
+AC_OUTPUT would put in it, it is left alone. Doing this allows
+some changes in configuration without needlessly causing object files
+that depend on the header file to be recompiled.
+
+
+
+Usually the input file is named `header.in'; however, you can
+override the input file name by appending to header, a
+colon-separated list of input files. Examples:
+
+
+
+
+Your distribution should contain a template file that looks as you want
+the final header file to look, including comments, with #undef
+statements which are used as hooks. For example, suppose your
+`configure.ac' makes these calls:
+
+
+
+
+Then you could have code like the following in `conf.h.in'. On
+systems that have `unistd.h', @command{configure} will `#define'
+`HAVE_UNISTD_H' to 1. On other systems, the whole line will be
+commented out (in case the system predefines that symbol).
+
+
+
+
+/* Define as 1 if you have unistd.h. */
+#undef HAVE_UNISTD_H
+
+
+
+You can then decode the configuration header using the preprocessor
+directives:
+
+
+
+
+#include <conf.h>
+
+#if HAVE_UNISTD_H
+# include <unistd.h>
+#else
+/* We are in trouble. */
+#endif
+
+
+
+The use of old form templates, with `#define' instead of
+`#undef' is strongly discouraged.
+
+
+
+The @command{autoheader} program can create a template file of C
+`#define' statements for @command{configure} to use. If
+`configure.ac' invokes AC_CONFIG_HEADERS(file),
+@command{autoheader} creates `file.in'; if multiple file
+arguments are given, the first one is used. Otherwise,
+@command{autoheader} creates `config.h.in'.
+
+
+
+In order to do its job, @command{autoheader} needs you to document all
+of the symbols that you might use; i.e., there must be at least one
+AC_DEFINE or one AC_DEFINE_UNQUOTED using its third
+argument for each symbol (see section Defining C Preprocessor Symbols). An additional
+constraint is that the first argument of AC_DEFINE must be a
+literal. Note that all symbols defined by Autoconf's built-in tests are
+already documented properly; you only need to document those that you
+define yourself.
+
+
+
+You might wonder why @command{autoheader} is needed: after all, why
+would @command{configure} need to "patch" a `config.h.in' to
+produce a `config.h' instead of just creating `config.h' from
+scratch? Well, when everything rocks, the answer is just that we are
+wasting our time maintaining @command{autoheader}: generating
+`config.h' directly is all that is needed. When things go wrong,
+however, you'll be thankful for the existence of @command{autoheader}.
+
+
+
+The fact that the symbols are documented is important in order to
+check that `config.h' makes sense. The fact that there is a
+well defined list of symbols that should be #define'd (or not) is
+also important for people who are porting packages to environments where
+@command{configure} cannot be run: they just have to @emph{fill in the
+blanks}.
+
+
+
+But let's come back to the point: @command{autoheader}'s invocation...
+
+
+
+If you give @command{autoheader} an argument, it uses that file instead
+of `configure.ac' and writes the header file to the standard output
+instead of to `config.h.in'. If you give @command{autoheader} an
+argument of @option{-}, it reads the standard input instead of
+`configure.ac' and writes the header file to the standard output.
+
+
+
+@command{autoheader} accepts the following options:
+
+
+
+
+
@option{--help}
+
+
@option{-h}
+
+Print a summary of the command line options and exit.
+
+
@option{--version}
+
+
@option{-V}
+
+Print the version number of Autoconf and exit.
+
+
@option{--verbose}
+
+
@option{-v}
+
+Report processing steps.
+
+
@option{--debug}
+
+
@option{-d}
+
+Don't remove the temporary files.
+
+
@option{--force}
+
+
@option{-f}
+
+Remake the template file even if newer than its input files.
+
+
@option{--include=dir}
+
+
@option{-I dir}
+
+Also look for input files in dir. Multiple invocations accumulate.
+Directories are browsed from last to first.
+
+
@option{--warnings=category}
+
+
@option{-W category}
+
+
+Report the warnings related to category (which can actually be a
+comma separated list). Current categories include:
+
+
+@command{autoheader} scans `configure.ac' and figures out which C
+preprocessor symbols it might define. It knows how to generate
+templates for symbols defined by AC_CHECK_HEADERS,
+AC_CHECK_FUNCS etc., but if you AC_DEFINE any additional
+symbol, you must define a template for it. If there are missing
+templates, @command{autoheader} fails with an error message.
+
+
+
+The simplest way to create a template for a symbol is to supply
+the description argument to an `AC_DEFINE(symbol)'; see
+section Defining C Preprocessor Symbols. You may also use one of the following macros.
+
+
+
+
+
Macro:AH_VERBATIM(key, template)
+
+
+
+Tell @command{autoheader} to include the template as-is in the header
+template file. This template is associated with the key,
+which is used to sort all the different templates and guarantee their
+uniqueness. It should be the symbol that can be AC_DEFINE'd.
+
+
+
+For example:
+
+
+
+
+AH_VERBATIM([_GNU_SOURCE],
+[/* Enable GNU extensions on systems that have them. */
+#ifndef _GNU_SOURCE
+# define _GNU_SOURCE
+#endif])
+
+
+
+
+
+
+
Macro:AH_TEMPLATE(key, description)
+
+
+
+Tell @command{autoheader} to generate a template for key. This macro
+generates standard templates just like AC_DEFINE when a
+description is given.
+
+
+
+For example:
+
+
+
+
+AH_TEMPLATE([CRAY_STACKSEG_END],
+ [Define to one of _getb67, GETB67, getb67
+ for Cray-2 and Cray-YMP systems. This
+ function is required for alloca.c support
+ on those systems.])
+
+
+
+will generate the following template, with the description properly
+justified.
+
+
+
+
+/* Define to one of _getb67, GETB67, getb67 for Cray-2 and
+ Cray-YMP systems. This function is required for alloca.c
+ support on those systems. */
+#undef CRAY_STACKSEG_END
+
+
+
+
+
+
+
Macro:AH_TOP(text)
+
+
+
+Include text at the top of the header template file.
+
+
+
+
+
+
Macro:AH_BOTTOM(text)
+
+
+
+Include text at the bottom of the header template file.
+
+You execute arbitrary commands either before, during and after
+`config.status' is run. The three following macros accumulate the
+commands to run when they are called multiple times.
+AC_CONFIG_COMMANDS replaces the obsolete macro
+AC_OUTPUT_COMMANDS, see section Obsolete Macros, for details.
+
+
+
+
+Specify additional shell commands to run at the end of
+`config.status', and shell commands to initialize any variables
+from @command{configure}. Associate the commands to the tag. Since
+typically the cmds create a file, tag should naturally be
+the name of that file. This macro is one of the instantiating macros,
+see section Taking Configuration Actions.
+
+
+
+Here is an unrealistic example:
+
+
+fubar=42
+AC_CONFIG_COMMANDS([fubar],
+ [echo this is extra $fubar, and so on.],
+ [fubar=$fubar])
+
+
+Execute the cmds right before creating `config.status'. A
+typical use is computing values derived from variables built during the
+execution of @command{configure}:
+
+
+
+
+AC_CONFIG_COMMANDS_PRE(
+[LTLIBOBJS=`echo $LIBOBJS | sed 's/\.o/\.lo/g'`
+AC_SUBST(LTLIBOBJS)])
+
+
+
+
+
+
+
Macro:AC_CONFIG_COMMANDS_POST(cmds)
+
+
+Execute the cmds right after creating `config.status'.
+
+You may find it convenient to create links whose destinations depend upon
+results of tests. One can use AC_CONFIG_COMMANDS but the
+creation of relative symbolic links can be delicate when the package is
+built in another directory than its sources.
+
+
+
+
+
+Make AC_OUTPUT link each of the existing files source to
+the corresponding link name dest. Makes a symbolic link if
+possible, otherwise a hard link. The dest and source names
+should be relative to the top level source or build directory. This
+macro is one of the instantiating macros, see section Taking Configuration Actions.
+
+
+
+In most situations, calling AC_OUTPUT is sufficient to produce
+`Makefile's in subdirectories. However, @command{configure} scripts
+that control more than one independent package can use
+AC_CONFIG_SUBDIRS to run @command{configure} scripts for other
+packages in subdirectories.
+
+
+
+
+
Macro:AC_CONFIG_SUBDIRS(dir ...)
+
+
+
+Make AC_OUTPUT run @command{configure} in each subdirectory
+dir in the given whitespace-separated list. Each dir should
+be a literal, i.e., please do not use:
+
+
+
+
+if test "$package_foo_enabled" = yes; then
+ $my_subdirs="$my_subdirs foo"
+fi
+AC_CONFIG_SUBDIRS($my_subdirs)
+
+
+
+because this prevents `./configure --help=recursive' from
+displaying the options of the package foo. Rather, you should
+write:
+
+
+
+
+if test "$package_foo_enabled" = yes; then
+ AC_CONFIG_SUBDIRS(foo)
+fi
+
+
+
+If a given dir is not found, an error is reported: if the
+subdirectory is optional, write:
+
+
+
+
+if test -d $srcdir/foo; then
+ AC_CONFIG_SUBDIRS(foo)
+fi
+
+
+
+If a given dir contains @command{configure.gnu}, it is run instead
+of @command{configure}. This is for packages that might use a
+non-autoconf script @command{Configure}, which can't be called through a
+wrapper @command{configure} since it would be the same file on
+case-insensitive filesystems. Likewise, if a dir contains
+`configure.ac' but no @command{configure}, the Cygnus
+@command{configure} script found by AC_CONFIG_AUX_DIR is used.
+
+
+
+The subdirectory @command{configure} scripts are given the same command
+line options that were given to this @command{configure} script, with minor
+changes if needed, which include:
+
+
+
+
+
+
+adjusting a relative path for the cache file;
+
+
+
+adjusting a relative path for the source directory;
+
+
+
+propagating the current value of $prefix, including if it was
+defaulted, and if default values of the top level and of sub directory
+`configure' differ.
+
+
+
+This macro also sets the output variable subdirs to the list of
+directories `dir ...'. `Makefile' rules can use
+this variable to determine which subdirectories to recurse into. This
+macro may be called multiple times.
+
+By default, @command{configure} sets the prefix for files it installs to
+`/usr/local'. The user of @command{configure} can select a different
+prefix using the @option{--prefix} and @option{--exec-prefix} options.
+There are two ways to change the default: when creating
+@command{configure}, and when running it.
+
+
+
+Some software packages might want to install in a directory besides
+`/usr/local' by default. To accomplish that, use the
+AC_PREFIX_DEFAULT macro.
+
+
+
+
+
Macro:AC_PREFIX_DEFAULT(prefix)
+
+
+Set the default installation prefix to prefix instead of
+`/usr/local'.
+
+
+
+
+It may be convenient for users to have @command{configure} guess the
+installation prefix from the location of a related program that they
+have already installed. If you wish to do that, you can call
+AC_PREFIX_PROGRAM.
+
+
+
+
+
Macro:AC_PREFIX_PROGRAM(program)
+
+
+If the user did not specify an installation prefix (using the
+@option{--prefix} option), guess a value for it by looking for
+program in PATH, the way the shell does. If program
+is found, set the prefix to the parent of the directory containing
+program; otherwise leave the prefix specified in
+`Makefile.in' unchanged. For example, if program is
+gcc and the PATH contains `/usr/local/gnu/bin/gcc',
+set the prefix to `/usr/local/gnu'.
+
+These macros test for particular system features that packages might
+need or want to use. If you need to test for a kind of feature that
+none of these macros check for, you can probably do it by calling
+primitive test macros with appropriate arguments (see section Writing Tests).
+
+
+
+These tests print messages telling the user which feature they're
+checking for, and what they find. They cache their results for future
+@command{configure} runs (see section Caching Results).
+
+
+
+Some of these macros set output variables. See section Substitutions in Makefiles, for how to get their values. The phrase "define
+name" is used below as a shorthand to mean "define C
+preprocessor symbol name to the value 1". See section Defining C Preprocessor Symbols, for how to get those symbol definitions into your program.
+
+
+
+
+
+Much effort has been expended to make Autoconf easy to learn. The most
+obvious way to reach this goal is simply to enforce standard interfaces
+and behaviors, avoiding exceptions as much as possible. Because of
+history and inertia, unfortunately, there are still too many exceptions
+in Autoconf; nevertheless, this section describes some of the common
+rules.
+
+
+
+
+
+All the generic macros that AC_DEFINE a symbol as a result of
+their test transform their arguments to a standard alphabet.
+First, argument is converted to upper case and any asterisks
+(`*') are each converted to `P'. Any remaining characters
+that are not alphanumeric are converted to underscores.
+
+
+
+For instance,
+
+
+
+
+AC_CHECK_TYPES(struct $Expensive*)
+
+
+
+will define the symbol `HAVE_STRUCT__EXPENSIVEP' if the check
+succeeds.
+
+
+
+
+
+Several tests depend upon a set of header files. Since these headers
+are not universally available, tests actually have to provide a set of
+protected includes, such as:
+
+
+
+
+#if TIME_WITH_SYS_TIME
+# include <sys/time.h>
+# include <time.h>
+#else
+# if HAVE_SYS_TIME_H
+# include <sys/time.h>
+# else
+# include <time.h>
+# endif
+#endif
+
+
+
+Unless you know exactly what you are doing, you should avoid using
+unconditional includes, and check the existence of the headers you
+include beforehand (see section Header Files).
+
+
+
+Most generic macros provide the following default set of includes:
+
+
+
+
+#include <stdio.h>
+#if HAVE_SYS_TYPES_H
+# include <sys/types.h>
+#endif
+#if HAVE_SYS_STAT_H
+# include <sys/stat.h>
+#endif
+#if STDC_HEADERS
+# include <stdlib.h>
+# include <stddef.h>
+#else
+# if HAVE_STDLIB_H
+# include <stdlib.h>
+# endif
+#endif
+#if HAVE_STRING_H
+# if !STDC_HEADERS && HAVE_MEMORY_H
+# include <memory.h>
+# endif
+# include <string.h>
+#endif
+#if HAVE_STRINGS_H
+# include <strings.h>
+#endif
+#if HAVE_INTTYPES_H
+# include <inttypes.h>
+#else
+# if HAVE_STDINT_H
+# include <stdint.h>
+# endif
+#endif
+#if HAVE_UNISTD_H
+# include <unistd.h>
+#endif
+
+
+
+If the default includes are used, then Autoconf will automatically check
+for the presence of these headers and their compatibility, i.e., you
+don't need to run AC_HEADERS_STDC, nor check for `stdlib.h'
+etc.
+
+
+
+These headers are checked for in the same order as they are included.
+For instance, on some systems `string.h' and `strings.h' both
+exist, but conflict. Then HAVE_STRING_H will be defined, but
+HAVE_STRINGS_H won't.
+
+
+
+
+
+These macros check for the presence or behavior of particular programs.
+They are used to choose between several alternative programs and to
+decide what to do once one has been chosen. If there is no macro
+specifically defined to check for a program you need, and you don't need
+to check for any special properties of it, then you can use one of the
+general program-check macros.
+
+
+
+
+
+These macros check for particular programs--whether they exist, and
+in some cases whether they support certain features.
+
+
+
+
+
Macro:AC_PROG_AWK
+
+
+
+Check for gawk, mawk, nawk, and awk, in that
+order, and set output variable AWK to the first one that is found.
+It tries gawk first because that is reported to be the
+best implementation.
+
+
+
+
+
+
Macro:AC_PROG_INSTALL
+
+
+
+
+
+
+Set output variable INSTALL to the path of a BSD compatible
+install program, if one is found in the current PATH.
+Otherwise, set INSTALL to `dir/install-sh -c',
+checking the directories specified to AC_CONFIG_AUX_DIR (or its
+default directories) to determine dir (see section Outputting Files). Also set
+the variables INSTALL_PROGRAM and INSTALL_SCRIPT to
+`${INSTALL}' and INSTALL_DATA to `${INSTALL} -m 644'.
+
+
+
+This macro screens out various instances of install known not to
+work. It prefers to find a C program rather than a shell script, for
+speed. Instead of `install-sh', it can also use `install.sh',
+but that name is obsolete because some make programs have a rule
+that creates `install' from it if there is no `Makefile'.
+
+
+
+Autoconf comes with a copy of `install-sh' that you can use. If
+you use AC_PROG_INSTALL, you must include either
+`install-sh' or `install.sh' in your distribution, or
+@command{configure} will produce an error message saying it can't find
+them--even if the system you're on has a good install program.
+This check is a safety measure to prevent you from accidentally leaving
+that file out, which would prevent your package from installing on
+systems that don't have a BSD-compatible install program.
+
+
+
+If you need to use your own installation program because it has features
+not found in standard install programs, there is no reason to use
+AC_PROG_INSTALL; just put the file name of your program into your
+`Makefile.in' files.
+
+
+
+
+
+
Macro:AC_PROG_LEX
+
+
+
+
+
+
+If flex is found, set output variable LEX to `flex'
+and LEXLIB to @option{-lfl}, if that library is in a standard
+place. Otherwise set LEX to `lex' and LEXLIB to
+@option{-ll}.
+
+
+
+Define YYTEXT_POINTER if yytext is a `char *' instead
+of a `char []'. Also set output variable LEX_OUTPUT_ROOT to
+the base of the file name that the lexer generates; usually
+`lex.yy', but sometimes something else. These results vary
+according to whether lex or flex is being used.
+
+
+
+You are encouraged to use Flex in your sources, since it is both more
+pleasant to use than plain Lex and the C source it produces is portable.
+In order to ensure portability, however, you must either provide a
+function yywrap or, if you don't use it (e.g., your scanner has
+no `#include'-like feature), simply include a `%noyywrap'
+statement in the scanner's source. Once this done, the scanner is
+portable (unless you felt free to use nonportable constructs) and
+does not depend on any library. In this case, and in this case only, it
+is suggested that you use this Autoconf snippet:
+
+
+
+
+AC_PROG_LEX
+if test "$LEX" != flex; then
+ LEX="$SHELL $missing_dir/missing flex"
+ AC_SUBST(LEX_OUTPUT_ROOT, lex.yy)
+ AC_SUBST(LEXLIB, '')
+fi
+
+
+
+The shell script @command{missing} can be found in the Automake
+distribution.
+
+
+
+To ensure backward compatibility, Automake's AM_PROG_LEX invokes
+(indirectly) this macro twice, which will cause an annoying but benign
+"AC_PROG_LEX invoked multiple times" warning. Future versions
+of Automake will fix this issue, meanwhile, just ignore this message.
+
+
+
+
+
+
Macro:AC_PROG_LN_S
+
+
+
+If `ln -s' works on the current file system (the operating system
+and file system support symbolic links), set the output variable
+LN_S to `ln -s'; otherwise, if `ln' works, set
+LN_S to `ln' and otherwise set it to `cp -p'.
+
+
+
+If you make a link a directory other than the current directory, its
+meaning depends on whether `ln' or `ln -s' is used. To safely
+create links using `$(LN_S)', either find out which form is used
+and adjust the arguments, or always invoke ln in the directory
+where the link is to be created.
+
+
+
+In other words, it does not work to do:
+
+
+$(LN_S) foo /x/bar
+
+
+
+Instead, do:
+
+
+
+
+(cd /x && $(LN_S) foo bar)
+
+
+
+
+
+
+
Macro:AC_PROG_RANLIB
+
+
+
+Set output variable RANLIB to `ranlib' if ranlib
+is found, and otherwise to `:' (do nothing).
+
+
+
+
+
+
Macro:AC_PROG_YACC
+
+
+
+If bison is found, set output variable YACC to `bison
+-y'. Otherwise, if byacc is found, set YACC to
+`byacc'. Otherwise set YACC to `yacc'.
+
+These macros are used to find programs not covered by the "particular"
+test macros. If you need to check the behavior of a program as well as
+find out whether it is present, you have to write your own test for it
+(see section Writing Tests). By default, these macros use the environment
+variable PATH. If you need to check for a program that might not
+be in the user's PATH, you can pass a modified path to use
+instead, like this:
+
+
+
+
+You are strongly encouraged to declare the variable passed to
+AC_CHECK_PROG etc. as precious, See section Setting Output Variables,
+AC_ARG_VAR, for more details.
+
+
+
+
+Check whether program prog-to-check-for exists in PATH. If
+it is found, set variable to value-if-found, otherwise to
+value-if-not-found, if given. Always pass over reject (an
+absolute file name) even if it is the first found in the search path; in
+that case, set variable using the absolute file name of the
+prog-to-check-for found that is not reject. If
+variable was already set, do nothing. Calls AC_SUBST for
+variable.
+
+
+Check for each program in the whitespace-separated list
+progs-to-check-for exists on the PATH. If it is found, set
+variable to the name of that program. Otherwise, continue
+checking the next program in the list. If none of the programs in the
+list are found, set variable to value-if-not-found; if
+value-if-not-found is not specified, the value of variable
+is not changed. Calls AC_SUBST for variable.
+
+
+Like AC_CHECK_PROG, but first looks for prog-to-check-for
+with a prefix of the host type as determined by
+AC_CANONICAL_HOST, followed by a dash (see section Getting the Canonical System Type).
+For example, if the user runs `configure --host=i386-gnu', then
+this call:
+
+
+AC_CHECK_TOOL(RANLIB, ranlib, :)
+
+
+
+sets RANLIB to `i386-gnu-ranlib' if that program exists in
+PATH, or otherwise to `ranlib' if that program exists in
+PATH, or to `:' if neither program exists.
+
+
+Like AC_CHECK_TOOL, each of the tools in the list
+progs-to-check-for are checked with a prefix of the host type as
+determined by AC_CANONICAL_HOST, followed by a dash
+(see section Getting the Canonical System Type). If none of the tools can be found with a
+prefix, then the first one without a prefix is used. If a tool is found,
+set variable to the name of that program. If none of the tools in
+the list are found, set variable to value-if-not-found; if
+value-if-not-found is not specified, the value of variable
+is not changed. Calls AC_SUBST for variable.
+
+You might also need to check for the existence of files. Before using
+these macros, ask yourself whether a run time test might not be a better
+solution. Be aware that, like most Autoconf macros, they test a feature
+of the host machine, and therefore, they die when cross-compiling.
+
+
+
+
+Executes AC_CHECK_FILE once for each file listed in files.
+Additionally, defines `HAVE_file' (see section Standard Symbols)
+for each file found.
+
+
+Depending on the current language(see section Language Choice), try to
+ensure that the C, C++, or Fortran 77 function function is
+available by checking whether a test program can be linked with the
+library library to get the function. library is the base
+name of the library; e.g., to check for @option{-lmp}, use `mp' as
+the library argument.
+
+
+
+action-if-found is a list of shell commands to run if the link
+with the library succeeds; action-if-not-found is a list of shell
+commands to run if the link fails. If action-if-found is not
+specified, the default action will prepend @option{-llibrary} to
+LIBS and define `HAVE_LIBlibrary' (in all
+capitals). This macro is intended to support building of LIBS in
+a right-to-left (least-dependent to most-dependent) fashion such that
+library dependencies are satisfied as a natural side-effect of
+consecutive tests. Some linkers are very sensitive to library ordering
+so the order in which LIBS is generated is important to reliable
+detection of libraries.
+
+
+
+If linking with library results in unresolved symbols that would
+be resolved by linking with additional libraries, give those libraries
+as the other-libraries argument, separated by spaces:
+e.g. @option{-lXt -lX11}. Otherwise, this macro will fail to detect
+that library is present, because linking the test program will
+always fail with unresolved symbols. The other-libraries argument
+should be limited to cases where it is desirable to test for one library
+in the presence of another that is not already in LIBS.
+
+
+Search for a library defining function if it's not already
+available. This equates to calling AC_TRY_LINK_FUNC first
+with no libraries, then for each library listed in search-libs.
+
+
+
+Add @option{-llibrary} to LIBS for the first library found
+to contain function, and run action-if-found. If the
+function is not found, run action-if-not-found.
+
+
+
+If linking with library results in unresolved symbols that would
+be resolved by linking with additional libraries, give those libraries
+as the other-libraries argument, separated by spaces:
+e.g. @option{-lXt -lX11}. Otherwise, this macro will fail to detect
+that function is present, because linking the test program will
+always fail with unresolved symbols.
+
+The following macros check for particular C library functions.
+If there is no macro specifically defined to check for a function you need,
+and you don't need to check for any special properties of
+it, then you can use one of the general function-check macros.
+
+
+
+
+
+Most usual functions can either be missing, or be buggy, or be limited
+on some architectures. This section tries to make an inventory of these
+portability issues. By definition, this list will always require
+additions. Please help us keeping it as complete as possible.
+
+
+
+
+
snprintf
+
+
+
+The ISO C99 standard says that if the output array isn't big enough and
+if no other errors occur, snprintf and vsnprintf truncate
+the output and return the number of bytes that ought to have been
+produced. Some older systems return the truncated length (e.g., GNU C
+Library 2.0.x or IRIX 6.5), some a negative value (e.g., earlier GNU C
+Library versions), and some the buffer length without truncation (e.g.,
+32-bit Solaris 7). Also, some buggy older systems ignore the length and
+overrun the buffer (e.g., 64-bit Solaris 7).
+
+
sprintf
+
+
+
+The ISO C standard says sprintf and vsprintf return the
+number of bytes written, but on some old systems (SunOS 4 for
+instance) they return the buffer pointer instead.
+
+
sscanf
+
+
+On various old systems, e.g. HP-UX 9, sscanf requires that its
+input string is writable (though it doesn't actually change it). This
+can be a problem when using @command{gcc} since it normally puts
+constant strings in read-only memory
+(see section `Incompatibilities' in Using and Porting the GNU Compiler Collection). Apparently in some cases even
+having format strings read-only can be a problem.
+
+
strnlen
+
+
+AIX 4.3 provides a broken version which produces funny results:
+
+
+
+
+The POSIX spec says that unlink causes the given files to be
+removed only after there are no more open file handles for it. Not all
+OS's support this behaviour though. So even on systems that provide
+unlink, you cannot portably assume it is OK to call it on files
+that are open. For example, on Windows 9x and ME, such a call would fail;
+on DOS it could even lead to file system corruption, as the file might end
+up being written to after the OS has removed it.
+
+
va_copy
+
+
+The ISO C99 standard provides va_copy for copying
+va_list variables. It may be available in older environments
+too, though possibly as __va_copy (eg. @command{gcc} in strict
+C89 mode). These can be tested with #ifdef. A fallback to
+memcpy (&dst, &src, sizeof(va_list)) will give maximum
+portability.
+
+
va_list
+
+
+va_list is not necessarily just a pointer. It can be a
+struct (eg. @command{gcc} on Alpha), which means NULL is
+not portable. Or it can be an array (eg. @command{gcc} in some
+PowerPC configurations), which means as a function parameter it can be
+effectively call-by-reference and library routines might modify the
+value back in the caller (eg. vsnprintf in the GNU C Library
+2.1).
+
+
Signed >>
+
+Normally the C >> right shift of a signed type replicates the
+high bit, giving a so-called "arithmetic" shift. But care should be
+taken since the ISO C standard doesn't require that behaviour. On those
+few processors without a native arithmetic shift (for instance Cray
+vector systems) zero bits may be shifted in, the same as a shift of an
+unsigned type.
+
+These macros check for particular C functions--whether they exist, and
+in some cases how they respond when given certain arguments.
+
+
+
+
+
Macro:AC_FUNC_ALLOCA
+
+
+
+
+
+
+Check how to get alloca. Tries to get a builtin version by
+checking for `alloca.h' or the predefined C preprocessor macros
+__GNUC__ and _AIX. If this macro finds `alloca.h',
+it defines HAVE_ALLOCA_H.
+
+
+
+If those attempts fail, it looks for the function in the standard C
+library. If any of those methods succeed, it defines
+HAVE_ALLOCA. Otherwise, it sets the output variable
+ALLOCA to `alloca.o' and defines C_ALLOCA (so
+programs can periodically call `alloca(0)' to garbage collect).
+This variable is separate from LIBOBJS so multiple programs can
+share the value of ALLOCA without needing to create an actual
+library, in case only some of them use the code in LIBOBJS.
+
+
+
+This macro does not try to get alloca from the System V R3
+`libPW' or the System V R4 `libucb' because those libraries
+contain some incompatible functions that cause trouble. Some versions
+do not even contain alloca or contain a buggy version. If you
+still want to use their alloca, use ar to extract
+`alloca.o' from them instead of compiling `alloca.c'.
+
+
+
+Source files that use alloca should start with a piece of code
+like the following, to declare it properly. In some versions of AIX,
+the declaration of alloca must precede everything else except for
+comments and preprocessor directives. The #pragma directive is
+indented so that pre-ANSI C compilers will ignore it, rather than
+choke on it.
+
+
+
+
+/* AIX requires this to be the first thing in the file. */
+#ifndef __GNUC__
+# if HAVE_ALLOCA_H
+# include <alloca.h>
+# else
+# ifdef _AIX
+ #pragma alloca
+# else
+# ifndef alloca /* predefined by HP cc +Olibcalls */
+char *alloca ();
+# endif
+# endif
+# endif
+#endif
+
+
+
+
+
+
+
Macro:AC_FUNC_CHOWN
+
+
+
+If the chown function is available and works (in particular, it
+should accept @option{-1} for uid and gid), define
+HAVE_CHOWN.
+
+
+
+
+
+
Macro:AC_FUNC_CLOSEDIR_VOID
+
+
+
+
+If the closedir function does not return a meaningful value,
+define CLOSEDIR_VOID. Otherwise, callers ought to check its
+return value for an error indicator.
+
+
+
+
+
+
Macro:AC_FUNC_ERROR_AT_LINE
+
+
+
+If the error_at_line function is not found, require an
+AC_LIBOBJ replacement of `error'.
+
+
+
+
+
+
Macro:AC_FUNC_FNMATCH
+
+
+
+If the fnmatch function is available and works (unlike the one on
+Solaris 2.4), define HAVE_FNMATCH.
+
+
+
+
+
+
Macro:AC_FUNC_FORK
+
+
+
+
+
+
+
+
+This macro checks for the fork and vfork functions. If a
+working fork is found, define HAVE_WORKING_FORK. This macro
+checks whether fork is just a stub by trying to run it.
+
+
+
+If `vfork.h' is found, define HAVE_VFORK_H. If a working
+vfork is found, define HAVE_WORKING_VFORK. Otherwise,
+define vfork to be fork for backward compatibility with
+previous versions of @command{autoconf}. This macro checks for several known
+errors in implementations of vfork and considers the system to not
+have a working vfork if it detects any of them. It is not considered
+to be an implementation error if a child's invocation of signal
+modifies the parent's signal handler, since child processes rarely change
+their signal handlers.
+
+
+
+Since this macro defines vfork only for backward compatibility with
+previous versions of @command{autoconf} you're encouraged to define it
+yourself in new code:
+
+
+
+
+
+If the fseeko function is available, define HAVE_FSEEKO.
+Define _LARGEFILE_SOURCE if necessary.
+
+
+
+
+
+
Macro:AC_FUNC_GETGROUPS
+
+
+
+
+If the getgroups function is available and works (unlike on
+Ultrix 4.3, where `getgroups (0, 0)' always fails), define
+HAVE_GETGROUPS. Set GETGROUPS_LIBS to any libraries
+needed to get that function. This macro runs AC_TYPE_GETGROUPS.
+
+
+
+
+
+
Macro:AC_FUNC_GETLOADAVG
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Check how to get the system load averages. If the system has the
+getloadavg function, define HAVE_GETLOADAVG, and set
+GETLOADAVG_LIBS to any libraries needed to get that function.
+Also add GETLOADAVG_LIBS to LIBS.
+
+
+
+Otherwise, require an AC_LIBOBJ replacement (`getloadavg.c')
+of `getloadavg', and possibly define several other C preprocessor
+macros and output variables:
+
+
+
+
+
+
+Define C_GETLOADAVG.
+
+
+
+Define SVR4, DGUX, UMAX, or UMAX4_3 if on
+those systems.
+
+
+
+If `nlist.h' is found, define NLIST_STRUCT.
+
+
+
+If `struct nlist' has an `n_un.n_name' member, define
+HAVE_STRUCT_NLIST_N_UN_N_NAME. The obsolete symbol
+NLIST_NAME_UNION is still defined, but do not depend upon it.
+
+
+
+Programs may need to be installed setgid (or setuid) for
+getloadavg to work. In this case, define
+GETLOADAVG_PRIVILEGED, set the output variable NEED_SETGID
+to `true' (and otherwise to `false'), and set
+KMEM_GROUP to the name of the group that should own the installed
+program.
+
+
+
+
+
+
+
Macro:AC_FUNC_GETMNTENT
+
+
+
+
+Check for getmntent in the `sun', `seq', and `gen'
+libraries, for Irix 4, PTX, and Unixware, respectively. Then, if
+getmntent is available, define HAVE_GETMNTENT.
+
+
+
+
+
+
Macro:AC_FUNC_GETPGRP
+
+
+
+
+
+Define GETPGRP_VOID if it is an error to pass 0 to
+getpgrp; this is the POSIX.1 behavior. On older BSD
+systems, you must pass 0 to getpgrp, as it takes an argument and
+behaves like POSIX.1's getpgid.
+
+
+
+
+This macro does not check whether
+getpgrp exists at all; if you need to work in that situation,
+first call AC_CHECK_FUNC for getpgrp.
+
+
+
+
+
+
Macro:AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
+
+
+
+
+If `link' is a symbolic link, then lstat should treat
+`link/' the same as `link/.'. However, many older
+lstat implementations incorrectly ignore trailing slashes.
+
+
+
+It is safe to assume that if lstat incorrectly ignores
+trailing slashes, then other symbolic-link-aware functions like
+unlink and unlink also incorrectly ignore trailing slashes.
+
+
+
+If lstat behaves properly, define
+LSTAT_FOLLOWS_SLASHED_SYMLINK, otherwise require an
+AC_LIBOBJ replacement of lstat.
+
+
+
+
+
+
Macro:AC_FUNC_MALLOC
+
+
+
+If the malloc works correctly (`malloc (0)' returns a valid
+pointer), define HAVE_MALLOC.
+
+
+
+
+
+
Macro:AC_FUNC_MEMCMP
+
+
+
+
+If the memcmp function is not available, or does not work on
+8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
+bytes or more and with at least one buffer not starting on a 4-byte
+boundary (such as the one on NeXT x86 OpenStep), require an
+AC_LIBOBJ replacement for `memcmp'.
+
+
+
+
+
+
Macro:AC_FUNC_MKTIME
+
+
+
+
+If the mktime function is not available, or does not work
+correctly, require an AC_LIBOBJ replacement for `mktime'.
+
+
+
+
+
+
Macro:AC_FUNC_MMAP
+
+
+
+
+If the mmap function exists and works correctly, define
+HAVE_MMAP. Only checks private fixed mapping of already-mapped
+memory.
+
+
+
+
+
+
Macro:AC_FUNC_OBSTACK
+
+
+
+
+If the obstacks are found, define HAVE_OBSTACK, else require an
+AC_LIBOBJ replacement for `obstack'.
+
+
+
+
+
+
Macro:AC_FUNC_SELECT_ARGTYPES
+
+
+
+
+
+
+Determines the correct type to be passed for each of the
+select function's arguments, and defines those types
+in SELECT_TYPE_ARG1, SELECT_TYPE_ARG234, and
+SELECT_TYPE_ARG5 respectively. SELECT_TYPE_ARG1 defaults
+to `int', SELECT_TYPE_ARG234 defaults to `int *',
+and SELECT_TYPE_ARG5 defaults to `struct timeval *'.
+
+
+
+
+
+
Macro:AC_FUNC_SETPGRP
+
+
+
+
+If setpgrp takes no argument (the POSIX.1 version), define
+SETPGRP_VOID. Otherwise, it is the BSD version, which takes
+two process IDs as arguments. This macro does not check whether
+setpgrp exists at all; if you need to work in that situation,
+first call AC_CHECK_FUNC for setpgrp.
+
+
+
+
+
+
Macro:AC_FUNC_STAT
+
+
Macro:AC_FUNC_LSTAT
+
+
+
+
+
+
+
+Determine whether stat or lstat have the bug that it
+succeeds when given the zero-length file name argument. The stat
+and lstat from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
+this.
+
+
+
+If it does, then define HAVE_STAT_EMPTY_STRING_BUG (or
+HAVE_LSTAT_EMPTY_STRING_BUG) and ask for an AC_LIBOBJ
+replacement of it.
+
+
+
+
+
+
Macro:AC_FUNC_SETVBUF_REVERSED
+
+
+
+
+If setvbuf takes the buffering type as its second argument and
+the buffer pointer as the third, instead of the other way around, define
+SETVBUF_REVERSED.
+
+
+
+
+
+
Macro:AC_FUNC_STRCOLL
+
+
+
+
+If the strcoll function exists and works correctly, define
+HAVE_STRCOLL. This does a bit more than
+`AC_CHECK_FUNCS(strcoll)', because some systems have incorrect
+definitions of strcoll that should not be used.
+
+
+
+
+
+
Macro:AC_FUNC_STRTOD
+
+
+
+
+If the strtod function does not exist or doesn't work correctly,
+ask for an AC_LIBOBJ replacement of `strtod'. In this case,
+because `strtod.c' is likely to need `pow', set the output
+variable POW_LIB to the extra library needed.
+
+
+
+
+
+
Macro:AC_FUNC_STRERROR_R
+
+
+
+
+
+
+If strerror_r is available, define HAVE_STRERROR_R, and if
+it is declared, define HAVE_DECL_STRERROR_R. If it returns a
+char * message, define STRERROR_R_CHAR_P; otherwise it
+returns an int error number. The Thread-Safe Functions option of
+POSIX-200X requires strerror_r to return int, but
+many systems (including, for example, version 2.2.4 of the GNU C
+Library) return a char * value that is not necessarily equal to
+the buffer argument.
+
+
+
+
+
+
Macro:AC_FUNC_STRFTIME
+
+
+
+
+Check for strftime in the `intl' library, for SCO UNIX.
+Then, if strftime is available, define HAVE_STRFTIME.
+
+
+
+
+
+
Macro:AC_FUNC_STRNLEN
+
+
+
+
+Check for a working strnlen, and ask for its replacement. Some
+architectures are know to provide broken versions of strnlen, such
+as AIX 4.3.
+
+
+
+
+
+If vprintf is found, define HAVE_VPRINTF. Otherwise, if
+_doprnt is found, define HAVE_DOPRNT. (If vprintf
+is available, you may assume that vfprintf and vsprintf
+are also available.)
+
+These macros are used to find functions not covered by the "particular"
+test macros. If the functions might be in libraries other than the
+default C library, first call AC_CHECK_LIB for those libraries.
+If you need to check the behavior of a function as well as find out
+whether it is present, you have to write your own test for
+it (see section Writing Tests).
+
+
+
+
+If C function function is available, run shell commands
+action-if-found, otherwise action-if-not-found. If you just
+want to define a symbol if the function is available, consider using
+AC_CHECK_FUNCS instead. This macro checks for functions with C
+linkage even when AC_LANG(C++) has been called, since C is more
+standardized than C++. (see section Language Choice, for more information
+about selecting the language for checks.)
+
+
+
+For each function in the whitespace-separated argument list,
+define HAVE_function (in all capitals) if it is available.
+If action-if-found is given, it is additional shell code to
+execute when one of the functions is found. You can give it a value of
+`break' to break out of the loop on the first match. If
+action-if-not-found is given, it is executed when one of the
+functions is not found.
+
+
+
+
+Autoconf follows a philosophy that was formed over the years by those
+who have struggled for portability: isolate the portability issues in
+specific files, and then program as if you were in a POSIX
+environment. Some functions may be missing or unfixable, and your
+package must be ready to replace them.
+
+
+
+Use the first three of the following macros to specify a function to be
+replaced, and the last one (AC_REPLACE_FUNCS) to check for and
+replace the function if needed.
+
+
+
+
+
Macro:AC_LIBOBJ(function)
+
+
+
+Specify that `function.c' must be included in the executables
+to replace a missing or broken implementation of function.
+
+
+
+Technically, it adds `function.$ac_objext' to the output
+variable LIBOBJS and calls AC_LIBSOURCE for
+`function.c'. You should not directly change LIBOBJS,
+since this is not traceable.
+
+
+
+
+
+
Macro:AC_LIBSOURCE(file)
+
+
+Specify that file might be needed to compile the project. If you
+need to know what files might be needed by a `configure.ac', you
+should trace AC_LIBSOURCE. file must be a literal.
+
+
+
+This macro is called automatically from AC_LIBOBJ, but you must
+call it explicitly if you pass a shell variable to AC_LIBOBJ. In
+that case, since shell variables cannot be traced statically, you must
+pass to AC_LIBSOURCE any possible files that the shell variable
+might cause AC_LIBOBJ to need. For example, if you want to pass
+a variable $foo_or_bar to AC_LIBOBJ that holds either
+"foo" or "bar", you should do:
+
+
+
+
+There is usually a way to avoid this, however, and you are encouraged to
+simply call AC_LIBOBJ with literal arguments.
+
+
+
+Note that this macro replaces the obsolete AC_LIBOBJ_DECL, with
+slightly different semantics: the old macro took the function name,
+e.g. foo, as its argument rather than the file name.
+
+
+
+
+
+
Macro:AC_LIBSOURCES(files)
+
+
+Like AC_LIBSOURCE, but accepts one or more files in a
+comma-separated M4 list. Thus, the above example might be rewritten:
+
+
+
+
+
+
+Like AC_CHECK_FUNCS, but uses `AC_LIBOBJ(function)' as
+action-if-not-found. You can declare your replacement function by
+enclosing the prototype in `#if !HAVE_function'. If the
+system has the function, it probably declares it in a header file you
+should be including, so you shouldn't redeclare it lest your declaration
+conflict.
+
+The following macros check for the presence of certain C header files.
+If there is no macro specifically defined to check for a header file you need,
+and you don't need to check for any special properties of
+it, then you can use one of the general header-file check macros.
+
+
+
+
+
+These macros check for particular system header files--whether they
+exist, and in some cases whether they declare certain symbols.
+
+
+
+
+
Macro:AC_HEADER_DIRENT
+
+
+
+
+
+
+Check for the following header files. For the first one that is
+found and defines `DIR', define the listed C preprocessor macro:
+
+
+
`dirent.h'
HAVE_DIRENT_H
+
+
`sys/ndir.h'
HAVE_SYS_NDIR_H
+
+
`sys/dir.h'
HAVE_SYS_DIR_H
+
+
`ndir.h'
HAVE_NDIR_H
+
+The directory-library declarations in your source code should look
+something like the following:
+
+
+
+#if HAVE_DIRENT_H
+# include <dirent.h>
+# define NAMLEN(dirent) strlen((dirent)->d_name)
+#else
+# define dirent direct
+# define NAMLEN(dirent) (dirent)->d_namlen
+# if HAVE_SYS_NDIR_H
+# include <sys/ndir.h>
+# endif
+# if HAVE_SYS_DIR_H
+# include <sys/dir.h>
+# endif
+# if HAVE_NDIR_H
+# include <ndir.h>
+# endif
+#endif
+
+
+Using the above declarations, the program would declare variables to be
+of type struct dirent, not struct direct, and would access
+the length of a directory entry name by passing a pointer to a
+struct dirent to the NAMLEN macro.
+
+This macro also checks for the SCO Xenix `dir' and `x' libraries.
+
+
+
+
Macro:AC_HEADER_MAJOR
+
+
+
+
+If `sys/types.h' does not define major, minor, and
+makedev, but `sys/mkdev.h' does, define
+MAJOR_IN_MKDEV; otherwise, if `sys/sysmacros.h' does, define
+MAJOR_IN_SYSMACROS.
+
+
+
+
Macro:AC_HEADER_STAT
+
+
+
+If the macros S_ISDIR, S_ISREG et al. defined in
+`sys/stat.h' do not work properly (returning false positives),
+define STAT_MACROS_BROKEN. This is the case on Tektronix UTekV,
+Amdahl UTS and Motorola System V/88.
+
+
+
+
Macro:AC_HEADER_STDC
+
+
+
+Define STDC_HEADERS if the system has ANSI C header files.
+Specifically, this macro checks for `stdlib.h', `stdarg.h',
+`string.h', and `float.h'; if the system has those, it
+probably has the rest of the ANSI C header files. This macro also
+checks whether `string.h' declares memchr (and thus
+presumably the other mem functions), whether `stdlib.h'
+declare free (and thus presumably malloc and other related
+functions), and whether the `ctype.h' macros work on characters
+with the high bit set, as ANSI C requires.
+
+Use STDC_HEADERS instead of __STDC__ to determine whether
+the system has ANSI-compliant header files (and probably C library
+functions) because many systems that have GCC do not have ANSI C
+header files.
+
+On systems without ANSI C headers, there is so much variation that
+it is probably easier to declare the functions you use than to figure
+out exactly what the system header files declare. Some systems contain
+a mix of functions ANSI and BSD; some are mostly ANSI but
+lack `memmove'; some define the BSD functions as macros in
+`string.h' or `strings.h'; some have only the BSD
+functions but `string.h'; some declare the memory functions in
+`memory.h', some in `string.h'; etc. It is probably
+sufficient to check for one string function and one memory function; if
+the library has the ANSI versions of those then it probably has
+most of the others. If you put the following in `configure.ac':
+
+
+
+AC_HEADER_STDC
+AC_CHECK_FUNCS(strchr memcpy)
+
+
+then, in your code, you can put declarations like this:
+
+
+
+
+If you use a function like memchr, memset, strtok,
+or strspn, which have no BSD equivalent, then macros won't
+suffice; you must provide an implementation of each function. An easy
+way to incorporate your implementations only when needed (since the ones
+in system C libraries may be hand optimized) is to, taking memchr
+for example, put it in `memchr.c' and use
+`AC_REPLACE_FUNCS(memchr)'.
+
+
+
+
Macro:AC_HEADER_SYS_WAIT
+
+
+
+If `sys/wait.h' exists and is compatible with POSIX.1, define
+HAVE_SYS_WAIT_H. Incompatibility can occur if `sys/wait.h'
+does not exist, or if it uses the old BSD union wait instead
+of int to store a status value. If `sys/wait.h' is not
+POSIX.1 compatible, then instead of including it, define the
+POSIX.1 macros with their usual interpretations. Here is an
+example:
+
+
+
+
+
+_POSIX_VERSION is defined when `unistd.h' is included on
+POSIX.1 systems. If there is no `unistd.h', it is definitely
+not a POSIX.1 system. However, some non-POSIX.1 systems do
+have `unistd.h'.
+
+The way to check if the system supports POSIX.1 is:
+
+
+
+#if HAVE_UNISTD_H
+# include <sys/types.h>
+# include <unistd.h>
+#endif
+
+#ifdef _POSIX_VERSION
+/* Code for POSIX.1 systems. */
+#endif
+
+
+
+
Macro:AC_HEADER_TIME
+
+
+
+If a program may include both `time.h' and `sys/time.h',
+define TIME_WITH_SYS_TIME. On some older systems,
+`sys/time.h' includes `time.h', but `time.h' is not
+protected against multiple inclusion, so programs should not explicitly
+include both files. This macro is useful in programs that use, for
+example, struct timeval or struct timezone as well as
+struct tm. It is best used in conjunction with
+HAVE_SYS_TIME_H, which can be checked for using
+AC_CHECK_HEADERS(sys/time.h).
+
+
+
+#if TIME_WITH_SYS_TIME
+# include <sys/time.h>
+# include <time.h>
+#else
+# if HAVE_SYS_TIME_H
+# include <sys/time.h>
+# else
+# include <time.h>
+# endif
+#endif
+
+
+
+
+
+
Macro:AC_HEADER_TIOCGWINSZ
+
+
+
+If the use of TIOCGWINSZ requires `<sys/ioctl.h>', then
+define GWINSZ_IN_SYS_IOCTL. Otherwise TIOCGWINSZ can be
+found in `<termios.h>'.
+
+Use:
+
+
+
+#if HAVE_TERMIOS_H
+# include <termios.h>
+#endif
+
+#if GWINSZ_IN_SYS_IOCTL
+# include <sys/ioctl.h>
+#endif
+
+These macros are used to find system header files not covered by the
+"particular" test macros. If you need to check the contents of a header
+as well as find out whether it is present, you have to write your own
+test for it (see section Writing Tests).
+
+
+
+
+If the system header file header-file is usable, execute shell
+commands action-if-found, otherwise execute
+action-if-not-found. If you just want to define a symbol if the
+header file is available, consider using AC_CHECK_HEADERS
+instead.
+
+
+
+The meaning of "usable" depends upon the content of includes:
+
+
+
+
+
if includes is empty
+
+check whether
+
+
+
+header-file
+
+
+can be preprocessed without error.
+
+
if include is set
+
+Check whether
+
+
+
+includes
+#include <header-file>
+
+
+can be compiled without error. You may use
+AC_CHECK_HEADER (and AC_CHECK_HEADERS) to check whether
+two headers are compatible.
+
+
+
+You may pass any kind of dummy content for includes, such as a
+single space, a comment, to check whether header-file compiles
+with success.
+
+
+
+For each given system header file header-file in the
+whitespace-separated argument list that exists, define
+HAVE_header-file (in all capitals). If action-if-found
+is given, it is additional shell code to execute when one of the header
+files is found. You can give it a value of `break' to break out of
+the loop on the first match. If action-if-not-found is given, it
+is executed when one of the header files is not found.
+
+
+
+Be sure to read the documentation of AC_CHECK_HEADER to
+understand the influence of includes.
+
+The following macros check for the declaration of variables and
+functions. If there is no macro specifically defined to check for a
+symbol you need, then you can use the general macros (see section Generic Declaration Checks) or, for more complex tests, you may use
+AC_TRY_COMPILE (see section Examining Syntax).
+
+
+
+
+
+
+If symbol (a function or a variable) is not declared in
+includes and a declaration is needed, run the shell commands
+action-if-not-found, otherwise action-if-found. If no
+includes are specified, the default includes are used
+(see section Default Includes).
+
+
+
+This macro actually tests whether it is valid to use symbol as an
+r-value, not if it is really declared, because it is much safer to avoid
+introducing extra declarations when they are not needed.
+
+
+
+For each of the symbols (comma-separated list), define
+HAVE_DECL_symbol (in all capitals) to `1' if
+symbol is declared, otherwise to `0'. If
+action-if-not-found is given, it is additional shell code to
+execute when one of the function declarations is needed, otherwise
+action-if-found is executed.
+
+
+
+This macro uses an m4 list as first argument:
+
+
+Unlike the other `AC_CHECK_*S' macros, when a symbol is not
+declared, HAVE_DECL_symbol is defined to `0' instead
+of leaving HAVE_DECL_symbol undeclared. When you are
+sure that the check was performed, use
+HAVE_DECL_symbol just like any other result of Autoconf:
+
+
+
+
+If the test may have not been performed, however, because it is safer
+not to declare a symbol than to use a declaration that conflicts
+with the system's one, you should use:
+
+
+
+
+You fall into the second category only in extreme situations: either
+your files may be used without being configured, or they are used during
+the configuration. In most cases the traditional approach is enough.
+
+The following macros check for the presence of certain members in C
+structures. If there is no macro specifically defined to check for a
+member you need, then you can use the general structure-member macro
+(see section Generic Structure Checks) or, for more complex tests, you may use
+AC_TRY_COMPILE (see section Examining Syntax).
+
+
+
+
+
+The following macros check for certain structures or structure members.
+
+
+
+
+
Macro:AC_STRUCT_ST_BLKSIZE
+
+
+
+
+If struct stat contains an st_blksize member, define
+HAVE_STRUCT_STAT_ST_BLKSIZE. The former name,
+HAVE_ST_BLKSIZE is to be avoided, as its support will cease in
+the future. This macro is obsoleted, and should be replaced by
+
+
+
+
+AC_CHECK_MEMBERS([struct stat.st_blksize])
+
+
+
+
+
+
+
Macro:AC_STRUCT_ST_BLOCKS
+
+
+
+
+
+If struct stat contains an st_blocks member, define
+HAVE_STRUCT STAT_ST_BLOCKS. Otherwise, require an
+AC_LIBOBJ replacement of `fileblocks'. The former name,
+HAVE_ST_BLOCKS is to be avoided, as its support will cease in the
+future.
+
+
+
+
+
+
Macro:AC_STRUCT_ST_RDEV
+
+
+
+
+If struct stat contains an st_rdev member, define
+HAVE_STRUCT_STAT_ST_RDEV. The former name for this macro,
+HAVE_ST_RDEV, is to be avoided as it will cease to be supported
+in the future. Actually, even the new macro is obsolete, and should be
+replaced by:
+
+
+AC_CHECK_MEMBERS([struct stat.st_rdev])
+
+
+
+
+
+
+
Macro:AC_STRUCT_TM
+
+
+
+If `time.h' does not define struct tm, define
+TM_IN_SYS_TIME, which means that including `sys/time.h'
+had better define struct tm.
+
+
+
+
+
+
Macro:AC_STRUCT_TIMEZONE
+
+
+
+
+Figure out how to get the current timezone. If struct tm has a
+tm_zone member, define HAVE_STRUCT_TM_TM_ZONE (and the
+obsoleted HAVE_TM_ZONE). Otherwise, if the external array
+tzname is found, define HAVE_TZNAME.
+
+
+Check whether member is a member of the aggregate aggregate.
+If no includes are specified, the default includes are used
+(see section Default Includes).
+
+
+
+
+AC_CHECK_MEMBER(struct passwd.pw_gecos,,
+ [AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
+ [#include <pwd.h>])
+
+
+Check for the existence of each `aggregate.member' of
+members using the previous macro. When member belongs to
+aggregate, define HAVE_aggregate_member (in all
+capitals, with spaces and dots replaced by underscores).
+
+
+
+The following macros check for C types, either builtin or typedefs. If
+there is no macro specifically defined to check for a type you need, and
+you don't need to check for any special properties of it, then you can
+use a general type-check macro.
+
+
+
+
+
+These macros check for particular C types in `sys/types.h',
+`stdlib.h' and others, if they exist.
+
+
+
+
+
Macro:AC_TYPE_GETGROUPS
+
+
+
+Define GETGROUPS_T to be whichever of gid_t or int
+is the base type of the array argument to getgroups.
+
+
+
+
+
+
Macro:AC_TYPE_MODE_T
+
+
+
+Equivalent to `AC_CHECK_TYPE(mode_t, int)'.
+
+
+
+
+
+
Macro:AC_TYPE_OFF_T
+
+
+
+Equivalent to `AC_CHECK_TYPE(off_t, long)'.
+
+
+
+
+
+
Macro:AC_TYPE_PID_T
+
+
+
+Equivalent to `AC_CHECK_TYPE(pid_t, int)'.
+
+
+
+
+
+
Macro:AC_TYPE_SIGNAL
+
+
+
+If `signal.h' declares signal as returning a pointer to a
+function returning void, define RETSIGTYPE to be
+void; otherwise, define it to be int.
+
+
+
+Define signal handlers as returning type RETSIGTYPE:
+
+
+
+
+RETSIGTYPE
+hup_handler ()
+{
+...
+}
+
+
+
+
+
+
+
Macro:AC_TYPE_SIZE_T
+
+
+
+Equivalent to `AC_CHECK_TYPE(size_t, unsigned)'.
+
+
+
+
+
+
Macro:AC_TYPE_UID_T
+
+
+
+
+If uid_t is not defined, define uid_t to be int and
+gid_t to be int.
+
+
+For each type of the types that is defined, define
+HAVE_type (in all capitals). If no includes are
+specified, the default includes are used (see section Default Includes). If
+action-if-found is given, it is additional shell code to execute
+when one of the types is found. If action-if-not-found is given,
+it is executed when one of the types is not found.
+
+
+
+This macro uses m4 lists:
+
+
+AC_CHECK_TYPES(ptrdiff_t)
+AC_CHECK_TYPES([unsigned long long, uintmax_t])
+
+
+
+
+
+Autoconf, up to 2.13, used to provide to another version of
+AC_CHECK_TYPE, broken by design. In order to keep backward
+compatibility, a simple heuristics, quite safe but not totally, is
+implemented. In case of doubt, read the documentation of the former
+AC_CHECK_TYPE, see section Obsolete Macros.
+
+
+
+
+
+
+All the tests for compilers (AC_PROG_CC, AC_PROG_CXX,
+AC_PROG_F77) define the output variable EXEEXT based on
+the output of the 1compiler, typically to the empty string if Unix and
+`.exe' if Win32 or OS/2.
+
+
+
+
+They also define the output variable OBJEXT based on the
+output of the compiler, after .c files have been excluded, typically
+to `o' if Unix, `obj' if Win32.
+
+
+
+If the compiler being used does not produce executables, they fail. If
+the executables can't be run, and cross-compilation is not enabled, they
+fail too. See section Manual Configuration, for more on support for cross
+compiling.
+
+
+
+
+
+Some compilers exhibit different behaviors.
+
+
+
+
+
Static/Dynamic Expressions
+
+Autoconf relies on a trick to extract one bit of information from the C
+compiler: using negative array sizes. For instance the following
+excerpt of a C source demonstrates how to test whether `int's are 4
+bytes long:
+
+
+
+
+To our knowledge, there is a single compiler that does not support this
+trick: the HP C compilers (the real one, not only the "bundled") on
+HP-UX 11.00:
+
+
+
+$ cc -c -Ae +O2 +Onolimit conftest.c
+cc: "conftest.c": error 1879: Variable-length arrays cannot \
+ have static storage.
+
+
+Autoconf works around this problem by casting sizeof (int) to
+long before comparing it.
+
+
+Define SIZEOF_type (see section Standard Symbols) to be the
+size in bytes of type. If `type' is unknown, it gets a size
+of 0. If no includes are specified, the default includes are used
+(see section Default Includes). If you provide include, make sure to
+include `stdio.h' which is required for this macro to run.
+
+
+
+This macro now works even when cross-compiling. The unused
+argument was used when cross-compiling.
+
+
+
+For example, the call
+
+
+
+
+AC_CHECK_SIZEOF(int *)
+
+
+
+defines SIZEOF_INT_P to be 8 on DEC Alpha AXP systems.
+
+
+
+
+Determine a C compiler to use. If CC is not already set in the
+environment, check for gcc and cc, then for other C
+compilers. Set output variable CC to the name of the compiler
+found.
+
+
+
+This macro may, however, be invoked with an optional first argument
+which, if specified, must be a space separated list of C compilers to
+search for. This just gives the user an opportunity to specify an
+alternative search list for the C compiler. For example, if you didn't
+like the default order, then you could invoke AC_PROG_CC like
+this:
+
+
+
+
+AC_PROG_CC(cl egcs gcc cc)
+
+
+
+If using the GNU C compiler, set shell variable GCC to
+`yes'. If output variable CFLAGS was not already set, set
+it to @option{-g -O2} for the GNU C compiler (@option{-O2} on systems
+where GCC does not accept @option{-g}), or @option{-g} for other compilers.
+
+
+
+
+
+
Macro:AC_PROG_CC_C_O
+
+
+
+If the C compiler does not accept the @option{-c} and @option{-o} options
+simultaneously, define NO_MINUS_C_MINUS_O. This macro actually
+tests both the compiler found by AC_PROG_CC, and, if different,
+the first cc in the path. The test fails if one fails. This
+macro was created for GNU Make to choose the default C compilation
+rule.
+
+
+
+
+
+
Macro:AC_PROG_CC_STDC
+
+
+
+If the C compiler is not in ANSI C mode by default, try to add an
+option to output variable CC to make it so. This macro tries
+various options that select ANSI C on some system or another. It
+considers the compiler to be in ANSI C mode if it handles function
+prototypes correctly.
+
+
+
+If you use this macro, you should check after calling it whether the C
+compiler has been set to accept ANSI C; if not, the shell variable
+ac_cv_prog_cc_stdc is set to `no'. If you wrote your source
+code in ANSI C, you can make an un-ANSIfied copy of it by
+using the program ansi2knr, which comes with Automake.
+
+
+
+
+
+
Macro:AC_PROG_CPP
+
+
+
+Set output variable CPP to a command that runs the
+C preprocessor. If `$CC -E' doesn't work, `/lib/cpp' is used.
+It is only portable to run CPP on files with a `.c'
+extension.
+
+
+
+If the current language is C (see section Language Choice), many of the
+specific test macros use the value of CPP indirectly by calling
+AC_TRY_CPP, AC_CHECK_HEADER, AC_EGREP_HEADER, or
+AC_EGREP_CPP.
+
+
+
+Some preprocessors don't indicate missing include files by the error
+status. For such preprocessors an internal variable is set that causes
+other macros to check the standard error from the preprocessor and
+consider the test failed if any warnings have been reported.
+
+
+
+
+The following macros check for C compiler or machine architecture
+features. To check for characteristics not listed here, use
+AC_TRY_COMPILE (see section Examining Syntax) or AC_TRY_RUN
+(see section Checking Run Time Behavior)
+
+
+
+
+
+
+If words are stored with the most significant byte first (like Motorola
+and SPARC CPUs), execute action-if-true. If words are stored with
+the less significant byte first (like Intel and VAX CPUs), execute
+action-if-false.
+
+
+
+This macro runs a test-case if endianness cannot be determined from the
+system header files. When cross-compiling the test-case is not run but
+grep'ed for some magic values. action-if-unknown is executed if
+the latter case fails to determine the byte sex of the host system.
+
+
+
+The default for action-if-true is to define
+`WORDS_BIGENDIAN'. The default for action-if-false is to do
+nothing. And finally, the default for action-if-unknown is to
+abort configure and tell the installer which variable he should preset
+to bypass this test.
+
+
+
+
+
+
Macro:AC_C_CONST
+
+
+
+If the C compiler does not fully support the ANSI C qualifier
+const, define const to be empty. Some C compilers that do
+not define __STDC__ do support const; some compilers that
+define __STDC__ do not completely support const. Programs
+can simply use const as if every C compiler supported it; for
+those that don't, the `Makefile' or configuration header file will
+define it as empty.
+
+
+
+Occasionally installers use a C++ compiler to compile C code, typically
+because they lack a C compiler. This causes problems with const,
+because C and C++ treat const differently. For example:
+
+
+
+
+const int foo;
+
+
+
+is valid in C but not in C++. These differences unfortunately cannot be
+papered over by defining const to be empty.
+
+
+
+If @command{autoconf} detects this situation, it leaves const alone,
+as this generally yields better results in practice. However, using a
+C++ compiler to compile C code is not recommended or supported, and
+installers who run into trouble in this area should get a C compiler
+like GCC to compile their C code.
+
+
+
+
+
+
Macro:AC_C_VOLATILE
+
+
+
+If the C compiler does not understand the keyword volatile,
+define volatile to be empty. Programs can simply use
+volatile as if every C compiler supported it; for those that do
+not, the `Makefile' or configuration header will define it as
+empty.
+
+
+
+If the correctness of your program depends on the semantics of
+volatile, simply defining it to be empty does, in a sense, break
+your code. However, given that the compiler does not support
+volatile, you are at its mercy anyway. At least your
+program will compile, when it wouldn't before.
+
+
+
+In general, the volatile keyword is a feature of ANSI C, so
+you might expect that volatile is available only when
+__STDC__ is defined. However, Ultrix 4.3's native compiler does
+support volatile, but does not defined __STDC__.
+
+
+
+
+
+
Macro:AC_C_INLINE
+
+
+
+If the C compiler supports the keyword inline, do nothing.
+Otherwise define inline to __inline__ or __inline
+if it accepts one of those, otherwise define inline to be empty.
+
+
+
+
+
+
Macro:AC_C_CHAR_UNSIGNED
+
+
+
+If the C type char is unsigned, define __CHAR_UNSIGNED__,
+unless the C compiler predefines it.
+
+
+
+
+
+
Macro:AC_C_LONG_DOUBLE
+
+
+
+If the C compiler supports a working long double type with more
+range or precision than the double type, define
+HAVE_LONG_DOUBLE.
+
+
+
+
+
+
Macro:AC_C_STRINGIZE
+
+
+
+If the C preprocessor supports the stringizing operator, define
+HAVE_STRINGIZE. The stringizing operator is `#' and is
+found in macros such as this:
+
+
+
+
+#define x(y) #y
+
+
+
+
+
+
+
Macro:AC_C_PROTOTYPES
+
+
+
+
+
+Check to see if function prototypes are understood by the compiler. If
+so, define PROTOTYPES and __PROTOTYPES.
+In the case the compiler does not handle
+prototypes, you should use ansi2knr, which comes with the
+Automake distribution, to unprotoize function definitions. For
+function prototypes, you should first define PARAMS:
+
+
+
+
+#ifndef PARAMS
+# if PROTOTYPES
+# define PARAMS(protos) protos
+# else /* no PROTOTYPES */
+# define PARAMS(protos) ()
+# endif /* no PROTOTYPES */
+#endif
+
+
+
+then use it this way:
+
+
+
+
+size_t my_strlen PARAMS ((const char *));
+
+
+
+
+
+This macro also defines __PROTOTYPES; this is for the benefit of
+header files that cannot use macros that infringe on user name space.
+
+
+
+
+
Macro:AC_PROG_GCC_TRADITIONAL
+
+
+
+Add @option{-traditional} to output variable CC if using the
+GNU C compiler and ioctl does not work properly without
+@option{-traditional}. That usually happens when the fixed header files
+have not been installed on an old system. Since recent versions of the
+GNU C compiler fix the header files automatically when installed,
+this is becoming a less prevalent problem.
+
+
+
+
+Determine a C++ compiler to use. Check if the environment variable
+CXX or CCC (in that order) is set; if so, then set output
+variable CXX to its value.
+
+
+
+Otherwise, if the macro is invoked without an argument, then search for
+a C++ compiler under the likely names (first g++ and c++
+then other names). If none of those checks succeed, then as a last
+resort set CXX to g++.
+
+
+
+This macro may, however, be invoked with an optional first argument
+which, if specified, must be a space separated list of C++ compilers to
+search for. This just gives the user an opportunity to specify an
+alternative search list for the C++ compiler. For example, if you
+didn't like the default order, then you could invoke AC_PROG_CXX
+like this:
+
+
+
+
+AC_PROG_CXX(cl KCC CC cxx cc++ xlC aCC c++ g++ egcs gcc)
+
+
+
+If using the GNU C++ compiler, set shell variable GXX to
+`yes'. If output variable CXXFLAGS was not already set, set
+it to @option{-g -O2} for the GNU C++ compiler (@option{-O2} on
+systems where G++ does not accept @option{-g}), or @option{-g} for other
+compilers.
+
+
+
+
+
+
Macro:AC_PROG_CXXCPP
+
+
+
+Set output variable CXXCPP to a command that runs the C++
+preprocessor. If `$CXX -E' doesn't work, `/lib/cpp' is used.
+It is only portable to run CXXCPP on files with a `.c',
+`.C', or `.cc' extension.
+
+
+
+If the current language is C++ (see section Language Choice), many of the
+specific test macros use the value of CXXCPP indirectly by
+calling AC_TRY_CPP, AC_CHECK_HEADER,
+AC_EGREP_HEADER, or AC_EGREP_CPP.
+
+
+
+Some preprocessors don't indicate missing include files by the error
+status. For such preprocessors an internal variable is set that causes
+other macros to check the standard error from the preprocessor and
+consider the test failed if any warnings have been reported. However,
+it is not known whether such broken preprocessors exist for C++.
+
+
+
+
+Determine a Fortran 77 compiler to use. If F77 is not already
+set in the environment, then check for g77 and f77, and
+then some other names. Set the output variable F77 to the name
+of the compiler found.
+
+
+
+This macro may, however, be invoked with an optional first argument
+which, if specified, must be a space separated list of Fortran 77
+compilers to search for. This just gives the user an opportunity to
+specify an alternative search list for the Fortran 77 compiler. For
+example, if you didn't like the default order, then you could invoke
+AC_PROG_F77 like this:
+
+
+
+
+If using g77 (the GNU Fortran 77 compiler), then
+AC_PROG_F77 will set the shell variable G77 to `yes'.
+If the output variable FFLAGS was not already set in the
+environment, then set it to @option{-g -02} for g77 (or @option{-O2}
+where g77 does not accept @option{-g}). Otherwise, set
+FFLAGS to @option{-g} for all other Fortran 77 compilers.
+
+
+
+
+
+
Macro:AC_PROG_F77_C_O
+
+
+
+Test if the Fortran 77 compiler accepts the options @option{-c} and
+@option{-o} simultaneously, and define F77_NO_MINUS_C_MINUS_O if it
+does not.
+
+
+
+
+The following macros check for Fortran 77 compiler characteristics. To
+check for characteristics not listed here, use AC_TRY_COMPILE
+(see section Examining Syntax) or AC_TRY_RUN (see section Checking Run Time Behavior),
+making sure to first set the current language to Fortran 77
+AC_LANG(Fortran 77) (see section Language Choice).
+
+
+
+
+
Macro:AC_F77_LIBRARY_LDFLAGS
+
+
+
+Determine the linker flags (e.g. @option{-L} and @option{-l}) for the
+Fortran 77 intrinsic and run-time libraries that are required to
+successfully link a Fortran 77 program or shared library. The output
+variable FLIBS is set to these flags.
+
+
+
+This macro is intended to be used in those situations when it is
+necessary to mix, e.g. C++ and Fortran 77 source code into a single
+program or shared library (see section `Mixing Fortran 77 With C and C++' in GNU Automake).
+
+
+
+For example, if object files from a C++ and Fortran 77 compiler must be
+linked together, then the C++ compiler/linker must be used for linking
+(since special C++-ish things need to happen at link time like calling
+global constructors, instantiating templates, enabling exception
+support, etc.).
+
+
+
+However, the Fortran 77 intrinsic and run-time libraries must be linked
+in as well, but the C++ compiler/linker doesn't know by default how to
+add these Fortran 77 libraries. Hence, the macro
+AC_F77_LIBRARY_LDFLAGS was created to determine these Fortran 77
+libraries.
+
+
+
+The macro AC_F77_DUMMY_MAIN or AC_F77_MAIN will probably
+also be necessary to link C/C++ with Fortran; see below.
+
+
+
+With many compilers, the Fortran libraries detected by
+AC_F77_LIBRARY_LDFLAGS provide their own main entry
+function that initializes things like Fortran I/O, and which then calls
+a user-provided entry function named e.g. MAIN__ to run the
+user's program. The AC_F77_DUMMY_MAIN or AC_F77_MAIN
+macro figures out how to deal with this interaction.
+
+
+
+When using Fortran for purely numerical functions (no I/O, etcetera),
+users often prefer to provide their own main and skip the Fortran
+library initializations. In this case, however, one may still need to
+provide a dummy MAIN__ routine in order to prevent linking errors
+on some systems. AC_F77_DUMMY_MAIN detects whether any such
+routine is required for linking, and what its name is; the shell
+variable F77_DUMMY_MAIN holds this name, unknown when no
+solution was found, and none when no such dummy main is needed.
+
+
+
+By default, action-if-found defines F77_DUMMY_MAIN to the
+name of this routine (e.g. MAIN__) if it is required.
+@ovar{action-if-not-found} defaults to exiting with an error.
+
+
+
+In order to link with Fortran routines, the user's C/C++ program should
+then include the following code to define the dummy main if it is
+needed:
+
+
+
+
+Note that AC_F77_DUMMY_MAIN is called automatically from
+AC_F77_WRAPPERS; there is generally no need to call it explicitly
+unless one wants to change the default actions.
+
+
+
+
+
+
Macro:AC_F77_MAIN
+
+
+
+As discussed above for AC_F77_DUMMY_MAIN, many Fortran libraries
+allow you to provide an entry point called e.g. MAIN__ instead of
+the usual main, which is then called by a main function in
+the Fortran libraries that initializes things like Fortran I/O. The
+AC_F77_MAIN macro detects whether it is possible to
+utilize such an alternate main function, and defines F77_MAIN to
+the name of the function. (If no alternate main function name is found,
+F77_MAIN is simply defined to main.)
+
+
+
+Thus, when calling Fortran routines from C that perform things like I/O,
+one should use this macro and name the "main" function F77_MAIN
+instead of main.
+
+
+
+
+
+
Macro:AC_F77_WRAPPERS
+
+
+
+
+Defines C macros F77_FUNC(name,NAME) and
+F77_FUNC_(name,NAME) to properly mangle the names of C/C++
+identifiers, and identifiers with underscores, respectively, so that
+they match the name-mangling scheme used by the Fortran 77 compiler.
+
+
+
+Fortran 77 is case-insensitive, and in order to achieve this the Fortran
+77 compiler converts all identifiers into a canonical case and format.
+To call a Fortran 77 subroutine from C or to write a C function that is
+callable from Fortran 77, the C program must explicitly use identifiers
+in the format expected by the Fortran 77 compiler. In order to do this,
+one simply wraps all C identifiers in one of the macros provided by
+AC_F77_WRAPPERS. For example, suppose you have the following
+Fortran 77 subroutine:
+
+
+
+
+ subroutine foobar(x,y)
+ double precision x, y
+ y = 3.14159 * x
+ return
+ end
+
+
+
+You would then declare its prototype in C or C++ as:
+
+
+
+
+#define FOOBAR_F77 F77_FUNC(foobar,FOOBAR)
+#ifdef __cplusplus
+extern "C" /* prevent C++ name mangling */
+#endif
+void FOOBAR_F77(double *x, double *y);
+
+
+
+Note that we pass both the lowercase and uppercase versions of the
+function name to F77_FUNC so that it can select the right one.
+Note also that all parameters to Fortran 77 routines are passed as
+pointers (see section `Mixing Fortran 77 With C and C++' in GNU Automake).
+
+
+
+Although Autoconf tries to be intelligent about detecting the
+name-mangling scheme of the Fortran 77 compiler, there may be Fortran 77
+compilers that it doesn't support yet. In this case, the above code
+will generate a compile-time error, but some other behavior
+(e.g. disabling Fortran-related features) can be induced by checking
+whether the F77_FUNC macro is defined.
+
+
+
+Now, to call that routine from a C program, we would do something like:
+
+
+
+
+If the Fortran 77 identifier contains an underscore
+(e.g. foo_bar), you should use F77_FUNC_ instead of
+F77_FUNC (with the same arguments). This is because some Fortran
+77 compilers mangle names differently if they contain an underscore.
+
+
+
+
+
+
Macro:AC_F77_FUNC(name, @ovar{shellvar})
+
+
+Given an identifier name, set the shell variable shellvar to
+hold the mangled version name according to the rules of the
+Fortran 77 linker (see also AC_F77_WRAPPERS). shellvar is
+optional; if it is not supplied, the shell variable will be simply
+name. The purpose of this macro is to give the caller a way to
+access the name-mangling information other than through the C
+preprocessor as above; for example, to call Fortran routines from some
+language other than C/C++.
+
+The following macros check for operating system services or capabilities.
+
+
+
+
+
Macro:AC_PATH_X
+
+
+Try to locate the X Window System include files and libraries. If the
+user gave the command line options @option{--x-includes=dir} and
+@option{--x-libraries=dir}, use those directories. If either or
+both were not given, get the missing values by running xmkmf on a
+trivial `Imakefile' and examining the `Makefile' that it
+produces. If that fails (such as if xmkmf is not present), look
+for them in several directories where they often reside. If either
+method is successful, set the shell variables x_includes and
+x_libraries to their locations, unless they are in directories
+the compiler searches by default.
+
+
+
+If both methods fail, or the user gave the command line option
+@option{--without-x}, set the shell variable no_x to `yes';
+otherwise set it to the empty string.
+
+
+
+
+
+
Macro:AC_PATH_XTRA
+
+
+
+
+
+
+
+An enhanced version of AC_PATH_X. It adds the C compiler flags
+that X needs to output variable X_CFLAGS, and the X linker flags
+to X_LIBS. Define X_DISPLAY_MISSING if X is not
+available.
+
+
+
+This macro also checks for special libraries that some systems need in
+order to compile X programs. It adds any that the system needs to
+output variable X_EXTRA_LIBS. And it checks for special X11R6
+libraries that need to be linked with before @option{-lX11}, and adds
+any found to the output variable X_PRE_LIBS.
+
+
+
+
+
+
+
Macro:AC_SYS_INTERPRETER
+
+
+Check whether the system supports starting scripts with a line of the
+form `#! /bin/csh' to select the interpreter to use for the script.
+After running this macro, shell code in @command{configure.ac} can check
+the shell variable interpval; it will be set to `yes'
+if the system supports `#!', `no' if not.
+
+
+
+
+
+
Macro:AC_SYS_LARGEFILE
+
+
+
+
+
+Arrange for
+@href{http://www.sas.com/standards/large.file/x_open.20Mar96.html,
+large-file support}. On some hosts, one must use special compiler
+options to build programs that can access large files. Append any such
+options to the output variable CC. Define
+_FILE_OFFSET_BITS and _LARGE_FILES if necessary.
+
+
+
+Large-file support can be disabled by configuring with the
+@option{--disable-largefile} option.
+
+
+
+If you use this macro, check that your program works even when
+off_t is longer than long, since this is common when
+large-file support is enabled. For example, it is not correct to print
+an arbitrary off_t value X with printf ("%ld",
+(long) X).
+
+
+
+
+
+
Macro:AC_SYS_LONG_FILE_NAMES
+
+
+
+If the system supports file names longer than 14 characters, define
+HAVE_LONG_FILE_NAMES.
+
+
+
+
+
+
Macro:AC_SYS_POSIX_TERMIOS
+
+
+
+
+Check to see if POSIX termios headers and functions are available on the
+system. If so, set the shell variable am_cv_sys_posix_termios to
+`yes'. If not, set the variable to `no'.
+
+The following macros check for certain operating systems that need
+special treatment for some programs, due to exceptional oddities in
+their header files or libraries. These macros are warts; they will be
+replaced by a more systematic approach, based on the functions they make
+available or the environments they provide.
+
+
+
+
+
Macro:AC_AIX
+
+
+
+If on AIX, define _ALL_SOURCE. Allows the use of some BSD
+functions. Should be called before any macros that run the C compiler.
+
+
+
+
+
+
Macro:AC_ISC_POSIX
+
+
+
+For INTERACTIVE UNIX (ISC), add @option{-lcposix} to output
+variable LIBS if necessary for POSIX facilities. Call this
+after AC_PROG_CC and before any other macros that use POSIX
+interfaces. INTERACTIVE UNIX is no longer sold, and Sun says that
+they will drop support for it on 2006-07-23, so this macro is becoming
+obsolescent.
+
+
+
+
+
+
Macro:AC_MINIX
+
+
+
+
+
+If on Minix, define _MINIX and _POSIX_SOURCE and define
+_POSIX_1_SOURCE to be 2. This allows the use of POSIX
+facilities. Should be called before any macros that run the C compiler.
+
+If the existing feature tests don't do something you need, you have to
+write new ones. These macros are the building blocks. They provide
+ways for other macros to check whether various kinds of features are
+available and report the results.
+
+
+
+This chapter contains some suggestions and some of the reasons why the
+existing tests are written the way they are. You can also learn a lot
+about how to write Autoconf tests by looking at the existing ones. If
+something goes wrong in one or more of the Autoconf tests, this
+information can help you understand the assumptions behind them, which
+might help you figure out how to best solve the problem.
+
+
+
+These macros check the output of the C compiler system. They do
+not cache the results of their tests for future use (see section Caching Results), because they don't know enough about the information they are
+checking for to generate a cache variable name. They also do not print
+any messages, for the same reason. The checks for particular kinds of C
+features call these macros and do cache their results and print messages
+about what they're checking for.
+
+
+
+When you write a feature test that could be applicable to more than one
+software package, the best thing to do is encapsulate it in a new macro.
+See section Writing Autoconf Macros, for how to do that.
+
+
+
+
+
+The macro AC_TRY_CPP is used to check whether particular header
+files exist. You can check for one at a time, or more than one if you
+need several header files to all exist for some purpose.
+
+
+
+
+If the preprocessor produces no error messages while processing the
+input (typically includes), run shell commands
+action-if-true. Otherwise run shell commands
+action-if-false. Beware that input is double quoted. Shell
+variable, back quote, and backslash substitutions are performed on
+input.
+
+
+
+This macro uses CPPFLAGS, but not CFLAGS, because
+@option{-g}, @option{-O}, etc. are not valid options to many C
+preprocessors.
+
+
+
+
+Here is how to find out whether a header file contains a particular
+declaration, such as a typedef, a structure, a structure member, or a
+function. Use AC_EGREP_HEADER instead of running grep
+directly on the header file; on some systems the symbol might be defined
+in another header file that the file you are checking `#include's.
+
+
+
+
+If the output of running the preprocessor on the system header file
+header-file matches the egrep regular expression
+pattern, execute shell commands action-if-found, otherwise
+execute action-if-not-found.
+
+
+
+
+To check for C preprocessor symbols, either defined by header files or
+predefined by the C preprocessor, use AC_EGREP_CPP. Here is an
+example of the latter:
+
+
+
+
+
+program is the text of a C or C++ program, on which shell
+variable, back quote, and backslash substitutions are performed. If the
+output of running the preprocessor on program matches the
+egrep regular expression pattern, execute shell commands
+action-if-found, otherwise execute action-if-not-found.
+
+
+
+This macro calls AC_PROG_CPP or AC_PROG_CXXCPP (depending
+on which language is current, see section Language Choice), if it hasn't
+been called already.
+
+To check for a syntax feature of the C, C++ or Fortran 77 compiler, such
+as whether it recognizes a certain keyword, use AC_TRY_COMPILE to
+try to compile a small program that uses that feature. You can also use
+it to check for structures and structure members that are not present on
+all systems.
+
+
+
+
+Create a test program in the current language (see section Language Choice)
+to see whether a function whose body consists of function-body can
+be compiled. If the file compiles successfully, run shell commands
+action-if-found, otherwise run action-if-not-found.
+
+
+
+This macro double quotes both includes and function-body.
+
+
+
+For C and C++, includes is any #include statements needed
+by the code in function-body (includes will be ignored if
+the currently selected language is Fortran 77). This macro also uses
+CFLAGS or CXXFLAGS if either C or C++ is the currently
+selected language, as well as CPPFLAGS, when compiling. If
+Fortran 77 is the currently selected language then FFLAGS will be
+used when compiling.
+
+
+
+This macro does not try to link; use AC_TRY_LINK if you need to
+do that (see section Examining Libraries).
+
+To check for a library, a function, or a global variable, Autoconf
+@command{configure} scripts try to compile and link a small program that
+uses it. This is unlike Metaconfig, which by default uses nm
+or ar on the C library to try to figure out which functions are
+available. Trying to link with the function is usually a more reliable
+approach because it avoids dealing with the variations in the options
+and output formats of nm and ar and in the location of the
+standard libraries. It also allows configuring for cross-compilation or
+checking a function's runtime behavior if needed. On the other hand, it
+can be slower than scanning the libraries once.
+
+
+
+A few systems have linkers that do not return a failure exit status when
+there are unresolved functions in the link. This bug makes the
+configuration scripts produced by Autoconf unusable on those systems.
+However, some of them can be given options that make the exit status
+correct. This is a problem that Autoconf does not currently handle
+automatically. If users encounter this problem, they might be able to
+solve it by setting LDFLAGS in the environment to pass whatever
+options the linker needs (for example, @option{-Wl,-dn} on @sc{mips
+risc/os}).
+
+
+
+AC_TRY_LINK is used to compile test programs to test for
+functions and global variables. It is also used by AC_CHECK_LIB
+to check for libraries (see section Library Files), by adding the library being
+checked for to LIBS temporarily and trying to link a small
+program.
+
+
+
+
+Depending on the current language (see section Language Choice), create a
+test program to see whether a function whose body consists of
+function-body can be compiled and linked. If the file compiles
+and links successfully, run shell commands action-if-found,
+otherwise run action-if-not-found.
+
+
+
+This macro double quotes both includes and function-body.
+
+
+
+For C and C++, includes is any #include statements needed
+by the code in function-body (includes will be ignored if
+the currently selected language is Fortran 77). This macro also uses
+CFLAGS or CXXFLAGS if either C or C++ is the currently
+selected language, as well as CPPFLAGS, when compiling. If
+Fortran 77 is the currently selected language then FFLAGS will be
+used when compiling. However, both LDFLAGS and LIBS will
+be used during linking in all cases.
+
+
+Depending on the current language (see section Language Choice), create a
+test program to see whether a program whose body consists of
+a prototype of and a call to function can be compiled and linked.
+
+
+
+If the file compiles and links successfully, run shell commands
+action-if-found, otherwise run action-if-not-found.
+
+Sometimes you need to find out how a system performs at run time, such
+as whether a given function has a certain capability or bug. If you
+can, make such checks when your program runs instead of when it is
+configured. You can check for things like the machine's endianness when
+your program initializes itself.
+
+
+
+If you really need to test for a run-time behavior while configuring,
+you can write a test program to determine the result, and compile and
+run it using AC_TRY_RUN. Avoid running test programs if
+possible, because this prevents people from configuring your package for
+cross-compiling.
+
+
+
+
+
+
+If program compiles and links successfully and returns an exit
+status of 0 when executed, run shell commands action-if-true.
+Otherwise, run shell commands action-if-false.
+
+
+
+This macro double quotes program, the text of a program in the
+current language (see section Language Choice), on which shell variable and
+back quote substitutions are performed. This macro uses CFLAGS
+or CXXFLAGS, CPPFLAGS, LDFLAGS, and LIBS
+when compiling.
+
+
+
+If the C compiler being used does not produce executables that run on
+the system where @command{configure} is being run, then the test program is
+not run. If the optional shell commands action-if-cross-compiling
+are given, they are run instead. Otherwise, @command{configure} prints
+an error message and exits.
+
+
+
+In the action-if-false section, the exit status of the program is
+available in the shell variable `$?', but be very careful to limit
+yourself to positive values smaller than 127; bigger values shall be
+saved into a file by the program. Note also that you have simply
+no guarantee that this exit status is issued by the program, or by
+the failure of its compilation. In other words, use this feature if
+sadist only, it was reestablished because the Autoconf maintainers grew
+tired of receiving "bug reports".
+
+
+
+
+Try to provide a pessimistic default value to use when cross-compiling
+makes run-time tests impossible. You do this by passing the optional
+last argument to AC_TRY_RUN. @command{autoconf} prints a warning
+message when creating @command{configure} each time it encounters a call to
+AC_TRY_RUN with no action-if-cross-compiling argument
+given. You may ignore the warning, though users will not be able to
+configure your package for cross-compiling. A few of the macros
+distributed with Autoconf produce this warning message.
+
+
+
+To configure for cross-compiling you can also choose a value for those
+parameters based on the canonical system name (see section Manual Configuration). Alternatively, set up a test results cache file with
+the correct values for the host system (see section Caching Results).
+
+
+
+To provide a default for calls of AC_TRY_RUN that are embedded in
+other macros, including a few of the ones that come with Autoconf, you
+can call AC_PROG_CC before running them. Then, if the shell
+variable cross_compiling is set to `yes', use an alternate
+method to get the results instead of calling the macros.
+
+
+
+
+
+Test programs should not write anything to the standard output. They
+should return 0 if the test succeeds, nonzero otherwise, so that success
+can be distinguished easily from a core dump or other failure;
+segmentation violations and other failures produce a nonzero exit
+status. Test programs should exit, not return, from
+main, because on some systems (old Suns, at least) the argument
+to return in main is ignored.
+
+
+
+Test programs can use #if or #ifdef to check the values of
+preprocessor macros defined by tests that have already run. For
+example, if you call AC_HEADER_STDC, then later on in
+`configure.ac' you can have a test program that includes an
+ANSI C header file conditionally:
+
+
+
+
+#if STDC_HEADERS
+# include <stdlib.h>
+#endif
+
+
+
+If a test program needs to use or create a data file, give it a name
+that starts with `conftest', such as `conftest.data'. The
+@command{configure} script cleans up by running `rm -rf conftest*'
+after running test programs and if the script is interrupted.
+
+
+
+
+
+Function declarations in test programs should have a prototype
+conditionalized for C++. In practice, though, test programs rarely need
+functions that take arguments.
+
+
+
+
+Functions that test programs declare should also be conditionalized for
+C++, which requires `extern "C"' prototypes. Make sure to not
+include any header files containing clashing prototypes.
+
+
+
+
+If a test program calls a function with invalid parameters (just to see
+whether it exists), organize the program to ensure that it never invokes
+that function. You can do this by calling it in another function that is
+never invoked. You can't do it by putting it after a call to
+exit, because GCC version 2 knows that exit never returns
+and optimizes out any code that follows it in the same block.
+
+
+
+If you include any header files, make sure to call the functions
+relevant to them with the correct number of arguments, even if they are
+just 0, to avoid compilation errors due to prototypes. GCC version 2
+has internal prototypes for several functions that it automatically
+inlines; for example, memcpy. To avoid errors when checking for
+them, either pass them the correct number of arguments or redeclare them
+with a different return type (such as char).
+
+
+
+
+
+This section aims at presenting some systems and pointers to
+documentation. It may help you addressing particular problems reported
+by users.
+
+
+
+
+
QNX 4.25
+
+
+QNX is a realtime operating system running on Intel architecture
+meant to be scalable from the small embedded systems to hundred
+processor super-computer. It claims to be POSIX certified. More
+information is available on the @href{www.qnx.com, QNX home page},
+including the @href{http://support.qnx.com/support/docs/qnx4/, QNX
+man pages}.
+
+Some operations are accomplished in several possible ways, depending on
+the UNIX variant. Checking for them essentially requires a "case
+statement". Autoconf does not directly provide one; however, it is
+easy to simulate by using a shell variable to keep track of whether a
+way to perform the operation has been found yet.
+
+
+
+Here is an example that uses the shell variable fstype to keep
+track of whether the remaining cases need to be checked.
+
+
+
+
+AC_MSG_CHECKING([how to get file system type])
+fstype=no
+# The order of these tests is important.
+AC_TRY_CPP([#include <sys/statvfs.h>
+#include <sys/fstyp.h>],
+ [AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4])
+if test $fstype = no; then
+ AC_TRY_CPP([#include <sys/statfs.h>
+#include <sys/fstyp.h>],
+ [AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3])
+fi
+if test $fstype = no; then
+ AC_TRY_CPP([#include <sys/statfs.h>
+#include <sys/vmount.h>],
+ [AC_DEFINE(FSTYPE_AIX_STATFS) fstype=AIX])
+fi
+# (more cases omitted here)
+AC_MSG_RESULT([$fstype])
+
+Autoconf-generated @command{configure} scripts check for the C compiler and
+its features by default. Packages that use other programming languages
+(maybe more than one, e.g. C and C++) need to test features of the
+compilers for the respective languages. The following macros determine
+which programming language is used in the subsequent tests in
+`configure.ac'.
+
+
+
+
+
Macro:AC_LANG(language)
+
+Do compilation tests using the compiler, preprocessor and file
+extensions for the specified language.
+
+
+
+Supported languages are:
+
+
+
+
+
`C'
+
+Do compilation tests using CC and CPP and use extension
+`.c' for test programs.
+
+
`C++'
+
+Do compilation tests using CXX and CXXCPP and use
+extension `.C' for test programs.
+
+
`Fortran 77'
+
+Do compilation tests using F77 and use extension `.f' for
+test programs.
+
+
+
+
+
+
Macro:AC_LANG_PUSH(language)
+
+
+Remember the current language (as set by AC_LANG) on a stack, and
+then select the language. Use this macro and AC_LANG_POP
+in macros that need to temporarily switch to a particular language.
+
+
+
+
+
+
Macro:AC_LANG_POP(@ovar{language})
+
+
+Select the language that is saved on the top of the stack, as set by
+AC_LANG_PUSH, and remove it from the stack.
+
+
+
+If given, language specifies the language we just quit. It
+is a good idea to specify it when it's known (which should be the
+case...), since Autoconf will detect inconsistencies.
+
+
+
+
+AC_LANG_PUSH(Fortran 77)
+# Perform some tests on Fortran 77.
+# ...
+AC_LANG_POP(Fortran 77)
+
+
+
+
+
+
+
Macro:AC_REQUIRE_CPP
+
+
+Ensure that whichever preprocessor would currently be used for tests has
+been found. Calls AC_REQUIRE (see section Prerequisite Macros) with an
+argument of either AC_PROG_CPP or AC_PROG_CXXCPP,
+depending on which language is current.
+
+Once @command{configure} has determined whether a feature exists, what can
+it do to record that information? There are four sorts of things it can
+do: define a C preprocessor symbol, set a variable in the output files,
+save the result in a cache file for future @command{configure} runs, and
+print a message letting the user know the result of the test.
+
+
+
+
+
+A common action to take in response to a feature test is to define a C
+preprocessor symbol indicating the results of the test. That is done by
+calling AC_DEFINE or AC_DEFINE_UNQUOTED.
+
+
+
+By default, AC_OUTPUT places the symbols defined by these macros
+into the output variable DEFS, which contains an option
+@option{-Dsymbol=value} for each symbol defined. Unlike in
+Autoconf version 1, there is no variable DEFS defined while
+@command{configure} is running. To check whether Autoconf macros have
+already defined a certain C preprocessor symbol, test the value of the
+appropriate cache variable, as in this example:
+
+
+
+
+AC_CHECK_FUNC(vprintf, [AC_DEFINE(HAVE_VPRINTF)])
+if test "$ac_cv_func_vprintf" != yes; then
+ AC_CHECK_FUNC(_doprnt, [AC_DEFINE(HAVE_DOPRNT)])
+fi
+
+
+
+If AC_CONFIG_HEADERS has been called, then instead of creating
+DEFS, AC_OUTPUT creates a header file by substituting the
+correct values into #define statements in a template file.
+See section Configuration Header Files, for more information about this kind of
+output.
+
+
+
+
+Define C preprocessor variable variable. If value is given,
+set variable to that value (verbatim), otherwise set it to 1.
+value should not contain literal newlines, and if you are not
+using AC_CONFIG_HEADERS it should not contain any `#'
+characters, as make tends to eat them. To use a shell variable
+(which you need to do in order to define a value containing the M4 quote
+characters `[' or `]'), use AC_DEFINE_UNQUOTED instead.
+description is only useful if you are using
+AC_CONFIG_HEADERS. In this case, description is put into
+the generated `config.h.in' as the comment before the macro define.
+The following example defines the C preprocessor variable
+EQUATION to be the string constant `"$a > $b"':
+
+
+
+
+
+Like AC_DEFINE, but three shell expansions are
+performed--once--on variable and value: variable expansion
+(`$'), command substitution (``'), and backslash escaping
+(`\'). Single and double quote characters in the value have no
+special meaning. Use this macro instead of AC_DEFINE when
+variable or value is a shell variable. Examples:
+
+
+
+
+Due to the syntactical bizarreness of the Bourne shell, do not use
+semicolons to separate AC_DEFINE or AC_DEFINE_UNQUOTED
+calls from other macro calls or shell code; that can cause syntax errors
+in the resulting @command{configure} script. Use either spaces or
+newlines. That is, do this:
+
+
+
+
+Another way to record the results of tests is to set output
+variables, which are shell variables whose values are substituted into
+files that @command{configure} outputs. The two macros below create new
+output variables. See section Preset Output Variables, for a list of output
+variables that are always available.
+
+
+
+
+
Macro:AC_SUBST(variable, @ovar{value})
+
+
+Create an output variable from a shell variable. Make AC_OUTPUT
+substitute the variable variable into output files (typically one
+or more `Makefile's). This means that AC_OUTPUT will
+replace instances of `@variable@' in input files with the
+value that the shell variable variable has when AC_OUTPUT
+is called. This value of variable should not contain literal
+newlines.
+
+
+
+If value is given, in addition assign it to `variable'.
+
+
+
+
+
+
Macro:AC_SUBST_FILE(variable)
+
+
+Another way to create an output variable from a shell variable. Make
+AC_OUTPUT insert (without substitutions) the contents of the file
+named by shell variable variable into output files. This means
+that AC_OUTPUT will replace instances of
+`@variable@' in output files (such as `Makefile.in')
+with the contents of the file that the shell variable variable
+names when AC_OUTPUT is called. Set the variable to
+`/dev/null' for cases that do not have a file to insert.
+
+
+
+This macro is useful for inserting `Makefile' fragments containing
+special dependencies or other make directives for particular host
+or target types into `Makefile's. For example, `configure.ac'
+could contain:
+
+
+
+
+
+
+Running @command{configure} in different environments can be extremely
+dangerous. If for instance the user runs `CC=bizarre-cc
+./configure', then the cache, `config.h' and many other output
+files will depend upon @command{bizarre-cc} being the C compiler. If
+for some reason the user runs @command{/configure} again, or if it is
+run via `./config.status --recheck', (See section Automatic Remaking,
+and see section Recreating a Configuration), then the configuration can be
+inconsistent, composed of results depending upon two different
+compilers.
+
+
+
+Such variables are named precious variables, and can be declared
+as such by AC_ARG_VAR.
+
+
+
+
+
Macro:AC_ARG_VAR(variable, description)
+
+
+Declare variable is a precious variable, and include its
+description in the variable section of `./configure --help'.
+
+
+
+Being precious means that
+
+
+
+
+variable is AC_SUBST'd.
+
+
+
+variable is kept in the cache including if it was not specified on
+the `./configure' command line. Indeed, while @command{configure}
+can notice the definition of CC in `./configure
+CC=bizarre-cc', it is impossible to notice it in `CC=bizarre-cc
+./configure', which, unfortunately, is what most users do.
+
+
+
+variable is checked for consistency between two
+@command{configure} runs. For instance:
+
+
+
+$ ./configure --silent --config-cache
+$ CC=cc ./configure --silent --config-cache
+configure: error: `CC' was not set in the previous run
+configure: error: changes in the environment can compromise \
+the build
+configure: error: run `make distclean' and/or \
+`rm config.cache' and start over
+
+
+and similarly if the variable is unset, or if its content is changed.
+
+
+
+variable is kept during automatic reconfiguration
+(see section Recreating a Configuration) as if it had been passed as a command
+line argument, including when no cache is used:
+
+
+
+To avoid checking for the same features repeatedly in various
+@command{configure} scripts (or in repeated runs of one script),
+@command{configure} can optionally save the results of many checks in a
+cache file (see section Cache Files). If a @command{configure} script
+runs with caching enabled and finds a cache file, it reads the results
+of previous runs from the cache and avoids rerunning those checks. As a
+result, @command{configure} can then run much faster than if it had to
+perform all of the checks every time.
+
+
+
+
+Ensure that the results of the check identified by cache-id are
+available. If the results of the check were in the cache file that was
+read, and @command{configure} was not given the @option{--quiet} or
+@option{--silent} option, print a message saying that the result was
+cached; otherwise, run the shell commands commands-to-set-it. If
+the shell commands are run to determine the value, the value will be
+saved in the cache file just before @command{configure} creates its output
+files. See section Cache Variable Names, for how to choose the name of the
+cache-id variable.
+
+
+
+The commands-to-set-itmust have no side effects except for
+setting the variable cache-id, see below.
+
+
+A wrapper for AC_CACHE_VAL that takes care of printing the
+messages. This macro provides a convenient shorthand for the most
+common way to use these macros. It calls AC_MSG_CHECKING for
+message, then AC_CACHE_VAL with the cache-id and
+commands arguments, and AC_MSG_RESULT with cache-id.
+
+
+
+The commands-to-set-itmust have no side effects except for
+setting the variable cache-id, see below.
+
+
+
+
+It is very common to find buggy macros using AC_CACHE_VAL or
+AC_CACHE_CHECK, because people are tempted to call
+AC_DEFINE in the commands-to-set-it. Instead, the code that
+follows the call to AC_CACHE_VAL should call
+AC_DEFINE, by examining the value of the cache variable. For
+instance, the following macro is broken:
+
+
+
+
+AC_DEFUN([AC_SHELL_TRUE],
+[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
+ [ac_cv_shell_true_works=no
+ true && ac_cv_shell_true_works=yes
+ if test $ac_cv_shell_true_works = yes; then
+ AC_DEFINE([TRUE_WORKS], 1
+ [Define if `true(1)' works properly.])
+ fi])
+])
+
+
+
+This fails if the cache is enabled: the second time this macro is run,
+TRUE_WORKSwill not be defined. The proper implementation
+is:
+
+
+
+
+AC_DEFUN([AC_SHELL_TRUE],
+[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
+ [ac_cv_shell_true_works=no
+ true && ac_cv_shell_true_works=yes])
+ if test $ac_cv_shell_true_works = yes; then
+ AC_DEFINE([TRUE_WORKS], 1
+ [Define if `true(1)' works properly.])
+ fi
+])
+
+
+
+Also, commands-to-set-it should not print any messages, for
+example with AC_MSG_CHECKING; do that before calling
+AC_CACHE_VAL, so the messages are printed regardless of whether
+the results of the check are retrieved from the cache or determined by
+running the shell commands.
+
+
+
+
+
+for example, `ac_cv_header_stat_broken' or
+`ac_cv_prog_gcc_traditional'. The parts of the variable name are:
+
+
+
+
+
package-prefix
+
+An abbreviation for your package or organization; the same prefix you
+begin local Autoconf macros with, except lowercase by convention.
+For cache values used by the distributed Autoconf macros, this value is
+`ac'.
+
+
_cv_
+
+Indicates that this shell variable is a cache value. This string
+must be present in the variable name, including the leading
+underscore.
+
+
value-type
+
+A convention for classifying cache values, to produce a rational naming
+system. The values used in Autoconf are listed in section Macro Names.
+
+
specific-value
+
+Which member of the class of cache values this test applies to.
+For example, which function (`alloca'), program (`gcc'), or
+output variable (`INSTALL').
+
+
additional-options
+
+Any particular behavior of the specific member that this test applies to.
+For example, `broken' or `set'. This part of the name may
+be omitted if it does not apply.
+
+
+
+The values assigned to cache variables may not contain newlines.
+Usually, their values will be boolean (`yes' or `no') or the
+names of files or functions; so this is not an important restriction.
+
+
+
+
+
+A cache file is a shell script that caches the results of configure
+tests run on one system so they can be shared between configure scripts
+and configure runs. It is not useful on other systems. If its contents
+are invalid for some reason, the user may delete or edit it.
+
+
+
+By default, @command{configure} uses no cache file (technically, it uses
+@option{--cache-file=/dev/null}), to avoid problems caused by accidental
+use of stale cache files.
+
+
+
+To enable caching, @command{configure} accepts @option{--config-cache} (or
+@option{-C}) to cache results in the file `config.cache'.
+Alternatively, @option{--cache-file=file} specifies that
+file be the cache file. The cache file is created if it does not
+exist already. When @command{configure} calls @command{configure} scripts in
+subdirectories, it uses the @option{--cache-file} argument so that they
+share the same cache. See section Configuring Other Packages in Subdirectories, for information on
+configuring subdirectories with the AC_CONFIG_SUBDIRS macro.
+
+
+
+`config.status' only pays attention to the cache file if it is
+given the @option{--recheck} option, which makes it rerun
+@command{configure}.
+
+
+
+It is wrong to try to distribute cache files for particular system types.
+There is too much room for error in doing that, and too much
+administrative overhead in maintaining them. For any features that
+can't be guessed automatically, use the standard method of the canonical
+system type and linking files (see section Manual Configuration).
+
+
+
+The site initialization script can specify a site-wide cache file to
+use, instead of the usual per-program cache. In this case, the cache
+file will gradually accumulate information whenever someone runs a new
+@command{configure} script. (Running @command{configure} merges the new cache
+results with the existing cache file.) This may cause problems,
+however, if the system configuration (e.g. the installed libraries or
+compilers) changes and the stale cache file is not deleted.
+
+
+
+
+
+If your configure script, or a macro called from configure.ac, happens
+to abort the configure process, it may be useful to checkpoint the cache
+a few times at key points using AC_CACHE_SAVE. Doing so will
+reduce the amount of time it takes to re-run the configure script with
+(hopefully) the error that caused the previous abort corrected.
+
+
+
+
+
Macro:AC_CACHE_LOAD
+
+
+Loads values from existing cache file, or creates a new cache file if a
+cache file is not found. Called automatically from AC_INIT.
+
+
+
+
+
+
Macro:AC_CACHE_SAVE
+
+
+Flushes all cached values to the cache file. Called automatically from
+AC_OUTPUT, but it can be quite useful to call
+AC_CACHE_SAVE at key points in configure.ac.
+
+
+
+
+For instance:
+
+
+
+
+ ... AC_INIT, etc. ...
+# Checks for programs.
+AC_PROG_CC
+AC_PROG_GCC_TRADITIONAL
+ ... more program checks ...
+AC_CACHE_SAVE
+
+# Checks for libraries.
+AC_CHECK_LIB(nsl, gethostbyname)
+AC_CHECK_LIB(socket, connect)
+ ... more lib checks ...
+AC_CACHE_SAVE
+
+# Might abort...
+AM_PATH_GTK(1.0.2,, [AC_MSG_ERROR([GTK not in path])])
+AM_PATH_GTKMM(0.9.5,, [AC_MSG_ERROR([GTK not in path])])
+ ... AC_OUTPUT, etc. ...
+
+@command{configure} scripts need to give users running them several kinds
+of information. The following macros print messages in ways appropriate
+for each kind. The arguments to all of them get enclosed in shell
+double quotes, so the shell performs variable and back-quote
+substitution on them.
+
+
+
+These macros are all wrappers around the echo shell command.
+@command{configure} scripts should rarely need to run echo directly
+to print messages for the user. Using these macros makes it easy to
+change how and when each kind of message is printed; such changes need
+only be made to the macro definitions and all of the callers will change
+automatically.
+
+
+
+To diagnose static issues, i.e., when @command{autoconf} is run, see
+section Reporting Messages.
+
+
+
+
+
Macro:AC_MSG_CHECKING(feature-description)
+
+
+Notify the user that @command{configure} is checking for a particular
+feature. This macro prints a message that starts with `checking '
+and ends with `...' and no newline. It must be followed by a call
+to AC_MSG_RESULT to print the result of the check and the
+newline. The feature-description should be something like
+`whether the Fortran compiler accepts C++ comments' or `for
+c89'.
+
+
+
+This macro prints nothing if @command{configure} is run with the
+@option{--quiet} or @option{--silent} option.
+
+
+
+
+
+
Macro:AC_MSG_RESULT(result-description)
+
+
+Notify the user of the results of a check. result-description is
+almost always the value of the cache variable for the check, typically
+`yes', `no', or a file name. This macro should follow a call
+to AC_MSG_CHECKING, and the result-description should be
+the completion of the message printed by the call to
+AC_MSG_CHECKING.
+
+
+
+This macro prints nothing if @command{configure} is run with the
+@option{--quiet} or @option{--silent} option.
+
+
+
+
+
+
Macro:AC_MSG_NOTICE(message)
+
+
+Deliver the message to the user. It is useful mainly to print a
+general description of the overall purpose of a group of feature checks,
+e.g.,
+
+
+
+
+AC_MSG_NOTICE([checking if stack overflow is detectable])
+
+
+
+This macro prints nothing if @command{configure} is run with the
+@option{--quiet} or @option{--silent} option.
+
+
+Notify the user of an error that prevents @command{configure} from
+completing. This macro prints an error message to the standard error
+output and exits @command{configure} with exit-status (1 by default).
+error-description should be something like `invalid value
+$HOME for \$HOME'.
+
+
+
+The error-description should start with a lower-case letter, and
+"cannot" is preferred to "can't".
+
+
+
+
+
+
Macro:AC_MSG_WARN(problem-description)
+
+
+Notify the @command{configure} user of a possible problem. This macro
+prints the message to the standard error output; @command{configure}
+continues running afterward, so macros that call AC_MSG_WARN should
+provide a default (back-up) behavior for the situations they warn about.
+problem-description should be something like `ln -s seems to
+make hard links'.
+
+Autoconf is written on top of two layers: M4sugar, which provides
+convenient macros for pure M4 programming, and M4sh, which
+provides macros dedicated to shell script generation.
+
+
+
+As of this version of Autoconf, these two layers are still experimental,
+and their interface might change in the future. As a matter of fact,
+anything that is not documented must not be used.
+
+
+
+
+
+The most common brokenness of existing macros is an improper quotation.
+This section, which users of Autoconf can skip, but which macro writers
+must read, first justifies the quotation scheme that was chosen
+for Autoconf and then ends with a rule of thumb. Understanding the
+former helps one to follow the latter.
+
+
+
+
+
+To fully understand where proper quotation is important, you first need
+to know what are the special characters in Autoconf: `#' introduces
+a comment inside which no macro expansion is performed, `,'
+separates arguments, `[' and `]' are the quotes themselves,
+and finally `(' and `)' (which m4 tries to match by
+pairs).
+
+
+
+In order to understand the delicate case of macro calls, we first have
+to present some obvious failures. Below they are "obvious-ified",
+although you find them in real life, they are usually in disguise.
+
+
+
+Comments, introduced by a hash and running up to the newline, are opaque
+tokens to the top level: active characters are turned off, and there is
+no macro expansion:
+
+
+
+
+# define([def], ine)
+=># define([def], ine)
+
+
+
+Each time there can be a macro expansion, there is a quotation
+expansion; i.e., one level of quotes is stripped:
+
+
+
+
+Let's proceed on the interaction between active characters and macros
+with this small macro, which just returns its first argument:
+
+
+
+
+define([car], [$1])
+
+
+
+The two pairs of quotes above are not part of the arguments of
+define; rather, they are understood by the top level when it
+tries to find the arguments of define. Therefore, it is
+equivalent to write:
+
+
+
+
+define(car, $1)
+
+
+
+But, while it is acceptable for a `configure.ac' to avoid unneeded
+quotes, it is bad practice for Autoconf macros which must both be more
+robust and also advocate perfect style.
+
+
+
+At the top level, there are only two possible quotings: either you
+quote or you don't:
+
+
+
+
+car(foo, bar, baz)
+=>foo
+[car(foo, bar, baz)]
+=>car(foo, bar, baz)
+
+
+
+Let's pay attention to the special characters:
+
+
+
+
+car(#)
+error-->EOF in argument list
+
+
+
+The closing parenthesis is hidden in the comment; with a hypothetical
+quoting, the top level understood it this way:
+
+
+
+
+car([#)]
+
+
+
+Proper quotation, of course, fixes the problem:
+
+
+
+
+car([#])
+=>#
+
+
+
+The reader will easily understand the following examples:
+
+
+
+
+In the first case, the top level looks for the arguments of car,
+and finds `active'. Because m4 evaluates its arguments
+before applying the macro, `active' is expanded, which results in:
+
+
+
+
+car(ACT, IVE)
+=>ACT
+
+
+
+In the second case, the top level gives `active' as first and only
+argument of car, which results in:
+
+
+
+
+active
+=>ACT, IVE
+
+
+
+i.e., the argument is evaluated after the macro that invokes it.
+In the third case, car receives `[active]', which results in:
+
+
+
+
+[active]
+=>active
+
+
+
+exactly as we already saw above.
+
+
+
+The example above, applied to a more realistic example, gives:
+
+
+
+
+Huh? The first case is easily understood, but why is the second wrong,
+and the third right? To understand that, you must know that after
+m4 expands a macro, the resulting text is immediately subjected
+to macro expansion and quote removal. This means that the quote removal
+occurs twice--first before the argument is passed to the car
+macro, and second after the car macro expands to the first
+argument.
+
+
+
+As the author of the Autoconf macro car, you then consider it to
+be incorrect that your users have to double-quote the arguments of
+car, so you "fix" your macro. Let's call it qar for
+quoted car:
+
+
+
+
+define([qar], [[$1]])
+
+
+
+and check that qar is properly fixed:
+
+
+
+
+qar([int tab[10];])
+=>int tab[10];
+
+
+
+Ahhh! That's much better.
+
+
+
+But note what you've done: now that the arguments are literal strings,
+if the user wants to use the results of expansions as arguments, she has
+to use an unquoted macro call:
+
+
+
+
+qar(active)
+=>ACT
+
+
+
+where she wanted to reproduce what she used to do with car:
+
+
+
+
+car([active])
+=>ACT, IVE
+
+
+
+Worse yet: she wants to use a macro that produces a set of cpp
+macros:
+
+
+
+
+define([my_includes], [#include <stdio.h>])
+car([my_includes])
+=>#include <stdio.h>
+qar(my_includes)
+error-->EOF in argument list
+
+
+
+This macro, qar, because it double quotes its arguments, forces
+its users to leave their macro calls unquoted, which is dangerous.
+Commas and other active symbols are interpreted by m4 before
+they are given to the macro, often not in the way the users expect.
+Also, because qar behaves differently from the other macros,
+it's an exception that should be avoided in Autoconf.
+
+
+
+
+
+The temptation is often high to bypass proper quotation, in particular
+when it's late at night. Then, many experienced Autoconf hackers
+finally surrender to the dark side of the force and use the ultimate
+weapon: changequote.
+
+
+
+The M4 builtin changequote belongs to a set of primitives that
+allow one to adjust the syntax of the language to adjust it to her
+needs. For instance, by default M4 uses ``' and `'' as
+quotes, but in the context of shell programming (and actually of most
+programming languages), it's about the worst choice one can make:
+because of strings and back quoted expression in shell (such as
+`'this'' and ``that`'), because of literal characters in usual
+programming language (as in `'0''), there are many unbalanced
+``' and `''. Proper M4 quotation then becomes a nightmare, if
+not impossible. In order to make M4 useful in such a context, its
+designers have equipped it with changequote, which makes it
+possible to chose another pair of quotes. M4sugar, M4sh, Autoconf, and
+Autotest all have chosen to use `[' and `]'. Not especially
+because they are unlikely characters, but because they are
+characters unlikely to be unbalanced.
+
+
+
+There are other magic primitives, such as changecom to specify
+what syntactic forms are comments (it is common to see
+`changecom(<!--, -->)' when M4 is used to produce HTML pages),
+changeword and changesyntax to change other syntactic
+details (such as the character to denote the n-th argument, `$' by
+default, the parenthesis around arguments etc.).
+
+
+
+These primitives are really meant to make M4 more useful for specific
+domains: they should be considered like command line options:
+@option{--quotes}, @option{--comments}, @option{--words}, and
+--syntax. Nevertheless, they are implemented as M4 builtins, as
+it makes M4 libraries self contained (no need for additional options).
+
+
+
+There lies the problem...
+
+
+
+The problem is that it is then tempting to use them in the middle of an
+M4 script, as opposed to its initialization. This, if not carefully
+thought, can lead to disastrous effects: you are changing the
+language in the middle of the execution. Changing and restoring the
+syntax is often not enough: if you happened to invoke macros in between,
+these macros will be lost, as the current syntax will probably not be
+the one they were implemented with.
+
+
+
+
+
+When writing an autoconf macro you may occasionally need to generate
+special characters that are difficult to express with the standard
+autoconf quoting rules. For example, you may need to output the regular
+expression `[^[]', which matches any character other than `['.
+This expression contains unbalanced brackets so it cannot be put easily
+into an M4 macro.
+
+
+
+You can work around this problem by using one of the following
+quadrigraphs:
+
+
+
+
+
`@<:@'
+
+`['
+
`@:>@'
+
+`]'
+
`@S|@'
+
+`$'
+
`@%:@'
+
+`#'
+
`@&t@'
+
+Expands to nothing.
+
+
+
+Quadrigraphs are replaced at a late stage of the translation process,
+after @command{m4} is run, so they do not get in the way of M4 quoting.
+For example, the string `^@<:@', independently of its quotation,
+will appear as `^[' in the output.
+
+
+
+The empty quadrigraph can be used:
+
+
+
+
+
to mark explicitly trailing spaces
+
+Trailing spaces are smashed by @command{autom4te}. This is a feature.
+
+
to produce other quadrigraphs
+
+For instance `@<@&t@:@' produces `@<:@'.
+
+
to escape occurrences of forbidden patterns
+
+For instance you might want to mention AC_FOO is a comment, while
+still being sure that @command{autom4te} will still catch unexpanded
+`AC_*'. Then write `AC@&t@_FOO'.
+
+
+
+The name `@&t@' was suggested by Paul Eggert:
+
+
+
+
+
+I should give some credit to the `@&t@' pun. The `&' is my
+own invention, but the `t' came from the source code of the
+ALGOL68C compiler, written by Steve Bourne (of Bourne shell fame),
+and which used `mt' to denote the empty string. In C, it would
+have looked like something like:
+
+
+
+
+char const mt[] = "";
+
+
+
+but of course the source code was written in Algol 68.
+
+
+
+I don't know where he got `mt' from: it could have been his own
+invention, and I suppose it could have been a common pun around the
+Cambridge University computer lab at the time.
+
+To conclude, the quotation rule of thumb is:
+
+
+
+One pair of quotes per pair of parentheses.
+
+
+
+Never over-quote, never under-quote, in particular in the definition of
+macros. In the few places where the macros need to use brackets
+(usually in C program text or regular expressions), properly quote
+the arguments!
+
+
+
+It is common to read Autoconf programs with snippets like:
+
+
+
+
+The M4-fluent reader will note that these two examples are rigorously
+equivalent, since m4 swallows both the `changequote(<<, >>)'
+and `<<'`>>' when it collects the arguments: these
+quotes are not part of the arguments!
+
+
+
+Simplified, the example above is just doing this:
+
+
+
+
+See See section Quadrigraphs, for what to do if you run into a hopeless case
+where quoting does not suffice.
+
+
+
+When you create a @command{configure} script using newly written macros,
+examine it carefully to check whether you need to add more quotes in
+your macros. If one or more words have disappeared in the m4
+output, you need more quotes. When in doubt, quote.
+
+
+
+However, it's also possible to put on too many layers of quotes. If
+this happens, the resulting @command{configure} script will contain
+unexpanded macros. The @command{autoconf} program checks for this problem
+by doing `grep AC_ configure'.
+
+
+
+
+
+The Autoconf suite, including M4sugar, M4sh, and Autotest in addition to
+Autoconf per se, heavily rely on M4. All these different uses revealed
+common needs factored into a layer over @command{m4}:
+@command{autom4te}(3).
+
+
+
+@command{autom4te} should basically considered as a replacement of
+@command{m4} itself. In particular, its handling of command line
+arguments is modeled after M4's:
+
+
+
+
+autom4te optionsfiles
+
+
+
+where the files are directly passed to @command{m4}. In addition
+to the regular expansion, it handles the replacement of the quadrigraphs
+(see section Quadrigraphs), and of `__oline__', the current line in the
+output. It supports an extended syntax for the files:
+
+
+
+
+
`file.m4f'
+
+This file is an M4 frozen file. Note that all the previous files
+are ignored. See the option @option{--melt} for the rationale.
+
+
`file?'
+
+If found in the library path, the file is included for expansion,
+otherwise it is ignored instead of triggering a failure.
+
+
+
+Of course, it supports the Autoconf common subset of options:
+
+
+
+
+
@option{--help}
+
+
@option{-h}
+
+Print a summary of the command line options and exit.
+
+
@option{--version}
+
+
@option{-V}
+
+Print the version number of Autoconf and exit.
+
+
@option{--verbose}
+
+
@option{-v}
+
+Report processing steps.
+
+
@option{--debug}
+
+
@option{-d}
+
+Don't remove the temporary files and be even more verbose.
+
+
@option{--include=dir}
+
+
@option{-I dir}
+
+Also look for input files in dir. Multiple invocations
+accumulate. Contrary to M4 but in agreement with common sense,
+directories are browsed from last to first.
+
+
@option{--output=file}
+
+
@option{-o file}
+
+Save output (script or trace) to file. The file @option{-} stands
+for the standard output.
+
+
+
+As an extension of @command{m4}, it includes the following options:
+
+
+
+
+
@option{--warnings=category}
+
+
@option{-W category}
+
+
+Report the warnings related to category (which can actually be a
+comma separated list). See section Reporting Messages, macro
+AC_DIAGNOSE, for a comprehensive list of categories. Special
+values include:
+
+
+
+
`all'
+
+report all the warnings
+
+
`none'
+
+report none
+
+
`error'
+
+treats warnings as errors
+
+
`no-category'
+
+disable warnings falling into category
+
+
+Warnings about `syntax' are enabled by default, and the environment
+variable WARNINGS, a comma separated list of categories, is
+honored. @command{autom4te -W category} will actually
+behave as if you had run:
+
+
+
+autom4te --warnings=syntax,$WARNINGS,category
+
+
+If you want to disable @command{autom4te}'s defaults and
+WARNINGS, but (for example) enable the warnings about obsolete
+constructs, you would use @option{-W none,obsolete}.
+
+
+
+@command{autom4te} displays a back trace for errors, but not for
+warnings; if you want them, just pass @option{-W error}. For instance,
+on this `configure.ac':
+
+
+
+$ autom4te -l autoconf -Wcross
+configure.ac:8: warning: AC_TRY_RUN called without default \
+to allow cross compiling
+$ autom4te -l autoconf -Wcross,error
+configure.ac:8: error: AC_TRY_RUN called without default \
+to allow cross compiling
+acgeneral.m4:3044: AC_TRY_RUN is expanded from...
+configure.ac:2: INNER is expanded from...
+configure.ac:5: OUTER is expanded from...
+configure.ac:8: the top level
+
+
+
@option{--melt}
+
+
@option{-m}
+
+Do not use frozen files. Any argument file.m4f will be
+replaced with file.m4. This helps tracing the macros which
+are executed only when the files are frozen, typically
+m4_define. For instance, running:
+
+
+
+autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
+
+
+is roughly equivalent to running:
+
+
+
+m4 1.m4 2.m4 3.m4 4.m4 input.m4
+
+
+while
+
+
+
+autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
+
+
+is equivalent to:
+
+
+
+m4 --reload-state=4.m4f input.m4
+
+
+
@option{--freeze}
+
+
@option{-f}
+
+Produce a frozen state file. @command{autom4te} freezing is stricter
+than M4's: it must produce no warnings, and no output other than empty
+lines (a line with white spaces is not empty) and comments
+(starting with `#'). Please, note that contrary to @command{m4},
+this options takes no argument:
+
+
+
+Set the mode of the non traces output to octal-mode. By default,
+`0666'.
+
+
+
+
+As another additional feature over @command{m4}, @command{autom4te}
+caches its results. GNU M4 is able to produce a regular output and
+traces at the same time. Traces are heavily used in the GNU Build
+System: @command{autoheader} uses them to build `config.h.in',
+@command{autoreconf} to determine what GNU Build System components are
+used, @command{automake} to "parse" `configure.ac' etc. To save
+the long runs of @command{m4}, traces are cached while performing
+regular expansion, and conversely. This cache is (actually, the caches
+are) stored in the directory `autom4te.cache'. It can safely
+be removed at any moment (especially if for some reason
+@command{autom4te} considers it is trashed).
+
+
+
+
+
@option{--force}
+
+
@option{-f}
+
+Do not consider the cache (but update it anyway).
+
+
+
+Because traces are so important to the GNU Build System,
+@command{autom4te} provides high level tracing features as compared to
+M4, and helps exploiting the cache:
+
+
+
+
+
@option{--trace=macro[:format]}
+
+
@option{-t macro[:format]}
+
+Trace the invocations to macro according to the format.
+Multiple @option{--trace} arguments can be used to list several macros.
+Multiple @option{--trace} arguments for a single macro are not
+cumulative; instead, you should just make format as long as
+needed.
+
+The format is a regular string, with newlines if desired, and
+several special escape codes. It defaults to `$f:$l:$n:$%'. It can
+use the following special escapes:
+
+
+
+
`$$'
+
+The character `$'.
+
+
`$f'
+
+The filename from which macro is called.
+
+
`$l'
+
+The line number from which macro is called.
+
+
`$d'
+
+The depth of the macro call. This is an M4 technical detail that
+you probably don't want to know about.
+
+
`$n'
+
+The name of the macro.
+
+
`$num'
+
+The numth argument of the call to macro.
+
+
`$@'
+
+
`$sep@'
+
+
`${separator}@'
+
+All the arguments passed to macro, separated by the character
+sep or the string separator (`,' by default). Each
+argument is quoted, i.e. enclosed in a pair of square brackets.
+
+
`$*'
+
+
`$sep*'
+
+
`${separator}*'
+
+As above, but the arguments are not quoted.
+
+
`$%'
+
+
`$sep%'
+
+
`${separator}%'
+
+As above, but the arguments are not quoted, all new line characters in
+the arguments are smashed, and the default separator is `:'.
+
+The escape `$%' produces single-line trace outputs (unless you put
+newlines in the `separator'), while `$@' and `$*' do
+not.
+
+Cache the traces of macro, but do not enable traces. This is
+especially important to save cpu cycles in the future. For instance,
+when invoked, @command{autoconf} preselects all the macros that
+@command{autoheader}, automake, autoreconf etc. will
+trace, so that running @command{m4} is not needed to trace them: the
+cache suffices. This results in a huge speed-up.
+
+
+
+
+Finally, @command{autom4te} introduces the concept of @dfn{Autom4te
+libraries}. They consists in a powerful yet extremely simple feature:
+sets of combined command line arguments:
+
+
+
+
+
@option{--language=language}
+
+
@option{-l =language}
+
+Use the language Autom4te library. Current languages include:
+
+
+
+
M4sugar
+
+create M4sugar output.
+
+
M4sh
+
+create M4sh executable shell scripts.
+
+
Autotest
+
+create Autotest executable test suites.
+
+
Autoconf
+
+create Autoconf executable configure scripts.
+
+
+
+
+
+As an example, if Autoconf is installed in its default location,
+`/usr/local', running `autom4te -l m4sugar foo.m4' is strictly
+equivalent to running `autom4te --include /usr/local/share/autoconf
+m4sugar/m4sugar.m4f --warning syntax foo.m4'. Recursive expansion
+applies: running `autom4te -l m4sh foo.m4', is the same as
+`autom4te --language M4sugar m4sugar/m4sh.m4f foo.m4', i.e.,
+`autom4te --include /usr/local/share/autoconf m4sugar/m4sugar.m4f
+m4sugar/m4sh.m4f --mode 777 foo.m4'. The definition of the languages is
+stored in `autom4te.cfg'.
+
+
+
+
+
+
+M4 by itself provides only a small, but sufficient, set of all-purpose
+macros. M4sugar introduces additional generic macros. Its name was
+coined by Lars J. Aas: "Readability And Greater Understanding Stands 4
+M4sugar".
+
+
+
+
+
+
+This macro corresponds to patsubst. The name m4_patsubst
+is kept for future versions of M4sh, on top of GNU M4 which will
+provide extended regular expression syntax via epatsubst.
+
+
+
+
+
+
Macro:m4_popdef(macro)
+
+
+Contrary to the M4 builtin, this macro fails if macro is not
+defined. See m4_undefine.
+
+
+This macro corresponds to regexp. The name m4_regexp
+is kept for future versions of M4sh, on top of GNU M4 which will
+provide extended regular expression syntax via eregexp.
+
+
+
+
+
+
Macro:m4_wrap(text)
+
+
+This macro corresponds to m4wrap.
+
+
+
+You are encouraged to end text with `[]', so that there are
+no risks that two consecutive invocations of m4_wrap result in an
+unexpected pasting of tokens, as in
+
+
+
+
+The following macros give some control over the order of the evaluation
+by adding or removing levels of quotes. They are meant for hard core M4
+programmers.
+
+
+
+
+
Macro:m4_dquote(arg1, ...)
+
+
+Return the arguments as a quoted list of quoted arguments.
+
+
+
+
+
+
Macro:m4_quote(arg1, ...)
+
+
+Return the arguments as a single entity, i.e., wrap them into a pair of
+quotes.
+
+
+
+
+The following example aims at emphasing the difference between (i), not
+using these macros, (ii), using m4_quote, and (iii), using
+m4_dquote.
+
+
+
+
+$ cat example.m4
+# Over quote, so that quotes are visible.
+m4_define([show], [$[]1 = [$1], $[]@ = [$@]])
+m4_divert(0)dnl
+show(a, b)
+show(m4_quote(a, b))
+show(m4_dquote(a, b))
+$ autom4te -l m4sugar example.m4
+$1 = a, $@ = [a],[b]
+$1 = a,b, $@ = [a,b]
+$1 = [a],[b], $@ = [[a],[b]]
+
+M4sugar provides a means to define suspicious patterns, patterns
+describing tokens which should not be found in the output. For
+instance, if an Autoconf `configure' script includes tokens such as
+`AC_DEFINE', or `dnl', then most probably something went
+wrong (typically a macro was not evaluated because of over quotation).
+
+
+
+M4sugar forbids all the tokens matching `^m4_' and `^dnl$'.
+
+
+
+
+
Macro:m4_pattern_forbid(pattern)
+
+
+Declare no token matching pattern must be found in the output.
+Comments are not checked; this can be a problem if, for instance, you
+have some macro left unexpanded after an `#include'. No consensus
+is currently found in the Autoconf community, as some people consider it
+should be valid to name macros in comments (which doesn't makes sense to
+the author of this documentation, as `#'-comments should document
+the output, not the input, documented vy `dnl'-comments).
+
+
+
+
+Of course, you might encounter exceptions to these generic rules, for
+instance you might have to refer to `$m4_flags'.
+
+
+
+
+
Macro:m4_pattern_allow(pattern)
+
+
+Any token matching pattern is allowed, including if it matches an
+m4_pattern_forbid pattern.
+
+M4sh provides portable alternatives for some common shell constructs
+that unfortunately are not portable in practice.
+
+
+
+
+
Macro:AS_DIRNAME(pathname)
+
+
+Return the directory portion of pathname, using the algorithm
+required by POSIX. See section Limitations of Usual Tools, for more
+details about what this returns and why it is more portable than the
+@command{dirname} command.
+
+When you write a feature test that could be applicable to more than one
+software package, the best thing to do is encapsulate it in a new macro.
+Here are some instructions and guidelines for writing Autoconf macros.
+
+
+
+
+
+
+Autoconf macros are defined using the AC_DEFUN macro, which is
+similar to the M4 builtin m4_define macro. In addition to
+defining a macro, AC_DEFUN adds to it some code that is used to
+constrain the order in which macros are called (see section Prerequisite Macros).
+
+
+
+You can refer to any arguments passed to the macro as `$1',
+`$2', etc. See section `How to define new macros' in GNU m4, for more complete information on writing M4 macros.
+
+
+
+Be sure to properly quote both the macro-bodyand the
+macro-name to avoid any problems if the macro happens to have
+been previously defined.
+
+
+
+Each macro should have a header comment that gives its prototype, and a
+brief description. When arguments have default values, display them in
+the prototype. For example:
+
+
+
+
+Comments about the macro should be left in the header comment. Most
+other comments will make their way into `configure', so just keep
+using `#' to introduce comments.
+
+
+
+
+If you have some very special comments about pure M4 code, comments
+that make no sense in `configure' and in the header comment, then
+use the builtin dnl: it causes m4 to discard the text
+through the next newline.
+
+
+
+Keep in mind that dnl is rarely needed to introduce comments;
+dnl is more useful to get rid of the newlines following macros
+that produce no output, such as AC_REQUIRE.
+
+
+
+
+
+All of the Autoconf macros have all-uppercase names starting with
+`AC_' to prevent them from accidentally conflicting with other
+text. All shell variables that they use for internal purposes have
+mostly-lowercase names starting with `ac_'. To ensure that your
+macros don't conflict with present or future Autoconf macros, you should
+prefix your own macro names and any shell variables they use with some
+other sequence. Possibilities include your initials, or an abbreviation
+for the name of your organization or software package.
+
+
+
+Most of the Autoconf macros' names follow a structured naming convention
+that indicates the kind of feature check by the name. The macro names
+consist of several words, separated by underscores, going from most
+general to most specific. The names of their cache variables use the
+same convention (see section Cache Variable Names, for more information on
+them).
+
+
+
+The first word of the name after `AC_' usually tells the category
+of feature being tested. Here are the categories used in Autoconf for
+specific test macros, the kind of macro that you are more likely to
+write. They are also used for cache variables, in all-lowercase. Use
+them where applicable; where they're not, invent your own categories.
+
+
+
+
+
C
+
+C language builtin features.
+
DECL
+
+Declarations of C variables in header files.
+
FUNC
+
+Functions in libraries.
+
GROUP
+
+UNIX group owners of files.
+
HEADER
+
+Header files.
+
LIB
+
+C libraries.
+
PATH
+
+The full path names to files, including programs.
+
PROG
+
+The base names of programs.
+
MEMBER
+
+Members of aggregates.
+
SYS
+
+Operating system features.
+
TYPE
+
+C builtin or declared types.
+
VAR
+
+C variables in libraries.
+
+
+
+After the category comes the name of the particular feature being
+tested. Any further words in the macro name indicate particular aspects
+of the feature. For example, AC_FUNC_UTIME_NULL checks the
+behavior of the utime function when called with a NULL
+pointer.
+
+
+
+An internal macro should have a name that starts with an underscore;
+Autoconf internals should therefore start with `_AC_'.
+Additionally, a macro that is an internal subroutine of another macro
+should have a name that starts with an underscore and the name of that
+other macro, followed by one or more words saying what the internal
+macro does. For example, AC_PATH_X has internal macros
+_AC_PATH_X_XMKMF and _AC_PATH_X_DIRECT.
+
+
+
+
+
+When macros statically diagnose abnormal situations, benign or fatal,
+they should report them using these macros. For dynamic issues, i.e.,
+when @command{configure} is run, see section Printing Messages.
+
+
+
+
+
Macro:AC_DIAGNOSE(category, message)
+
+
+Report message as a warning (or as an error if requested by the
+user) if it falls into the category. You are encouraged to use
+standard categories, which currently include:
+
+
+
+
+
`all'
+
+messages that don't fall into one of the following category. Use of an
+empty category is equivalent.
+
+
+Some Autoconf macros depend on other macros having been called first in
+order to work correctly. Autoconf provides a way to ensure that certain
+macros are called if needed and a way to warn the user if macros are
+called in an order that might cause incorrect operation.
+
+
+
+
+
+A macro that you write might need to use values that have previously
+been computed by other macros. For example, AC_DECL_YYTEXT
+examines the output of flex or lex, so it depends on
+AC_PROG_LEX having been called first to set the shell variable
+LEX.
+
+
+
+Rather than forcing the user of the macros to keep track of the
+dependencies between them, you can use the AC_REQUIRE macro to do
+it automatically. AC_REQUIRE can ensure that a macro is only
+called if it is needed, and only called once.
+
+
+
+
+
Macro:AC_REQUIRE(macro-name)
+
+
+If the M4 macro macro-name has not already been called, call it
+(without any arguments). Make sure to quote macro-name with
+square brackets. macro-name must have been defined using
+AC_DEFUN or else contain a call to AC_PROVIDE to indicate
+that it has been called.
+
+
+
+AC_REQUIRE must be used inside an AC_DEFUN'd macro; it
+must not be called from the top level.
+
+
+
+
+AC_REQUIRE is often misunderstood. It really implements
+dependencies between macros in the sense that if one macro depends upon
+another, the latter will be expanded before the body of the
+former. In particular, `AC_REQUIRE(FOO)' is not replaced with the
+body of FOO. For instance, this definition of macros:
+
+
+
+
+This behavior was chosen on purpose: (i) it prevents messages in
+required macros from interrupting the messages in the requiring macros;
+(ii) it avoids bad surprises when shell conditionals are used, as in:
+
+
+
+
+if ...; then
+ AC_REQUIRE([SOME_CHECK])
+fi
+...
+SOME_CHECK
+
+
+
+You are encouraged to put all AC_REQUIREs at the beginning of a
+macro. You can use dnl to avoid the empty lines they leave.
+
+
+
+
+
+Some macros should be run before another macro if both are called, but
+neither requires that the other be called. For example, a macro
+that changes the behavior of the C compiler should be called before any
+macros that run the C compiler. Many of these dependencies are noted in
+the documentation.
+
+
+
+Autoconf provides the AC_BEFORE macro to warn users when macros
+with this kind of dependency appear out of order in a
+`configure.ac' file. The warning occurs when creating
+@command{configure} from `configure.ac', not when running
+@command{configure}.
+
+
+
+For example, AC_PROG_CPP checks whether the C compiler
+can run the C preprocessor when given the @option{-E} option. It should
+therefore be called after any macros that change which C compiler is
+being used, such as AC_PROG_CC. So AC_PROG_CC contains:
+
+
+
+
+AC_BEFORE([$0], [AC_PROG_CPP])dnl
+
+
+
+This warns the user if a call to AC_PROG_CPP has already occurred
+when AC_PROG_CC is called.
+
+
+
+
+Make m4 print a warning message to the standard error output if
+called-macro-name has already been called. this-macro-name
+should be the name of the macro that is calling AC_BEFORE. The
+macro called-macro-name must have been defined using
+AC_DEFUN or else contain a call to AC_PROVIDE to indicate
+that it has been called.
+
+Configuration and portability technology has evolved over the years.
+Often better ways of solving a particular problem are developed, or
+ad-hoc approaches are systematized. This process has occurred in many
+parts of Autoconf. One result is that some of the macros are now
+considered obsolete; they still work, but are no longer considered
+the best thing to do, hence they should be replaced with more modern
+macros. Ideally, @command{autoupdate} should substitute the old macro calls
+with their modern implementation.
+
+
+
+Autoconf provides a simple means to obsolete a macro.
+
+
+
+
+
+Define old-macro as implementation. The only difference
+with AC_DEFUN is that the user will be warned that
+old-macro is now obsolete.
+
+
+
+If she then uses @command{autoupdate}, the call to old-macro will be
+replaced by the modern implementation. The additional
+message is then printed.
+
+The Autoconf macros follow a strict coding style. You are encouraged to
+follow this style, especially if you intend to distribute your macro,
+either by contributing it to Autoconf itself, or via other means.
+
+
+
+The first requirement is to pay great attention to the quotation, for
+more details, see section The Autoconf Language, and section M4 Quotation.
+
+
+
+Do not try to invent new interfaces. It is likely that there is a macro
+in Autoconf that resembles the macro you are defining: try to stick to
+this existing interface (order of arguments, default values, etc.). We
+are conscious that some of these interfaces are not perfect;
+nevertheless, when harmless, homogeneity should be preferred over
+creativity.
+
+
+
+Be careful about clashes both between M4 symbols and between shell
+variables.
+
+
+
+If you stick to the suggested M4 naming scheme (see section Macro Names),
+you are unlikely to generate conflicts. Nevertheless, when you need to
+set a special value, avoid using a regular macro name; rather,
+use an "impossible" name. For instance, up to version 2.13, the macro
+AC_SUBST used to remember what symbols were already defined
+by setting AC_SUBST_symbol, which is a regular macro name.
+But since there is a macro named AC_SUBST_FILE, it was just
+impossible to `AC_SUBST(FILE)'! In this case,
+AC_SUBST(symbol) or _AC_SUBST(symbol) should
+have been used (yes, with the parentheses)...or better yet, high-level
+macros such as AC_EXPAND_ONCE.
+
+
+
+No Autoconf macro should ever enter the user-variable name space; i.e.,
+except for the variables that are the actual result of running the
+macro, all shell variables should start with ac_. In
+addition, small macros or any macro that is likely to be embedded in
+other macros should be careful not to use obvious names.
+
+
+
+
+Do not use dnl to introduce comments: most of the comments you
+are likely to write are either header comments which are not output
+anyway, or comments that should make their way into `configure'.
+There are exceptional cases where you do want to comment special M4
+constructs, in which case dnl is right, but keep in mind that it
+is unlikely.
+
+
+
+M4 ignores the leading spaces before each argument, use this feature to
+indent in such a way that arguments are (more or less) aligned with the
+opening parenthesis of the macro being called. For instance, instead of
+
+
+
+
+When using AC_TRY_RUN or any macro that cannot work when
+cross-compiling, provide a pessimistic value (typically `no').
+
+
+
+Feel free to use various tricks to prevent auxiliary tools, such as
+syntax-highlighting editors, from behaving improperly. For instance,
+instead of:
+
+
+
+
+m4_bpatsubst([$1], [$"])
+
+
+
+use
+
+
+
+
+m4_bpatsubst([$1], [$""])
+
+
+
+so that Emacsen do not open a endless "string" at the first quote.
+For the same reasons, avoid:
+
+
+
+
+test $[#] != 0
+
+
+
+and use:
+
+
+
+
+test $[@%:@] != 0
+
+
+
+Otherwise, the closing bracket would be hidden inside a `#'-comment,
+breaking the bracket-matching highlighting from Emacsen. Note the
+preferred style to escape from M4: `$[1]', `$[@]', etc. Do
+not escape when it is unneeded. Common examples of useless quotation
+are `[$]$1' (write `$$1'), `[$]var' (use `$var'),
+etc. If you add portability issues to the picture, you'll prefer
+`${1+"$[@]"}' to `"[$]@"', and you'll prefer do something
+better than hacking Autoconf :-).
+
+
+
+When using @command{sed}, don't use @option{-e} except for indenting
+purpose. With the s command, the preferred separator is `/'
+unless `/' itself is used in the command, in which case you should
+use `,'.
+
+
+
+See section Macro Definitions, for details on how to define a macro. If a
+macro doesn't use AC_REQUIRE and it is expected to never be the
+object of an AC_REQUIRE directive, then use define. In
+case of doubt, use AC_DEFUN. All the AC_REQUIRE
+statements should be at the beginning of the macro, dnl'ed.
+
+
+
+You should not rely on the number of arguments: instead of checking
+whether an argument is missing, test that it is not empty. It provides
+both a simpler and a more predictable interface to the user, and saves
+room for further arguments.
+
+
+
+Unless the macro is short, try to leave the closing `])' at the
+beginning of a line, followed by a comment that repeats the name of the
+macro being defined. This introduces an additional newline in
+@command{configure}; normally, that is not a problem, but if you want to
+remove it you can use `[]dnl' on the last line. You can similarly
+use `[]dnl' after a macro call to remove its newline. `[]dnl'
+is recommended instead of `dnl' to ensure that M4 does not
+interpret the `dnl' as being attached to the preceding text or
+macro output. For example, instead of:
+
+
+
+
+If the macro is long, try to split it into logical chunks. Typically,
+macros that check for a bug in a function and prepare its
+AC_LIBOBJ replacement should have an auxiliary macro to perform
+this setup. Do not hesitate to introduce auxiliary macros to factor
+your code.
+
+
+
+In order to highlight the recommended coding style, here is a macro
+written the old way:
+
+
+
+
+When writing your own checks, there are some shell-script programming
+techniques you should avoid in order to make your code portable. The
+Bourne shell and upward-compatible shells like the Korn shell and Bash
+have evolved over the years, but to prevent trouble, do not take
+advantage of features that were added after UNIX version 7, circa
+1977. You should not use shell functions, aliases, negated character
+classes, or other features that are not found in all Bourne-compatible
+shells; restrict yourself to the lowest common denominator. Even
+unset is not supported by all shells! Also, include a space
+after the exclamation point in interpreter specifications, like this:
+
+
+
+
+#! /usr/bin/perl
+
+
+
+If you omit the space before the path, then 4.2BSD based systems
+(such as Sequent DYNIX) will ignore the line, because they interpret
+`#! /' as a 4-byte magic number. Some old systems have quite
+small limits on the length of the `#!' line too, for instance 32
+bytes (not including the newline) on SunOS 4.
+
+
+
+The set of external programs you should run in a @command{configure} script
+is fairly small. See section `Utilities in Makefiles' in GNU Coding Standards, for the list. This
+restriction allows users to start out with a fairly small set of
+programs and build the rest, avoiding too many interdependencies between
+packages.
+
+
+
+Some of these external utilities have a portable subset of features; see
+section Limitations of Usual Tools.
+
+
+
+
+
+There are several families of shells, most prominently the Bourne
+family and the C shell family which are deeply incompatible. If you
+want to write portable shell scripts, avoid members of the C shell
+family.
+
+
+
+Below we describe some of the members of the Bourne shell family.
+
+
+
+
+
Ash
+
+
+@command{ash} is often used on GNU/Linux and BSD systems as a
+light-weight Bourne-compatible shell. Ash 0.2 has some bugs that are
+fixed in the 0.3.x series, but portable shell scripts should workaround
+them, since version 0.2 is still shipped with many GNU/Linux
+distributions.
+
+To be compatible with Ash 0.2:
+
+
+
+
+
+don't use `$?' after expanding empty or unset variables:
+
+
+
+foo=
+false
+$foo
+echo "Don't use it: $?"
+
+
+
+
+don't use command substitution within variable expansion:
+
+
+
+cat ${FOO=`bar`}
+
+
+
+
+beware that single builtin substitutions are not performed by a sub
+shell, hence their effect applies to the current shell! See section Shell Substitutions, item "Command Substitution".
+
+
+
Bash
+
+
+To detect whether you are running @command{bash}, test if
+BASH_VERSION is set. To disable its extensions and require
+POSIX compatibility, run `set -o posix'. See section `Bash POSIX Mode' in The GNU Bash Reference Manual, for
+details.
+
+
Bash 2.05 and later
+
+
+Versions 2.05 and later of @command{bash} use a different format for the
+output of the @command{set} builtin, designed to make evaluating this
+output easier. However, this output is not compatible with earlier
+versions of @command{bash} (or with many other shells, probably). So if
+you use @command{bash} 2.05 or higher to execute @command{configure},
+you'll need to use @command{bash} 2.05 for all other build tasks as well.
+
+
@command{/usr/xpg4/bin/sh on Solaris}
+
+
+The POSIX-compliant Bourne shell on a Solaris system is
+@command{/usr/xpg4/bin/sh} and is part of an extra optional package.
+There is no extra charge for this package, but it is also not part of a
+minimal OS install and therefore some folks may not have it.
+
+
Zsh
+
+
+To detect whether you are running @command{zsh}, test if
+ZSH_VERSION is set. By default @command{zsh} is not
+compatible with the Bourne shell: you have to run `emulate sh' and
+set NULLCMD to `:'. See section `Compatibility' in The Z Shell Manual, for details.
+
+Zsh 3.0.8 is the native @command{/bin/sh} on Mac OS X 10.0.3.
+
+
+
+The following discussion between Russ Allbery and Robert Lipe is worth
+reading:
+
+
+
+Russ Allbery:
+
+
+
+
+
+The GNU assumption that @command{/bin/sh} is the one and only shell
+leads to a permanent deadlock. Vendors don't want to break user's
+existant shell scripts, and there are some corner cases in the Bourne
+shell that are not completely compatible with a POSIX shell. Thus,
+vendors who have taken this route will never (OK..."never say
+never") replace the Bourne shell (as @command{/bin/sh}) with a
+POSIX shell.
+
+
+
+Robert Lipe:
+
+
+
+
+
+This is exactly the problem. While most (at least most System V's) do
+have a Bourne shell that accepts shell functions most vendor
+@command{/bin/sh} programs are not the POSIX shell.
+
+
+
+So while most modern systems do have a shell _somewhere_ that meets the
+POSIX standard, the challenge is to find it.
+
+Don't rely on `\' being preserved just because it has no special
+meaning together with the next symbol. in the native @command{/bin/sh}
+on OpenBSD 2.7 `\"' expands to `"' in here-documents with
+unquoted delimiter. As a general rule, if `\\' expands to `\'
+use `\\' to get `\'.
+
+
+
+With OpenBSD 2.7's @command{/bin/sh}
+
+
+
+
+$ cat <<EOF
+> \" \\
+> EOF
+" \
+
+
+
+and with Bash:
+
+
+
+
+bash-2.04$ cat <<EOF
+> \" \\
+> EOF
+\" \
+
+
+
+Many older shells (including the Bourne shell) implement here-documents
+inefficiently. Users can generally speed things up by using a faster
+shell, e.g., by using the command `bash ./configure' rather than
+plain `./configure'.
+
+
+
+Some shells can be extremely inefficient when there are a lot of
+here-documents inside a single statement. For instance if your
+`configure.ac' includes something like:
+
+
+
+
+if <cross_compiling>; then
+ assume this and that
+else
+ check this
+ check that
+ check something else
+ ...
+ on and on forever
+ ...
+fi
+
+
+
+A shell parses the whole if/fi construct, creating
+temporary files for each here document in it. Some shells create links
+for such here-documents on every fork, so that the clean-up code
+they had installed correctly removes them. It is creating the links
+that the shell can take forever.
+
+
+
+Moving the tests out of the if/fi, or creating multiple
+if/fi constructs, would improve the performance
+significantly. Anyway, this kind of construct is not exactly the
+typical use of Autoconf. In fact, it's even not recommended, because M4
+macros can't look into shell conditionals, so we may fail to expand a
+macro when it was expanded before in a conditional path, and the
+condition turned out to be false at run-time, and we end up not
+executing the macro at all.
+
+
+
+
+
+In each case the expected result is of course `fullness' containing
+`matter' and `void' being empty.
+
+
+
+Don't try to redirect the standard error of a command substitution: it
+must be done inside the command substitution: when running
+`: `cd /zorglub` 2>/dev/null' expect the error message to
+escape, while `: `cd /zorglub 2>/dev/null`' works properly.
+
+
+
+It is worth noting that Zsh (but not Ash nor Bash) makes it possible
+in assignments though: `foo=`cd /zorglub` 2>/dev/null'.
+
+
+
+Most shells, if not all (including Bash, Zsh, Ash), output traces on
+stderr, even for sub-shells. This might result in undesired content
+if you meant to capture the standard-error output of the inner command:
+
+
+
+
+You'll appreciate the various levels of detail...
+
+
+
+One workaround is to grep out uninteresting lines, hoping not to remove
+good ones...
+
+
+
+Don't try to move/delete open files, such as in `exec >foo; mv foo
+bar', see See section Limitations of Shell Builtins, @command{mv} for more details.
+
+
+
+
+
+While @command{autoconf} and friends will usually be run on some Unix
+variety, it can and will be used on other systems, most notably DOS
+variants. This impacts several assumptions regarding file and
+path names.
+
+
+
+will fail to properly detect absolute paths on those systems, because
+they can use a drivespec, and will usually use a backslash as directory
+separator. The canonical way to check for absolute paths is:
+
+
+
+
+Make sure you quote the brackets if appropriate and keep the backslash as
+first character (see section Limitations of Shell Builtins).
+
+
+
+Also, because the colon is used as part of a drivespec, these systems don't
+use it as path separator. When creating or accessing paths, use the
+PATH_SEPARATOR output variable instead. @command{configure} sets this
+to the appropriate value (`:' or `;') when it starts up.
+
+
+
+File names need extra care as well. While DOS-based environments
+that are Unixy enough to run @command{autoconf} (such as DJGPP) will
+usually be able to handle long file names properly, there are still
+limitations that can seriously break packages. Several of these issues
+can be easily detected by the
+@href{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk}
+package.
+
+
+
+A short overview follows; problems are marked with SFN/LFN to
+indicate where they apply: SFN means the issues are only relevant to
+plain DOS, not to DOS boxes under Windows, while LFN
+identifies problems that exist even under Windows.
+
+
+
+
+
No multiple dots (SFN)
+
+DOS cannot handle multiple dots in filenames. This is an especially
+important thing to remember when building a portable configure script,
+as @command{autoconf} uses a .in suffix for template files.
+
+This is perfectly OK on Unices:
+
+
+
+
+but it causes problems on DOS, as it requires `config.h.in',
+`source.c.in' and `foo.bar.in'. To make your package more portable
+to DOS-based environments, you should use this instead:
+
+
+
+DOS cannot handle filenames that start with a dot. This is usually
+not a very important issue for @command{autoconf}.
+
+
Case insensitivity (LFN)
+
+DOS is case insensitive, so you cannot, for example, have both a
+file called `INSTALL' and a directory called `install'. This
+also affects @command{make}; if there's a file called `INSTALL' in
+the directory, @command{make install} will do nothing (unless the
+`install' target is marked as PHONY).
+
+
The 8+3 limit (SFN)
+
+Because the DOS file system only stores the first 8 characters of
+the filename and the first 3 of the extension, those must be unique.
+That means that `foobar-part1.c', `foobar-part2.c' and
+`foobar-prettybird.c' all resolve to the same filename
+(`FOOBAR-P.C'). The same goes for `foo.bar' and
+`foo.bartender'.
+
+Note: This is not usually a problem under Windows, as it uses numeric
+tails in the short version of filenames to make them unique. However, a
+registry setting can turn this behaviour off. While this makes it
+possible to share file trees containing long file names between SFN
+and LFN environments, it also means the above problem applies there
+as well.
+
+
Invalid characters
+
+Some characters are invalid in DOS filenames, and should therefore
+be avoided. In a LFN environment, these are `/', `\',
+`?', `*', `:', `<', `>', `|' and `"'.
+In a SFN environment, other characters are also invalid. These
+include `+', `,', `[' and `]'.
+
+Contrary to a persistent urban legend, the Bourne shell does not
+systematically split variables and backquoted expressions, in particular
+on the right-hand side of assignments and in the argument of case.
+For instance, the following code:
+
+
+
+
+case "$given_srcdir" in
+.) top_srcdir="`echo "$dots" | sed 's,/$,,'`"
+*) top_srcdir="$dots$given_srcdir" ;;
+esac
+
+
+
+is more readable when written as:
+
+
+
+
+case $given_srcdir in
+.) top_srcdir=`echo "$dots" | sed 's,/$,,'`
+*) top_srcdir=$dots$given_srcdir ;;
+esac
+
+
+
+and in fact it is even more portable: in the first case of the
+first attempt, the computation of top_srcdir is not portable,
+since not all shells properly understand "`..."..."...`".
+Worse yet, not all shells understand "`...\"...\"...`"
+the same way. There is just no portable way to use double-quoted
+strings inside double-quoted backquoted expressions (pfew!).
+
+
+
+
+
$@
+
+
+One of the most famous shell-portability issues is related to
+`"$@"': when there are no positional arguments, it is supposed to
+be equivalent to nothing. But some shells, for instance under Digital
+Unix 4.0 and 5.0, will then replace it with an empty argument. To be
+portable, use `${1+"$@"}'.
+
+
${var:-value}
+
+
+Old BSD shells, including the Ultrix sh, don't accept the
+colon for any shell substitution, and complain and die.
+
+
${var=literal}
+
+
+Be sure to quote:
+
+
+
+: ${var='Some words'}
+
+
+otherwise some shells, such as on Digital Unix V 5.0, will die because
+of a "bad substitution".
+
+Solaris' @command{/bin/sh} has a frightening bug in its interpretation
+of this. Imagine you need set a variable to a string containing
+`}'. This `}' character confuses Solaris' @command{/bin/sh}
+when the affected variable was already set. This bug can be exercised
+by running:
+
+
+
+$ unset foo
+$ foo=${foo='}'}
+$ echo $foo
+}
+$ foo=${foo='}' # no error; this hints to what the bug is
+$ echo $foo
+}
+$ foo=${foo='}'}
+$ echo $foo
+}}
+ ^ ugh!
+
+
+It seems that `}' is interpreted as matching `${', even
+though it is enclosed in single quotes. The problem doesn't happen
+using double quotes.
+
+
${var=expanded-value}
+
+
+On Ultrix,
+running
+
+
+
+default="yu,yaa"
+: ${var="$default"}
+
+
+will set var to `M-yM-uM-,M-yM-aM-a', i.e., the 8th bit of
+each char will be set. You won't observe the phenomenon using a simple
+`echo $var' since apparently the shell resets the 8th bit when it
+expands $var. Here are two means to make this shell confess its sins:
+
+
+
+$ cat -v <<EOF
+$var
+EOF
+
+
+and
+
+
+
+$ set | grep '^var=' | cat -v
+
+
+One classic incarnation of this bug is:
+
+
+
+default="a b c"
+: ${list="$default"}
+for c in $list; do
+ echo $c
+done
+
+
+You'll get `a b c' on a single line. Why? Because there are no
+spaces in `$list': there are `M- ', i.e., spaces with the 8th
+bit set, hence no IFS splitting is performed!!!
+
+One piece of good news is that Ultrix works fine with `:
+${list=$default}'; i.e., if you don't quote. The bad news is
+then that QNX 4.25 then sets list to the last item of
+default!
+
+The portable way out consists in using a double assignment, to switch
+the 8th bit twice on Ultrix:
+
+
+
+list=${list="$default"}
+
+
+...but beware of the `}' bug from Solaris (see above). For safety,
+use:
+
+
+
+test "${var+set}" = set || var={value}
+
+
+
`commands`
+
+
+
+While in general it makes no sense, do not substitute a single builtin
+with side effects as Ash 0.2, trying to optimize, does not fork a
+sub-shell to perform the command.
+
+For instance, if you wanted to check that @command{cd} is silent, do not
+use `test -z "`cd /`"' because the following can happen:
+
+
+
+$ pwd
+/tmp
+$ test -n "`cd /`" && pwd
+/
+
+
+The result of `foo=`exit 1`' is left as an exercise to the reader.
+
+
$(commands)
+
+
+This construct is meant to replace ``commands`'; they can be
+nested while this is impossible to do portably with back quotes.
+Unfortunately it is not yet widely supported. Most notably, even recent
+releases of Solaris don't support it:
+
+
+
+When setting several variables in a row, be aware that the order of the
+evaluation is undefined. For instance `foo=1 foo=2; echo $foo'
+gives `1' with sh on Solaris, but `2' with Bash. You must use
+`;' to enforce the order: `foo=1; foo=2; echo $foo'.
+
+
+
+Don't rely on the exit status of an assignment: Ash 0.2 does not change
+the status and propagates that of the last statement:
+
+
+
+
+
+If the default value is a literal and does not contain any closing
+brace, use:
+
+
+
+: ${var='my literal'}
+
+
+
+
+If the default value contains no closing brace, has to be expanded, and
+the variable being initialized will never be IFS-split (i.e., it's not a
+list), then use:
+
+
+
+: ${var="$default"}
+
+
+
+
+If the default value contains no closing brace, has to be expanded, and
+the variable being initialized will be IFS-split (i.e., it's a list),
+then use:
+
+
+
+var=${var="$default"}
+
+
+
+
+If the default value contains a closing brace, then use:
+
+
+
+test "${var+set}" = set || var='${indirection}'
+
+
+
+
+
+In most cases `var=${var="$default"}' is fine, but in case of
+doubt, just use the latter. See section Shell Substitutions, items
+`${var:-value}' and `${var=value}'
+for the rationale.
+
+
+
+
+
+Some shell variables should not be used, since they can have a deep
+influence on the behavior of the shell. In order to recover a sane
+behavior from the shell, some variables should be unset, but
+@command{unset} is not portable (see section Limitations of Shell Builtins) and a
+fallback value is needed. We list these values below.
+
+
+
+
+
CDPATH
+
+
+When this variable is set cd is verbose, so idioms such as
+`abs=`cd $rel && pwd`' break because abs receives the path
+twice.
+
+Setting CDPATH to the empty value is not enough for most shells.
+A simple path separator is enough except for zsh, which prefers a
+leading dot:
+
+
+
+zsh-3.1.6$ mkdir foo && (CDPATH=: cd foo)
+/tmp/foo
+zsh-3.1.6$ (CDPATH=:. cd foo)
+/tmp/foo
+zsh-3.1.6$ (CDPATH=.: cd foo)
+zsh-3.1.6$
+
+
+(of course we could just @command{unset} CDPATH, since it also
+behaves properly if set to the empty string).
+
+Life wouldn't be so much fun if @command{bash} and @command{zsh} had the
+same behavior:
+
+
+
+bash-2.02$ mkdir foo && (CDPATH=: cd foo)
+bash-2.02$ (CDPATH=:. cd foo)
+bash-2.02$ (CDPATH=.: cd foo)
+/tmp/foo
+
+
+Of course, even better style would be to use PATH_SEPARATOR instead
+of a `:'.
+Therefore, a portable solution to neutralize CDPATH is
+
+
+
+CDPATH=${ZSH_VERSION+.}$PATH_SEPARATOR
+
+
+Note that since @command{zsh} supports @command{unset}, you may unset
+CDPATH using PATH_SEPARATOR as a fallback, see
+section Limitations of Shell Builtins.
+
+
IFS
+
+
+Don't set the first character of IFS to backslash. Indeed,
+Bourne shells use the first character (backslash) when joining the
+components in `"$@"' and some shells then re-interpret (!) the
+backslash escapes, so you can end up with backspace and other strange
+characters.
+
+
LANG
+
+
LC_ALL
+
+
LC_COLLATE
+
+
LC_CTYPE
+
+
LC_MESSAGES
+
+
LC_NUMERIC
+
+
LC_TIME
+
+
+
+
+
+
+
+
+
+Autoconf-generated scripts normally set all these variables to
+`C' because so much configuration code assumes the C locale and
+POSIX requires that @env{LC_ALL} be set to `C' if the C
+locale is desired. However, some older, nonstandard systems (notably
+SCO) break if @env{LC_ALL} is set to `C', so when running on
+these systems Autoconf-generated scripts first try to unset the
+variables instead.
+
+
LANGUAGE
+
+
+
+@env{LANGUAGE} is not specified by POSIX, but it is a GNU
+extension that overrides @env{LC_ALL} in some cases, so
+Autoconf-generated scripts set it too.
+
+
LINENO
+
+
+Most modern shells provide the current line number in LINENO.
+Its value is the line number of the beginning of the current command.
+Autoconf attempts to execute @command{configure} with a modern shell.
+If no such shell is available, it attempts to implement LINENO
+with a Sed prepass that replaces the each instance of the string
+$LINENO (not followed by an alphanumeric character) with the
+line's number.
+
+You should not rely on LINENO within @command{eval}, as the
+behavior differs in practice. Also, the possibility of the Sed
+prepass means that you should not rely on $LINENO when quoted,
+when in here-documents, or when in long commands that cross line
+boundaries. Subshells should be OK, though. In the following
+example, lines 1, 6, and 9 are portable, but the other instances of
+LINENO are not:
+
+
+
+
+When executing the command `>foo', @command{zsh} executes
+`$NULLCMD >foo'. The Bourne shell considers NULLCMD is
+`:', while @command{zsh}, even in Bourne shell compatibility mode,
+sets NULLCMD to `cat'. If you forgot to set NULLCMD,
+your script might be suspended waiting for data on its standard input.
+
+
status
+
+
+This variable is an alias to `$?' for zsh (at least 3.1.6),
+hence read-only. Do not use it.
+
+
PATH_SEPARATOR
+
+
+If it is not set, @command{configure} will detect the appropriate path
+separator for the build system and set the PATH_SEPARATOR output
+variable accordingly.
+
+On DJGPP systems, the PATH_SEPARATOR environment variable can be
+set to either `:' or `;' to control the path separator
+@command{bash} uses to set up certain environment variables (such as
+PATH). Since this only works inside @command{bash}, you want
+@command{configure} to detect the regular DOS path separator
+(`;'), so it can be safely substituted in files that may not support
+`;' as path separator. So it is recommended to either unset this
+variable or set it to `;'.
+
+
RANDOM
+
+
+Many shells provide RANDOM, a variable that returns a different
+integer when used. Most of the time, its value does not change when it
+is not used, but on IRIX 6.5 the value changes all the time. This
+can be observed by using @command{set}.
+
+No, no, we are serious: some shells do have limitations! :)
+
+
+
+You should always keep in mind that any built-in or command may support
+options, and therefore have a very different behavior with arguments
+starting with a dash. For instance, the innocent `echo "$word"'
+can give unexpected results when word starts with a dash. It is
+often possible to avoid this problem using `echo "x$word"', taking
+the `x' into account later in the pipe.
+
+
+
+
+
@command{.}
+
+
+Use @command{.} only with regular files (use `test -f'). Bash
+2.03, for instance, chokes on `. /dev/null'. Also, remember that
+@command{.} uses @env{PATH} if its argument contains no slashes, so if
+you want to use @command{.} on a file `foo' in the current
+directory, you must use `. ./foo'.
+
+
@command{!}
+
+
+You can't use @command{!}, you'll have to rewrite your code.
+
+
@command{break}
+
+
+The use of `break 2', etcetera, is safe.
+
+
@command{case}
+
+
+You don't need to quote the argument; no splitting is performed.
+
+You don't need the final `;;', but you should use it.
+
+Because of a bug in its fnmatch, @command{bash} fails to properly
+handle backslashes in character classes:
+
+
+
+bash-2.02$ case /tmp in [/\\]*) echo OK;; esac
+bash-2.02$
+
+
+This is extremely unfortunate, since you are likely to use this code to
+handle UNIX or MS-DOS absolute paths. To work around this
+bug, always put the backslash first:
+
+
+
+bash-2.02$ case '\TMP' in [\\/]*) echo OK;; esac
+OK
+bash-2.02$ case /tmp in [\\/]*) echo OK;; esac
+OK
+
+
+Some shells, such as Ash 0.3.8, are confused by empty
+case/esac:
+
+
+
+ash-0.3.8 $ case foo in esac;
+error-->Syntax error: ";" unexpected (expecting ")")
+
+
+Many shells still do not support parenthesized cases, which is a pity
+for those of us using tools that rely on balanced parentheses. For
+instance, Solaris 2.8's Bourne shell:
+
+
+
+$ case foo in (foo) echo foo;; esac
+error-->syntax error: `(' unexpected
+
+
+
@command{echo}
+
+
+The simple echo is probably the most surprising source of
+portability troubles. It is not possible to use `echo' portably
+unless both options and escape sequences are omitted. New applications
+which are not aiming at portability should use `printf' instead of
+`echo'.
+
+Don't expect any option. See section Preset Output Variables, ECHO_N
+etc. for a means to simulate @option{-c}.
+
+Do not use backslashes in the arguments, as there is no consensus on
+their handling. On `echo '\n' | wc -l', the @command{sh} of
+Digital Unix 4.0, MIPS RISC/OS 4.52, answer 2, but the Solaris'
+@command{sh}, Bash and Zsh (in @command{sh} emulation mode) report 1.
+Please note that the problem is truly @command{echo}: all the shells
+understand `'\n'' as the string composed of a backslash and an
+`n'.
+
+Because of these problems, do not pass a string containing arbitrary
+characters to @command{echo}. For example, `echo "$foo"' is safe
+if you know that foo's value cannot contain backslashes and cannot
+start with `-', but otherwise you should use a here-document like
+this:
+
+
+
+cat <<EOF
+$foo
+EOF
+
+
+
@command{exit}
+
+
+The default value of @command{exit} is supposed to be $?;
+unfortunately, some shells, such as the DJGPP port of Bash 2.04, just
+perform `exit 0'.
+
+
+
+
+Using `exit $?' restores the expected behavior.
+
+Some shell scripts, such as those generated by @command{autoconf}, use a
+trap to clean up before exiting. If the last shell command exited with
+nonzero status, the trap also exits with nonzero status so that the
+invoker can tell that an error occurred.
+
+Unfortunately, in some shells, such as Solaris 8 @command{sh}, an exit
+trap ignores the exit command's status. In these shells, a trap
+cannot determine whether it was invoked by plain exit or by
+exit 1. Instead of calling exit directly, use the
+AC_MSG_ERROR macro that has a workaround for this problem.
+
+
@command{export}
+
+
+The builtin @command{export} dubs environment variable a shell
+variable. Each update of exported variables corresponds to an update of
+the environment variables. Conversely, each environment variable
+received by the shell when it is launched should be imported as a shell
+variable marked as exported.
+
+Alas, many shells, such as Solaris 2.5, IRIX 6.3, IRIX 5.2, AIX 4.1.5
+and DU 4.0, forget to @command{export} the environment variables they
+receive. As a result, two variables are coexisting: the environment
+variable and the shell variable. The following code demonstrates this
+failure:
+
+
+
+
+when run with `FOO=foo' in the environment, these shells will print
+alternately `foo' and `bar', although it should only print
+`foo' and then a sequence of `bar's.
+
+Therefore you should @command{export} again each environment variable
+that you update.
+
+
@command{false}
+
+
+Don't expect @command{false} to exit with status 1: in the native Bourne
+shell of Solaris 8, it exits with status 255.
+
+
@command{for}
+
+
+To loop over positional arguments, use:
+
+
+
+for arg
+do
+ echo "$arg"
+done
+
+
+You may not leave the do on the same line as for,
+since some shells improperly grok:
+
+
+
+for arg; do
+ echo "$arg"
+done
+
+
+If you want to explicitly refer to the positional arguments, given the
+`$@' bug (see section Shell Substitutions), use:
+
+
+
+
+There are shells that do not reset the exit status from an @command{if}:
+
+
+
+$ if (exit 42); then true; fi; echo $?
+42
+
+
+whereas a proper shell should have printed `0'. This is especially
+bad in Makefiles since it produces false failures. This is why properly
+written Makefiles, such as Automake's, have such hairy constructs:
+
+
+
+if test -f "$file"; then
+ install "$file" "$dest"
+else
+ :
+fi
+
+
+
@command{set}
+
+
+This builtin faces the usual problem with arguments starting with a
+dash. Modern shells such as Bash or Zsh understand @option{--} to specify
+the end of the options (any argument after @option{--} is a parameters,
+even `-x' for instance), but most shells simply stop the option
+processing as soon as a non-option argument is found. Therefore, use
+`dummy' or simply `x' to end the option processing, and use
+@command{shift} to pop it out:
+
+
+
+set x $my_list; shift
+
+
+
@command{shift}
+
+
+Not only is @command{shift}ing a bad idea when there is nothing left to
+shift, but in addition it is not portable: the shell of MIPS
+RISC/OS 4.52 refuses to do it.
+
+
@command{source}
+
+
+This command is not portable, as POSIX does not require it; use
+@command{.} instead.
+
+
@command{test}
+
+
+The test program is the way to perform many file and string
+tests. It is often invoked by the alternate name `[', but using
+that name in Autoconf code is asking for trouble since it is an M4 quote
+character.
+
+If you need to make multiple checks using test, combine them with
+the shell operators `&&' and `||' instead of using the
+test operators @option{-a} and @option{-o}. On System V, the
+precedence of @option{-a} and @option{-o} is wrong relative to the unary
+operators; consequently, POSIX does not specify them, so using them
+is nonportable. If you combine `&&' and `||' in the same
+statement, keep in mind that they have equal precedence.
+
+You may use `!' with @command{test}, but not with @command{if}:
+`test ! -r foo || exit 1'.
+
+
@command{test (files)}
+
+To enable @command{configure} scripts to support cross-compilation, they
+shouldn't do anything that tests features of the build system instead of
+the host system. But occasionally you may find it necessary to check
+whether some arbitrary file exists. To do so, use `test -f' or
+`test -r'. Do not use `test -x', because 4.3BSD does not
+have it. Do not use `test -e' either, because Solaris 2.5 does not
+have it.
+
+
@command{test (strings)}
+
+Avoid `test "string"', in particular if string might
+start with a dash, since test might interpret its argument as an
+option (e.g., `string = "-n"').
+
+Contrary to a common belief, `test -n string' and `test
+-z string'are portable, nevertheless many shells (such
+as Solaris 2.5, AIX 3.2, UNICOS 10.0.0.6, Digital Unix 4 etc.) have
+bizarre precedence and may be confused if string looks like an
+operator:
+
+
+
+$ test -n =
+test: argument expected
+
+
+If there are risks, use `test "xstring" = x' or `test
+"xstring" != x' instead.
+
+It is frequent to find variations of the following idiom:
+
+
+
+
+Use case where possible since it is faster, being a shell builtin:
+
+
+
+case $ac_feature in
+ *[!-a-zA-Z0-9_]*) action;;
+esac
+
+
+Alas, negated character classes are probably not portable, although no
+shell is known to not support the POSIX.2 syntax `[!...]'
+(when in interactive mode, @command{zsh} is confused by the
+`[!...]' syntax and looks for an event in its history because of
+`!'). Many shells do not support the alternative syntax
+`[^...]' (Solaris, Digital Unix, etc.).
+
+One solution can be:
+
+
+
+
+`expr "Xfoo" : "Xbar"' is more robust than `echo
+"Xfoo" | grep "^Xbar"', because it avoids problems when
+`foo' contains backslashes.
+
+
@command{trap}
+
+
+It is safe to trap at least the signals 1, 2, 13 and 15. You can also
+trap 0, i.e., have the @command{trap} run when the script ends (either via an
+explicit @command{exit}, or the end of the script).
+
+Although POSIX is not absolutely clear on this point, it is widely
+admitted that when entering the trap `$?' should be set to the exit
+status of the last command run before the trap. The ambiguity can be
+summarized as: "when the trap is launched by an @command{exit}, what is
+the last command run: that before @command{exit}, or
+@command{exit} itself?"
+
+Bash considers @command{exit} to be the last command, while Zsh and
+Solaris 8 @command{sh} consider that when the trap is run it is
+still in the @command{exit}, hence it is the previous exit status
+that the trap receives:
+
+
+
+
+The portable solution is then simple: when you want to `exit 42',
+run `(exit 42); exit 42', the first @command{exit} being used to
+set the exit status to 42 for Zsh, and the second to trigger the trap
+and pass 42 as exit status for Bash.
+
+The shell in FreeBSD 4.0 has the following bug: `$?' is reset to 0
+by empty lines if the code is inside @command{trap}.
+
+
+
+$ trap 'false
+
+echo $?' 0
+$ exit
+0
+
+
+Fortunately, this bug only affects @command{trap}.
+
+
@command{true}
+
+
+
+Don't worry: as far as we know @command{true} is portable.
+Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
+portable shell community tends to prefer using @command{:}. This has a
+funny side effect: when asked whether @command{false} is more portable
+than @command{true} Alexandre Oliva answered:
+
+
+
+
+In a sense, yes, because if it doesn't exist, the shell will produce an
+exit status of failure, which is correct for @command{false}, but not
+for @command{true}.
+
+
+
@command{unset}
+
+
+You cannot assume the support of @command{unset}, nevertheless, because
+it is extremely useful to disable embarrassing variables such as
+CDPATH, you can test for its existence and use
+it provided you give a neutralizing value when @command{unset} is
+not supported:
+
+
+
+
+Either do not depend on such patterns (i.e., use `/^(.*foo|bar)/',
+or use a simple test to reject such AWK.
+
+
@command{cat}
+
+
+Don't rely on any option. The option @option{-v}, which displays
+non-printing characters, seems portable, though.
+
+
@command{cc}
+
+When a compilation such as `cc foo.c -o foo' fails, some compilers
+(such as CDS on Reliant UNIX) leave a `foo.o'.
+
+HP-UX @command{cc} doesn't accept `.S' files to preprocess and
+assemble. `cc -c foo.S' will appear to succeed, but in fact does
+nothing.
+
+
@command{cmp}
+
+
+@command{cmp} performs a raw data comparison of two files, while
+@command{diff} compares two text files. Therefore, if you might compare
+DOS files, even if only checking whether two files are different, use
+@command{diff} to avoid spurious differences due to differences of
+newline encoding.
+
+
@command{cp}
+
+
+SunOS @command{cp} does not support @option{-f}, although its
+@command{mv} does. It's possible to deduce why @command{mv} and
+@command{cp} are different with respect to @option{-f}. @command{mv}
+prompts by default before overwriting a read-only file. @command{cp}
+does not. Therefore, @command{mv} requires a @option{-f} option, but
+@command{cp} does not. @command{mv} and @command{cp} behave differently
+with respect to read-only files because the simplest form of
+@command{cp} cannot overwrite a read-only file, but the simplest form of
+@command{mv} can. This is because @command{cp} opens the target for
+write access, whereas @command{mv} simply calls link (or, in
+newer systems, rename).
+
+
@command{date}
+
+
+Some versions of @command{date} do not recognize special % directives,
+and unfortunately, instead of complaining, they just pass them through,
+and exit with success:
+
+
+
+$ uname -a
+OSF1 medusa.sis.pasteur.fr V5.1 732 alpha
+$ date "+%s"
+%s
+
+
+
@command{diff}
+
+
+Option @option{-u} is nonportable.
+
+Some implementations, such as Tru64's, fail when comparing to
+`/dev/null'. Use an empty file instead.
+
+
@command{dirname}
+
+
+Not all hosts have a working @command{dirname}, and you should instead
+use AS_DIRNAME (see section Programming in M4sh). For example:
+
+
+
+dir=`dirname "$file"` # This is not portable.
+dir=`AS_DIRNAME(["$file"])` # This is more portable.
+
+
+This handles a few subtleties in the standard way required by
+POSIX. For example, under UN*X, should `dirname //1' give
+`/'? Paul Eggert answers:
+
+
+
+
+No, under some older flavors of Unix, leading `//' is a special
+path name: it refers to a "super-root" and is used to access other
+machines' files. Leading `///', `////', etc. are equivalent
+to `/'; but leading `//' is special. I think this tradition
+started with Apollo Domain/OS, an OS that is still in use on some older
+hosts.
+
+
+
+POSIX allows but does not require the special treatment for `//'.
+It says that the behavior of dirname on path names of the form
+`//([^/]+/*)?' is implementation defined. In these cases, GNU
+@command{dirname} returns `/', but it's more portable to return
+`//' as this works even on those older flavors of Unix.
+
+
+
@command{egrep}
+
+
+The empty alternative is not portable, use `?' instead. For
+instance with Digital Unix v5.0:
+
+
+
+
+@command{egrep} also suffers the limitations of @command{grep}.
+
+
@command{expr}
+
+
+No @command{expr} keyword starts with `x', so use @samp{expr
+x"word" : 'xregex'} to keep @command{expr} from
+misinterpreting word.
+
+Don't use length, substr, match and index.
+
+
@command{expr (`|')}
+
+
+You can use `|'. Although POSIX does require that `expr
+"' return the empty string, it does not specify the result when you
+`|' together the empty string (or zero) with the empty string. For
+example:
+
+
+
+expr '' \| ''
+
+
+GNU/Linux and POSIX.2-1992 return the empty string for this
+case, but traditional Unix returns `0' (Solaris is one such
+example). In the latest POSIX draft, the specification has been
+changed to match traditional Unix's behavior (which is bizarre, but it's
+too late to fix this). Please note that the same problem does arise
+when the empty string results from a computation, as in:
+
+
+
+expr bar : foo \| foo : bar
+
+
+Avoid this portability problem by avoiding the empty string.
+
+
@command{expr (`:')}
+
+
+Don't use `\?', `\+' and `\|' in patterns, they are
+not supported on Solaris.
+
+The POSIX.2-1992 standard is ambiguous as to whether `expr a :
+b' (and `expr 'a' : '\(b\)'') output `0' or the empty string.
+In practice, it outputs the empty string on most platforms, but portable
+scripts should not assume this. For instance, the QNX 4.25 native
+@command{expr} returns `0'.
+
+You may believe that one means to get a uniform behavior would be to use
+the empty string as a default value:
+
+
+
+expr a : b \| ''
+
+
+unfortunately this behaves exactly as the original expression, see the
+`@command{expr' (`:')} entry for more information.
+
+Older @command{expr} implementations (e.g. SunOS 4 @command{expr} and
+Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
+@command{expr} to fail if the matched substring is longer than 120
+bytes. In this case, you might want to fall back on `echo|sed' if
+@command{expr} fails.
+
+Don't leave, there is some more!
+
+The QNX 4.25 @command{expr}, in addition of preferring `0' to
+the empty string, has a funny behavior in its exit status: it's always 1
+when parentheses are used!
+
+
+
+
+In practice this can be a big problem if you are ready to catch failures
+of @command{expr} programs with some other method (such as using
+@command{sed}), since you may get twice the result. For instance
+
+
+
+
+will output `a' on most hosts, but `aa' on QNX 4.25. A
+simple work around consists in testing @command{expr} and use a variable
+set to @command{expr} or to @command{false} according to the result.
+
+
@command{find}
+
+The option @option{-maxdepth} seems to be GNU specific. Tru64 v5.1,
+NetBSD 1.5 and Solaris 2.5 @command{find} commands do not understand it.
+
+The replacement of `{}' is guaranteed only if the argument is
+exactly {}, not if it's only a part of an argument. For
+instance on DU, and HP-UX 10.20 and HP-UX 11:
+
+
+
+
+while GNU @command{find} reports `./foo-./foo'.
+
+
@command{grep}
+
+
+Don't use `grep -s' to suppress output, because `grep -s' on
+System V does not suppress output, only error messages. Instead,
+redirect the standard output and standard error (in case the file
+doesn't exist) of grep to `/dev/null'. Check the exit
+status of grep to determine whether it found a match.
+
+Don't use multiple regexps with @option{-e}, as some grep will only
+honor the last pattern (eg., IRIX 6.5 and Solaris 2.5.1). Anyway,
+Stardent Vistra SVR4 grep lacks @option{-e}... Instead, use
+alternation and egrep.
+
+
@command{ln}
+
+
+
+Don't rely on @command{ln} having a @option{-f} option. Symbolic links
+are not available on old systems, use `ln' as a fall back.
+
+For versions of the DJGPP before 2.04, @command{ln} emulates soft links
+for executables by generating a stub that in turn calls the real
+program. This feature also works with nonexistent files like in the
+Unix spec. So `ln -s file link' will generate `link.exe',
+which will attempt to call `file.exe' if run. But this feature only
+works for executables, so `cp -p' is used instead for these
+systems. DJGPP versions 2.04 and later have full symlink support.
+
+
@command{mv}
+
+
+
+The only portable options are @option{-f} and @option{-i}.
+
+Moving individual files between file systems is portable (it was in V6),
+but it is not always atomic: when doing `mv new existing', there's
+a critical section where neither the old nor the new version of
+`existing' actually exists.
+
+Moving directories across mount points is not portable, use @command{cp}
+and @command{rm}.
+
+Moving/Deleting open files isn't portable. The following can't be done
+on DOS/WIN32:
+
+
+
+exec > foo
+mv foo bar
+
+
+nor can
+
+
+
+exec > foo
+rm -f foo
+
+
+
@command{sed}
+
+
+Patterns should not include the separator (unless escaped), even as part
+of a character class. In conformance with POSIX, the Cray
+@command{sed} will reject `s/[^/]*$//': use `s,[^/]*$,,'.
+
+Sed scripts should not use branch labels longer than 8 characters and
+should not contain comments.
+
+Don't include extra `;', as some @command{sed}, such as NetBSD
+1.4.2's, try to interpret the second as a command:
+
+
+
+$ echo a | sed 's/x/x/;;s/x/x/'
+sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
+
+
+Input should have reasonably long lines, since some @command{sed} have
+an input buffer limited to 4000 bytes.
+
+Alternation, `\|', is common but POSIX.2 does not require its
+support, so it should be avoided in portable scripts. Solaris 8
+@command{sed} does not support alternation; e.g. `sed '/a\|b/d''
+deletes only lines that contain the literal string `a|b'.
+
+Anchors (`^' and `$') inside groups are not portable.
+
+Nested parenthesization in patterns (e.g., `\(\(a*\)b*)\)') is
+quite portable to modern hosts, but is not supported by some older
+@command{sed} implementations like SVR3.
+
+Of course the option @option{-e} is portable, but it is not needed. No
+valid Sed program can start with a dash, so it does not help
+disambiguating. Its sole usefulness is helping enforcing indenting as
+in:
+
+
+
+sed -e instruction-1 \
+ -e instruction-2
+
+
+as opposed to
+
+
+
+sed instruction-1;instruction-2
+
+
+Contrary to yet another urban legend, you may portably use `&' in
+the replacement part of the s command to mean "what was
+matched". All descendents of Bell Lab's V7 @command{sed} (at least; we
+don't have first hand experience with older @command{sed}s) have
+supported it.
+
+
@command{sed (`t')}
+
+
+Some old systems have @command{sed} that "forget" to reset their
+`t' flag when starting a new cycle. For instance on MIPS
+RISC/OS, and on IRIX 5.3, if you run the following @command{sed}
+script (the line numbers are not actual part of the texts):
+
+
+
+s/keep me/kept/g # a
+t end # b
+s/.*/deleted/g # c
+: end # d
+
+
+on
+
+
+
+delete me # 1
+delete me # 2
+keep me # 3
+delete me # 4
+
+
+you get
+
+
+
+deleted
+delete me
+kept
+deleted
+
+
+instead of
+
+
+
+deleted
+deleted
+kept
+deleted
+
+
+Why? When processing 1, a matches, therefore sets the t flag, b jumps to
+d, and the output is produced. When processing line 2, the t flag is
+still set (this is the bug). Line a fails to match, but @command{sed}
+is not supposed to clear the t flag when a substitution fails. Line b
+sees that the flag is set, therefore it clears it, and jumps to d, hence
+you get `delete me' instead of `deleted'. When processing 3 t
+is clear, a matches, so the flag is set, hence b clears the flags and
+jumps. Finally, since the flag is clear, 4 is processed properly.
+
+There are two things one should remind about `t' in @command{sed}.
+Firstly, always remember that `t' jumps if some substitution
+succeeded, not only the immediately preceding substitution, therefore,
+always use a fake `t clear; : clear' to reset the t flag where
+indeed.
+
+Secondly, you cannot rely on @command{sed} to clear the flag at each new
+cycle.
+
+One portable implementation of the script above is:
+
+
+
+t clear
+: clear
+s/keep me/kept/g
+t end
+s/.*/deleted/g
+: end
+
+
+
@command{touch}
+
+
+On some old BSD systems, @command{touch} or any command that
+results in an empty file does not update the timestamps, so use a
+command like echo as a workaround.
+
+GNU @command{touch} 3.16r (and presumably all before that) fails to work
+on SunOS 4.1.3 when the empty file is on an NFS-mounted 4.2 volume.
+
+
+Make itself suffers a great number of limitations, only a few of which
+being listed here. First of all, remember that since commands are
+executed by the shell, all its weaknesses are inherited...
+
+
+
+
+
$<
+
+POSIX says that the `$<' construct in makefiles can be used
+only in inference rules and in the `.DEFAULT' rule; its meaning in
+ordinary rules is unspecified. Solaris 8's @command{make} for instance
+will replace it with the argument.
+
+
Leading underscore in macro names
+
+Some Make don't support leading underscores in macro names, such as on
+NEWS-OS 4.2R.
+
+
+
+$ cat Makefile
+_am_include = #
+_am_quote =
+all:; @echo this is test
+$ make
+Make: Must be a separator on rules line 2. Stop.
+$ cat Makefile2
+am_include = #
+am_quote =
+all:; @echo this is test
+$ make -f Makefile2
+this is test
+
+
+
VPATH
+
+
+Don't use it! For instance any assignment to VPATH causes Sun
+@command{make} to only execute the first set of double-colon rules.
+
+A few kinds of features can't be guessed automatically by running test
+programs. For example, the details of the object-file format, or
+special options that need to be passed to the compiler or linker. You
+can check for such features using ad-hoc means, such as having
+@command{configure} check the output of the uname program, or
+looking for libraries that are unique to particular systems. However,
+Autoconf provides a uniform method for handling unguessable features.
+
+
+
+
+
+Like other GNU @command{configure} scripts, Autoconf-generated
+@command{configure} scripts can make decisions based on a canonical name
+for the system type, which has the form:
+`cpu-vendor-os', where os can be
+`system' or `kernel-system'
+
+
+
+@command{configure} can usually guess the canonical name for the type of
+system it's running on. To do so it runs a script called
+@command{config.guess}, which infers the name using the uname
+command or symbols predefined by the C preprocessor.
+
+
+
+Alternately, the user can specify the system type with command line
+arguments to @command{configure}. Doing so is necessary when
+cross-compiling. In the most complex case of cross-compiling, three
+system types are involved. The options to specify them are:
+
+
+
+
+
@option{--build=build-type}
+
+the type of system on which the package is being configured and
+compiled. It defaults to the result of running @command{config.guess}.
+
+
@option{--host=host-type}
+
+
+the type of system on which the package will run. By default it is the
+same as the build machine. Specifying it enables the cross-compilation
+mode.
+
+
@option{--target=target-type}
+
+the type of system for which any compiler tools in the package will
+produce code (rarely needed). By default, it is the same as host.
+
+
+
+If you mean to override the result of @command{config.guess}, use
+@option{--build}, not @option{--host}, since the latter enables
+cross-compilation. For historical reasons, passing @option{--host} also
+changes the build type. Therefore, whenever you specify --host,
+be sure to specify --build too. This will be fixed in the
+future.
+
+
+
+
+will enter cross-compilation mode, but @command{configure} will fail if it
+can't run the code generated by the specified compiler if you configure
+as follows:
+
+
+
+
+./configure CC=m68k-coff-gcc
+
+
+
+
+@command{configure} recognizes short aliases for many system types; for
+example, `decstation' can be used instead of
+`mips-dec-ultrix4.2'. @command{configure} runs a script called
+@command{config.sub} to canonicalize system type aliases.
+
+
+
+This section deliberately omits the description of the obsolete
+interface, see section Hosts and Cross-Compilation.
+
+
+
+
+
+The following macros make the system type available to @command{configure}
+scripts.
+
+
+
+
+
+
+
+
+
+The variables `build_alias', `host_alias', and
+`target_alias' are always exactly the arguments of @option{--build},
+@option{--host}, and @option{--target}; in particular, they are left empty
+if the user did not use them, even if the corresponding
+AC_CANONICAL macro was run. Any configure script may use these
+variables anywhere. These are the variables that should be used when in
+interaction with the user.
+
+
+
+If you need to recognize some special environments based on their system
+type, run the following macros to get canonical system names. These
+variables are not set before the macro call.
+
+
+
+If you use these macros, you must distribute @command{config.guess} and
+@command{config.sub} along with your source code. See section Outputting Files, for
+information about the AC_CONFIG_AUX_DIR macro which you can use
+to control in which directory @command{configure} looks for those scripts.
+
+
+
+
+
Macro:AC_CANONICAL_BUILD
+
+
+
+
+
+
+Compute the canonical build-system type variable, build, and its
+three individual parts build_cpu, build_vendor, and
+build_os.
+
+
+
+If @option{--build} was specified, then build is the
+canonicalization of build_alias by @command{config.sub},
+otherwise it is determined by the shell script @command{config.guess}.
+
+
+
+
+
+
Macro:AC_CANONICAL_HOST
+
+
+
+
+
+
+Compute the canonical host-system type variable, host, and its
+three individual parts host_cpu, host_vendor, and
+host_os.
+
+
+
+If @option{--host} was specified, then host is the
+canonicalization of host_alias by @command{config.sub},
+otherwise it defaults to build.
+
+
+
+
+
+
Macro:AC_CANONICAL_TARGET
+
+
+
+
+
+
+Compute the canonical target-system type variable, target, and its
+three individual parts target_cpu, target_vendor, and
+target_os.
+
+
+
+If @option{--target} was specified, then target is the
+canonicalization of target_alias by @command{config.sub},
+otherwise it defaults to host.
+
+
+
+
+Note that there can be artifacts due to the backward compatibility
+code. See section Hosts and Cross-Compilation, for more.
+
+
+
+
+
+How do you use a canonical system type? Usually, you use it in one or
+more case statements in `configure.ac' to select
+system-specific C files. Then, using AC_CONFIG_LINKS, link those
+files which have names based on the system name, to generic names, such
+as `host.h' or `target.c' (see section Creating Configuration Links). The
+case statement patterns can use shell wild cards to group several
+cases together, like in this fragment:
+
+
+
+
+Note that the above example uses $target because it's taken from
+a tool which can be built on some architecture ($build), run on
+another ($host), but yet handle data for a third architecture
+($target). Such tools are usually part of a compiler suite, they
+generate code for a specific $target.
+
+
+
+However $target should be meaningless for most packages. If you
+want to base a decision on the system where your program will be run,
+make sure you use the $host variable, as in the following
+excerpt:
+
+
+
+
+You can also use the host system type to find cross-compilation tools.
+See section Generic Program and File Checks, for information about the AC_CHECK_TOOL
+macro which does that.
+
+
+
+
+
+@command{configure} scripts support several kinds of local configuration
+decisions. There are ways for users to specify where external software
+packages are, include or exclude optional features, install programs
+under modified names, and set default values for @command{configure}
+options.
+
+
+
+
+
+Some packages require, or can optionally use, other software packages
+that are already installed. The user can give @command{configure}
+command line options to specify which such external software to use.
+The options have one of these forms:
+
+
+
+
+--with-package[=arg]
+--without-package
+
+
+
+For example, @option{--with-gnu-ld} means work with the GNU linker
+instead of some other linker. @option{--with-x} means work with The X
+Window System.
+
+
+
+The user can give an argument by following the package name with
+`=' and the argument. Giving an argument of `no' is for
+packages that are used by default; it says to not use the
+package. An argument that is neither `yes' nor `no' could
+include a name or number of a version of the other package, to specify
+more precisely which other package this program is supposed to work
+with. If no argument is given, it defaults to `yes'.
+@option{--without-package} is equivalent to
+@option{--with-package=no}.
+
+
+
+@command{configure} scripts do not complain about
+@option{--with-package} options that they do not support. This
+behavior permits configuring a source tree containing multiple packages
+with a top-level @command{configure} script when the packages support
+different options, without spurious error messages about options that
+some of the packages support. An unfortunate side effect is that option
+spelling errors are not diagnosed. No better approach to this problem
+has been suggested so far.
+
+
+
+For each external software package that may be used, `configure.ac'
+should call AC_ARG_WITH to detect whether the @command{configure}
+user asked to use it. Whether each package is used or not by default,
+and which arguments are valid, is up to you.
+
+
+
+
+If the user gave @command{configure} the option @option{--with-package}
+or @option{--without-package}, run shell commands
+action-if-given. If neither option was given, run shell commands
+action-if-not-given. The name package indicates another
+software package that this program should work with. It should consist
+only of alphanumeric characters and dashes.
+
+
+
+The option's argument is available to the shell commands
+action-if-given in the shell variable withval, which is
+actually just the value of the shell variable with_package,
+with any @option{-} characters changed into `_'. You may use that
+variable instead, if you wish.
+
+
+
+The argument help-string is a description of the option that
+looks like this:
+
+
+ --with-readline support fancy command line editing
+
+
+
+help-string may be more than one line long, if more detail is
+needed. Just make sure the columns line up in `configure --help'.
+Avoid tabs in the help string. You'll need to enclose it in `['
+and `]' in order to produce the leading spaces.
+
+
+
+If a software package has optional compile-time features, the user can
+give @command{configure} command line options to specify whether to
+compile them. The options have one of these forms:
+
+
+
+
+--enable-feature[=arg]
+--disable-feature
+
+
+
+These options allow users to choose which optional features to build and
+install. @option{--enable-feature} options should never make a
+feature behave differently or cause one feature to replace another.
+They should only cause parts of the program to be built rather than left
+out.
+
+
+
+The user can give an argument by following the feature name with
+`=' and the argument. Giving an argument of `no' requests
+that the feature not be made available. A feature with an
+argument looks like @option{--enable-debug=stabs}. If no argument is
+given, it defaults to `yes'. @option{--disable-feature} is
+equivalent to @option{--enable-feature=no}.
+
+
+
+@command{configure} scripts do not complain about
+@option{--enable-feature} options that they do not support.
+This behavior permits configuring a source tree containing multiple
+packages with a top-level @command{configure} script when the packages
+support different options, without spurious error messages about options
+that some of the packages support.
+An unfortunate side effect is that option spelling errors are not diagnosed.
+No better approach to this problem has been suggested so far.
+
+
+
+For each optional feature, `configure.ac' should call
+AC_ARG_ENABLE to detect whether the @command{configure} user asked
+to include it. Whether each feature is included or not by default, and
+which arguments are valid, is up to you.
+
+
+
+
+If the user gave @command{configure} the option
+@option{--enable-feature} or @option{--disable-feature}, run
+shell commands action-if-given. If neither option was given, run
+shell commands action-if-not-given. The name feature
+indicates an optional user-level facility. It should consist only of
+alphanumeric characters and dashes.
+
+
+
+The option's argument is available to the shell commands
+action-if-given in the shell variable enableval, which is
+actually just the value of the shell variable
+enable_feature, with any @option{-} characters changed into
+`_'. You may use that variable instead, if you wish. The
+help-string argument is like that of AC_ARG_WITH
+(see section Working With External Software).
+
+
+
+Properly formatting the `help strings' which are used in
+AC_ARG_WITH (see section Working With External Software) and AC_ARG_ENABLE
+(see section Choosing Package Options) can be challenging. Specifically, you want
+your own `help strings' to line up in the appropriate columns of
+`configure --help' just like the standard Autoconf `help
+strings' do. This is the purpose of the AC_HELP_STRING macro.
+
+
+
+Expands into an help string that looks pretty when the user executes
+`configure --help'. It is typically used in AC_ARG_WITH
+(see section Working With External Software) or AC_ARG_ENABLE (see section Choosing Package Options). The following example will make this clearer.
+
+
+
+
+AC_DEFUN(TEST_MACRO,
+[AC_ARG_WITH(foo,
+ AC_HELP_STRING([--with-foo],
+ [use foo (default is NO)]),
+ ac_cv_use_foo=$withval, ac_cv_use_foo=no),
+AC_CACHE_CHECK(whether to use foo,
+ ac_cv_use_foo, ac_cv_use_foo=no)])
+
+
+
+Please note that the call to AC_HELP_STRING is unquoted.
+Then the last few lines of `configure --help' will appear like
+this:
+
+
+
+
+--enable and --with options recognized:
+ --with-foo use foo (default is NO)
+
+
+
+The AC_HELP_STRING macro is particularly helpful when the
+left-hand-side and/or right-hand-side are composed of macro
+arguments, as shown in the following example.
+
+
+
+
+AC_DEFUN(MY_ARG_WITH,
+[AC_ARG_WITH([$1],
+ AC_HELP_STRING([--with-$1], [use $1 (default is $2)]),
+ ac_cv_use_$1=$withval, ac_cv_use_$1=no),
+AC_CACHE_CHECK(whether to use $1, ac_cv_use_$1, ac_cv_use_$1=$2)])
+
+Some software packages require complex site-specific information. Some
+examples are host names to use for certain services, company names, and
+email addresses to contact. Since some configuration scripts generated
+by Metaconfig ask for such information interactively, people sometimes
+wonder how to get that information in Autoconf-generated configuration
+scripts, which aren't interactive.
+
+
+
+Such site configuration information should be put in a file that is
+edited only by users, not by programs. The location of the file
+can either be based on the prefix variable, or be a standard
+location such as the user's home directory. It could even be specified
+by an environment variable. The programs should examine that file at
+run time, rather than at compile time. Run time configuration is more
+convenient for users and makes the configuration process simpler than
+getting the information while configuring. See section `Variables for Installation Directories' in GNU Coding Standards, for more information on where to put data files.
+
+
+
+
+
+Autoconf supports changing the names of programs when installing them.
+In order to use these transformations, `configure.ac' must call the
+macro AC_ARG_PROGRAM.
+
+
+
+
+
Macro:AC_ARG_PROGRAM
+
+
+
+Place in output variable program_transform_name a sequence of
+sed commands for changing the names of installed programs.
+
+
+
+If any of the options described below are given to @command{configure},
+program names are transformed accordingly. Otherwise, if
+AC_CANONICAL_TARGET has been called and a @option{--target} value
+is given, the target type followed by a dash is used as a prefix.
+Otherwise, no program name transformation is done.
+
+These transformations are useful with programs that can be part of a
+cross-compilation development environment. For example, a
+cross-assembler running on a Sun 4 configured with
+@option{--target=i960-vxworks} is normally installed as
+`i960-vxworks-as', rather than `as', which could be confused
+with a native Sun 4 assembler.
+
+
+
+You can force a program name to begin with `g', if you don't want
+GNU programs installed on your system to shadow other programs with
+the same name. For example, if you configure GNU diff with
+@option{--program-prefix=g}, then when you run `make install' it is
+installed as `/usr/local/bin/gdiff'.
+
+
+
+As a more sophisticated example, you could use
+
+
+
+
+to prepend `g' to most of the program names in a source tree,
+excepting those like gdb that already have one and those like
+less and lesskey that aren't GNU programs. (That is
+assuming that you have a source tree containing those programs that is
+set up to use this feature.)
+
+
+
+One way to install multiple versions of some programs simultaneously is
+to append a version number to the name of one or both. For example, if
+you want to keep Autoconf version 1 around for awhile, you can configure
+Autoconf version 2 using @option{--program-suffix=2} to install the
+programs as `/usr/local/bin/autoconf2',
+`/usr/local/bin/autoheader2', etc. Nevertheless, pay attention
+that only the binaries are renamed, therefore you'd have problems with
+the library files which might overlap.
+
+
+
+
+
+Here is how to use the variable program_transform_name in a
+`Makefile.in':
+
+
+
+
+PROGRAMS = cp ls rm
+transform = @program_transform_name@
+install:
+ for p in $(PROGRAMS); do \
+ $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \
+ sed '$(transform)'`; \
+ done
+
+uninstall:
+ for p in $(PROGRAMS); do \
+ rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \
+ done
+
+
+
+It is guaranteed that program_transform_name is never empty, and
+that there are no useless separators. Therefore you may safely embed
+program_transform_name within a sed program using `;':
+
+
+
+
+Whether to do the transformations on documentation files (Texinfo or
+man) is a tricky question; there seems to be no perfect answer,
+due to the several reasons for name transforming. Documentation is not
+usually particular to a specific architecture, and Texinfo files do not
+conflict with system documentation. But they might conflict with
+earlier versions of the same files, and man pages sometimes do
+conflict with system documentation. As a compromise, it is probably
+best to do name transformations on man pages but not on Texinfo
+manuals.
+
+
+
+
+
+Autoconf-generated @command{configure} scripts allow your site to provide
+default values for some configuration values. You do this by creating
+site- and system-wide initialization files.
+
+
+
+
+If the environment variable @command{CONFIG_SITE} is set, @command{configure}
+uses its value as the name of a shell script to read. Otherwise, it
+reads the shell script `prefix/share/config.site' if it exists,
+then `prefix/etc/config.site' if it exists. Thus,
+settings in machine-specific files override those in machine-independent
+ones in case of conflict.
+
+
+
+Site files can be arbitrary shell scripts, but only certain kinds of
+code are really appropriate to be in them. Because @command{configure}
+reads any cache file after it has read any site files, a site file can
+define a default cache file to be shared between all Autoconf-generated
+@command{configure} scripts run on that system (see section Cache Files). If
+you set a default cache file in a site file, it is a good idea to also
+set the output variable CC in that site file, because the cache
+file is only valid for a particular compiler, but many systems have
+several available.
+
+
+
+You can examine or override the value set by a command line option to
+@command{configure} in a site file; options set shell variables that have
+the same names as the options, with any dashes turned into underscores.
+The exceptions are that @option{--without-} and @option{--disable-} options
+are like giving the corresponding @option{--with-} or @option{--enable-}
+option and the value `no'. Thus, @option{--cache-file=localcache}
+sets the variable cache_file to the value `localcache';
+@option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
+enable_warnings to the value `no'; @option{--prefix=/usr} sets the
+variable prefix to the value `/usr'; etc.
+
+
+
+Site files are also good places to set default values for other output
+variables, such as CFLAGS, if you need to give them non-default
+values: anything you would normally do, repetitively, on the command
+line. If you use non-default values for prefix or
+exec_prefix (wherever you locate the site file), you can set them
+in the site file if you specify it with the @command{CONFIG_SITE}
+environment variable.
+
+
+
+You can set some cache values in the site file itself. Doing this is
+useful if you are cross-compiling, so it is impossible to check features
+that require running a test program. You could "prime the cache" by
+setting those values correctly for that system in
+`prefix/etc/config.site'. To find out the names of the cache
+variables you need to set, look for shell variables with `_cv_' in
+their names in the affected @command{configure} scripts, or in the Autoconf
+M4 source code for those macros.
+
+
+
+The cache file is careful to not override any variables set in the site
+files. Similarly, you should not override command-line options in the
+site files. Your code should check that variables such as prefix
+and cache_file have their default values (as set near the top of
+@command{configure}) before changing them.
+
+
+
+Here is a sample file `/usr/share/local/gnu/share/config.site'. The
+command `configure --prefix=/usr/share/local/gnu' would read this
+file (if @command{CONFIG_SITE} is not set to a different file).
+
+
+
+
+# config.site for configure
+#
+# Change some defaults.
+test "$prefix" = NONE && prefix=/usr/share/local/gnu
+test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
+test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var
+test "$localstatedir" = '$prefix/var' && localstatedir=/var
+
+# Give Autoconf 2.x generated configure scripts a shared default
+# cache file for feature test results, architecture-specific.
+if test "$cache_file" = /dev/null; then
+ cache_file="$prefix/var/config.cache"
+ # A cache file is only valid for one C compiler.
+ CC=gcc
+fi
+
+Below are instructions on how to configure a package that uses a
+@command{configure} script, suitable for inclusion as an `INSTALL'
+file in the package. A plain-text version of `INSTALL' which you
+may use comes with Autoconf.
+
+
+
+
+
+These are generic installation instructions.
+
+
+
+The @command{configure} shell script attempts to guess correct values
+for various system-dependent variables used during compilation. It uses
+those values to create a `Makefile' in each directory of the
+package. It may also create one or more `.h' files containing
+system-dependent definitions. Finally, it creates a shell script
+`config.status' that you can run in the future to recreate the
+current configuration, and a file `config.log' containing compiler
+output (useful mainly for debugging @command{configure}).
+
+
+
+It can also use an optional file (typically called `config.cache'
+and enabled with @option{--cache-file=config.cache} or simply
+@option{-C}) that saves the results of its tests to speed up
+reconfiguring. (Caching is disabled by default to prevent problems with
+accidental use of stale cache files.)
+
+
+
+If you need to do unusual things to compile the package, please try to
+figure out how @command{configure} could check whether to do them, and
+mail diffs or instructions to the address given in the `README' so
+they can be considered for the next release. If you are using the
+cache, and at some point `config.cache' contains results you don't
+want to keep, you may remove or edit it.
+
+
+
+The file `configure.ac' (or `configure.in') is used to create
+`configure' by a program called autoconf. You only need
+`configure.ac' if you want to change it or regenerate
+`configure' using a newer version of autoconf.
+
+
+
+The simplest way to compile this package is:
+
+
+
+
+
+
+cd to the directory containing the package's source code and type
+`./configure' to configure the package for your system. If you're
+using csh on an old version of System V, you might need to type
+`sh ./configure' instead to prevent csh from trying to
+execute @command{configure} itself.
+
+Running @command{configure} takes awhile. While running, it prints some
+messages telling which features it is checking for.
+
+
+
+Type `make' to compile the package.
+
+
+
+Optionally, type `make check' to run any self-tests that come with
+the package.
+
+
+
+Type `make install' to install the programs and any data files and
+documentation.
+
+
+
+You can remove the program binaries and object files from the source
+code directory by typing `make clean'. To also remove the files
+that @command{configure} created (so you can compile the package for a
+different kind of computer), type `make distclean'. There is also
+a `make maintainer-clean' target, but that is intended mainly for
+the package's developers. If you use it, you may have to get all sorts
+of other programs in order to regenerate files that came with the
+distribution.
+
+Some systems require unusual options for compilation or linking that the
+@command{configure} script does not know about. Run @samp{./configure
+--help} for details on some of the pertinent environment variables.
+
+
+
+You can give @command{configure} initial values for variables by setting
+them in the environment. You can do that on the command line like this:
+
+
+
+
+You can compile the package for more than one kind of computer at the
+same time, by placing the object files for each architecture in their
+own directory. To do this, you must use a version of @command{make}
+that supports the VPATH variable, such as GNU @command{make}.
+@command{cd} to the directory where you want the object files and
+executables to go and run the @command{configure} script.
+@command{configure} automatically checks for the source code in the
+directory that @command{configure} is in and in `..'.
+
+
+
+If you have to use a @command{make} that does not support the
+VPATH variable, you have to compile the package for one
+architecture at a time in the source code directory. After you have
+installed the package for one architecture, use `make distclean'
+before reconfiguring for another architecture.
+
+
+
+
+
+By default, `make install' will install the package's files in
+`/usr/local/bin', `/usr/local/man', etc. You can specify an
+installation prefix other than `/usr/local' by giving
+@command{configure} the option @option{--prefix=path}.
+
+
+
+You can specify separate installation prefixes for architecture-specific
+files and architecture-independent files. If you give
+@command{configure} the option @option{--exec-prefix=path}, the
+package will use path as the prefix for installing programs and
+libraries. Documentation and other data files will still use the
+regular prefix.
+
+
+
+In addition, if you use an unusual directory layout you can give options
+like @option{--bindir=path} to specify different values for
+particular kinds of files. Run `configure --help' for a list of
+the directories you can set and what kinds of files go in them.
+
+
+
+If the package supports it, you can cause programs to be installed with
+an extra prefix or suffix on their names by giving @command{configure}
+the option @option{--program-prefix=PREFIX} or
+@option{--program-suffix=SUFFIX}.
+
+
+
+
+
+Some packages pay attention to @option{--enable-feature} options
+to @command{configure}, where feature indicates an optional part
+of the package. They may also pay attention to
+@option{--with-package} options, where package is something
+like `gnu-as' or `x' (for the X Window System). The
+`README' should mention any @option{--enable-} and @option{--with-}
+options that the package recognizes.
+
+
+
+For packages that use the X Window System, @command{configure} can
+usually find the X include and library files automatically, but if it
+doesn't, you can use the @command{configure} options
+@option{--x-includes=dir} and @option{--x-libraries=dir} to
+specify their locations.
+
+
+
+
+
+There may be some features @command{configure} cannot figure out
+automatically, but needs to determine by the type of machine the package
+will run on. Usually, assuming the package is built to be run on the
+same architectures, @command{configure} can figure that out, but
+if it prints a message saying it cannot guess the machine type, give it
+the @option{--build=type} option. type can either be a
+short name for the system type, such as `sun4', or a canonical name
+which has the form:
+
+
+
+
+cpu-company-system
+
+
+
+where system can have one of these forms:
+
+
+
+
+oskernel-os
+
+
+
+See the file `config.sub' for the possible values of each field.
+If `config.sub' isn't included in this package, then this package
+doesn't need to know the machine type.
+
+
+
+If you are building compiler tools for cross-compiling, you
+should use the @option{--target=type} option to select the type of
+system they will produce code for.
+
+
+
+If you want to use a cross compiler, that generates code for a
+platform different from the build platform, you should specify the
+host platform (i.e., that on which the generated programs will
+eventually be run) with @option{--host=type}.
+
+
+
+
+
+If you want to set default values for @command{configure} scripts to
+share, you can create a site shell script called `config.site' that
+gives default values for variables like CC, cache_file,
+and prefix. @command{configure} looks for
+`prefix/share/config.site' if it exists, then
+`prefix/etc/config.site' if it exists. Or, you can set the
+CONFIG_SITE environment variable to the location of the site
+script. A warning: not all @command{configure} scripts look for a site
+script.
+
+
+
+
+
+Variables not defined in a site shell script can be set in the
+environment passed to @command{configure}. However, some packages may
+run configure again during the build, and the customized values of these
+variables may be lost. In order to avoid this problem, you should set
+them in the @command{configure} command line, using `VAR=value'.
+For example:
+
+
+
+
+./configure CC=/usr/local2/bin/gcc
+
+
+
+will cause the specified gcc to be used as the C compiler (unless it is
+overridden in the site shell script).
+
+
+
+
+
+@command{configure} recognizes the following options to control how it
+operates.
+
+
+
+
+
@option{--help}
+
+
@option{-h}
+
+Print a summary of the options to @command{configure}, and exit.
+
+
@option{--version}
+
+
@option{-V}
+
+Print the version of Autoconf used to generate the @command{configure}
+script, and exit.
+
+
@option{--cache-file=file}
+
+
+Enable the cache: use and save the results of the tests in file,
+traditionally `config.cache'. file defaults to
+`/dev/null' to disable caching.
+
+
@option{--config-cache}
+
+
@option{-C}
+
+Alias for @option{--cache-file=config.cache}.
+
+
@option{--quiet}
+
+
@option{--silent}
+
+
@option{-q}
+
+Do not print messages saying which checks are being made. To suppress
+all normal output, redirect it to `/dev/null' (any error messages
+will still be shown).
+
+
@option{--srcdir=dir}
+
+Look for the package's source code in directory dir. Usually
+@command{configure} can determine that directory automatically.
+
+
+
+@command{configure} also accepts some other, not widely useful, options.
+Run `configure --help' for more details.
+
+
+
+
+
+The @command{configure} script creates a file named `config.status',
+which actually configures, instantiates, the template files. It
+also records the configuration options that were specified when the
+package was last configured in case reconfiguring is needed.
+
+
+
+Synopsis:
+
+
+./config.status option... [file...]
+
+
+
+It configures the files, if none are specified, all the templates
+are instantiated. The files must be specified without their
+dependencies, as in
+
+
+
+
+./config.status foobar
+
+
+
+not
+
+
+
+
+./config.status foobar:foo.in:bar.in
+
+
+
+The supported options are:
+
+
+
+
+
@option{--help}
+
+
@option{-h}
+
+Print a summary of the command line options, the list of the template
+files and exit.
+
+
@option{--version}
+
+
@option{-V}
+
+Print the version number of Autoconf and exit.
+
+
@option{--debug}
+
+
@option{-d}
+
+Don't remove the temporary files.
+
+
@option{--file=file[:template]}
+
+Require that file be instantiated as if
+`AC_CONFIG_FILES(file:template)' was used. Both
+file and template may be `-' in which case the standard
+output and/or standard input, respectively, is used. If a
+template filename is relative, it is first looked for in the build
+tree, and then in the source tree. See section Taking Configuration Actions, for
+more details.
+
+This option and the following ones provide one way for separately
+distributed packages to share the values computed by @command{configure}.
+Doing so can be useful if some of the packages need a superset of the
+features that one of them, perhaps a common library, does. These
+options allow a `config.status' file to create files other than the
+ones that its `configure.ac' specifies, so it can be used for a
+different package.
+
+
@option{--header=file[:template]}
+
+Same as @option{--file} above, but with `AC_CONFIG_HEADERS'.
+
+
@option{--recheck}
+
+Ask `config.status' to update itself and exit (no instantiation).
+This option is useful if you change @command{configure}, so that the
+results of some tests might be different from the previous run. The
+@option{--recheck} option re-runs @command{configure} with the same arguments
+you used before, plus the @option{--no-create} option, which prevents
+@command{configure} from running `config.status' and creating
+`Makefile' and other files, and the @option{--no-recursion} option,
+which prevents @command{configure} from running other @command{configure}
+scripts in subdirectories. (This is so other `Makefile' rules can
+run `config.status' when it changes; see section Automatic Remaking,
+for an example).
+
+
+
+`config.status' checks several optional environment variables that
+can alter its behavior:
+
+
+
+
+
Variable:CONFIG_SHELL
+
+
+The shell with which to run @command{configure} for the @option{--recheck}
+option. It must be Bourne-compatible. The default is a shell that
+supports @env{LINENO} if available, and `/bin/sh' otherwise.
+
+
+
+
+
+
Variable:CONFIG_STATUS
+
+
+The file name to use for the shell script that records the
+configuration. The default is `./config.status'. This variable is
+useful when one package uses parts of another and the @command{configure}
+scripts shouldn't be merged because they are maintained separately.
+
+
+
+
+You can use `./config.status' in your Makefiles. For example, in
+the dependencies given above (see section Automatic Remaking),
+`config.status' is run twice when `configure.ac' has changed.
+If that bothers you, you can make each run only regenerate the files for
+that rule:
+
+
+Autoconf changes, and throughout the years some constructs are obsoleted.
+Most of the changes involve the macros, but the tools themselves, or
+even some concepts, are now considered obsolete.
+
+
+
+You may completely skip this chapter if you are new to Autoconf, its
+intention is mainly to help maintainers updating their packages by
+understanding how to move to more modern constructs.
+
+
+
+
+
+`config.status' now supports arguments to specify the files to
+instantiate, see section Recreating a Configuration, for more details.
+Before, environment variables had to be used.
+
+
+
+
+
Variable:CONFIG_COMMANDS
+
+
+The tags of the commands to execute. The default is the arguments given
+to AC_OUTPUT and AC_CONFIG_COMMANDS in
+`configure.ac'.
+
+
+
+
+
+
Variable:CONFIG_FILES
+
+
+The files in which to perform `@variable@' substitutions.
+The default is the arguments given to AC_OUTPUT and
+AC_CONFIG_FILES in `configure.ac'.
+
+
+
+
+
+
Variable:CONFIG_HEADERS
+
+
+The files in which to substitute C #define statements. The
+default is the arguments given to AC_CONFIG_HEADERS; if that
+macro was not called, `config.status' ignores this variable.
+
+
+
+
+
+
Variable:CONFIG_LINKS
+
+
+The symbolic links to establish. The default is the arguments given to
+AC_CONFIG_LINKS; if that macro was not called,
+`config.status' ignores this variable.
+
+(If `configure.ac' does not call AC_CONFIG_HEADERS, there is
+no need to set @command{CONFIG_HEADERS} in the make rules, equally
+for @command{CONFIG_COMMANDS} etc.)
+
+
+
+
+
+In order to produce `config.h.in', @command{autoheader} needs to
+build or to find templates for each symbol. Modern releases of Autoconf
+use AH_VERBATIM and AH_TEMPLATE (see section Autoheader Macros), but in older releases a file, `acconfig.h', contained the
+list of needed templates. @command{autoheader} copies comments and
+#define and #undef statements from `acconfig.h' in
+the current directory, if present. This file used to be mandatory if
+you AC_DEFINE any additional symbols.
+
+
+
+Modern releases of Autoconf also provide AH_TOP and
+AH_BOTTOM if you need to prepend/append some information to
+`config.h.in'. Ancient versions of Autoconf had a similar feature:
+if `./acconfig.h' contains the string `@TOP@',
+@command{autoheader} copies the lines before the line containing
+`@TOP@' into the top of the file that it generates. Similarly,
+if `./acconfig.h' contains the string `@BOTTOM@',
+@command{autoheader} copies the lines after that line to the end of the
+file it generates. Either or both of those strings may be omitted. An
+even older alternate way to produce the same effect in jurasik versions
+of Autoconf is to create the files `file.top' (typically
+`config.h.top') and/or `file.bot' in the current
+directory. If they exist, @command{autoheader} copies them to the
+beginning and end, respectively, of its output.
+
+
+
+In former versions of Autoconf, the files used in preparing a software
+package for distribution were:
+
+
+The @command{autoupdate} program updates a `configure.ac' file that
+calls Autoconf macros by their old names to use the current macro names.
+In version 2 of Autoconf, most of the macros were renamed to use a more
+uniform and descriptive naming scheme. See section Macro Names, for a
+description of the new scheme. Although the old names still work
+(see section Obsolete Macros, for a list of the old macros and the corresponding
+new names), you can make your `configure.ac' files more readable
+and make it easier to use the current Autoconf documentation if you
+update them to use the new macro names.
+
+
+
+
+If given no arguments, @command{autoupdate} updates `configure.ac',
+backing up the original version with the suffix `~' (or the value
+of the environment variable SIMPLE_BACKUP_SUFFIX, if that is
+set). If you give @command{autoupdate} an argument, it reads that file
+instead of `configure.ac' and writes the updated file to the
+standard output.
+
+
+
+@command{autoupdate} accepts the following options:
+
+
+
+
+
@option{--help}
+
+
@option{-h}
+
+Print a summary of the command line options and exit.
+
+
@option{--version}
+
+
@option{-V}
+
+Print the version number of Autoconf and exit.
+
+
@option{--verbose}
+
+
@option{-v}
+
+Report processing steps.
+
+
@option{--debug}
+
+
@option{-d}
+
+Don't remove the temporary files.
+
+
@option{--force}
+
+
@option{-f}
+
+Force the update even if the file has not changed. Disregard the cache.
+
+
@option{--include=dir}
+
+
@option{-I dir}
+
+Also look for input files in dir. Multiple invocations accumulate.
+Directories are browsed from last to first.
+
+Several macros are obsoleted in Autoconf, for various reasons (typically
+they failed to quote properly, couldn't be extended for more recent
+issues etc.). They are still supported, but deprecated: their use
+should be avoided.
+
+
+
+During the jump from Autoconf version 1 to version 2, most of the
+macros were renamed to use a more uniform and descriptive naming scheme,
+but their signature did not change. See section Macro Names, for a
+description of the new naming scheme. Below, there is just the mapping
+from old names to new names for these macros, the reader is invited to
+refer to the definition of the new macro for the signature and the
+description.
+
+
+
+
+
Macro:AC_ALLOCA
+
+
+AC_FUNC_ALLOCA
+
+
+
+
+
+
Macro:AC_ARG_ARRAY
+
+
+removed because of limited usefulness
+
+
+
+
+
+
Macro:AC_C_CROSS
+
+
+This macro is obsolete; it does nothing.
+
+
+
+
+
+
Macro:AC_CANONICAL_SYSTEM
+
+
+Determine the system type and set output variables to the names of the
+canonical system types. See section Getting the Canonical System Type, for details about the
+variables this macro sets.
+
+
+
+The user is encouraged to use either AC_CANONICAL_BUILD, or
+AC_CANONICAL_HOST, or AC_CANONICAL_TARGET, depending on
+the needs. Using AC_CANONICAL_TARGET is enough to run the two
+other macros.
+
+
+
+
+
+
Macro:AC_CHAR_UNSIGNED
+
+
+AC_C_CHAR_UNSIGNED
+
+
+
+
+
+
Macro:AC_CHECK_TYPE(type, default)
+
+
+Autoconf, up to 2.13, used to provide this version of
+AC_CHECK_TYPE, deprecated because of its flaws. Firstly, although
+it is a member of the CHECK clan, singular sub-family, it does
+more than just checking. Second, missing types are not
+typedef'd, they are #define'd, which can lead to
+incompatible code in the case of pointer types.
+
+
+
+This use of AC_CHECK_TYPE is obsolete and discouraged, see
+section Generic Type Checks, for the description of the current macro.
+
+
+
+If the type type is not defined, define it to be the C (or C++)
+builtin type default; e.g., `short' or `unsigned'.
+
+
+
+This macro is equivalent to:
+
+
+
+
+AC_CHECK_TYPE([type],
+ [AC_DEFINE([type], [default],
+ [Define to `default' if <sys/types.h>
+ does not define.])])
+
+
+
+In order to keep backward compatibility, the two versions of
+AC_CHECK_TYPE are implemented, selected by a simple heuristics:
+
+
+
+
+
+
+If there are three or four arguments, the modern version is used.
+
+
+
+If the second argument appears to be a C or C++ type, then the
+obsolete version is used. This happens if the argument is a C or C++
+builtin type or a C identifier ending in `_t', optionally
+followed by one of `[(* ' and then by a string of zero or more
+characters taken from the set `[]()* _a-zA-Z0-9'.
+
+
+
+If the second argument is spelled with the alphabet of valid C and C++
+types, the user is warned and the modern version is used.
+
+
+
+Otherwise, the modern version is used.
+
+
+
+You are encouraged either to use a valid builtin type, or to use the
+equivalent modern code (see above), or better yet, to use
+AC_CHECK_TYPES together with
+
+
+
+
+
+This is an obsolete version of AC_TRY_LINK (see section Examining Libraries), with the addition that it prints `checking for
+echo-text' to the standard output first, if echo-text is
+non-empty. Use AC_MSG_CHECKING and AC_MSG_RESULT instead
+to print messages (see section Printing Messages).
+
+
+
+
+
+
Macro:AC_CONST
+
+
+AC_C_CONST
+
+
+
+
+
+
Macro:AC_CROSS_CHECK
+
+
+Same as AC_C_CROSS, which is obsolete too, and does nothing
+:-).
+
+
+
+
+
+
Macro:AC_CYGWIN
+
+
+Check for the Cygwin environment in which case the shell variable
+CYGWIN is set to `yes'. Don't use this macro, the dignified
+means to check the nature of the host is using
+AC_CANONICAL_HOST. As a matter of fact this macro is defined as:
+
+
+
+
+Beware that the variable CYGWIN has a very special meaning when
+running CygWin32, and should not be changed. That's yet another reason
+not to use this macro.
+
+
+
+
+
+
Macro:AC_DECL_YYTEXT
+
+
+Does nothing, now integrated in AC_PROG_LEX.
+
+
+
+
+
+
Macro:AC_DIR_HEADER
+
+
+
+
+
+
+Like calling AC_FUNC_CLOSEDIR_VOID andAC_HEADER_DIRENT,
+but defines a different set of C preprocessor macros to indicate which
+header file is found:
+
+
+
Header
Old Symbol
New Symbol
+
+
`dirent.h'
DIRENT
HAVE_DIRENT_H
+
+
`sys/ndir.h'
SYSNDIR
HAVE_SYS_NDIR_H
+
+
`sys/dir.h'
SYSDIR
HAVE_SYS_DIR_H
+
+
`ndir.h'
NDIR
HAVE_NDIR_H
+
+
+
+
+
Macro:AC_DYNIX_SEQ
+
+
+If on Dynix/PTX (Sequent UNIX), add @option{-lseq} to output variable
+LIBS. This macro used to be defined as
+
+
+
+
+
+Defined the output variable EXEEXT based on the output of the
+compiler, which is now done automatically. Typically set to empty
+string if Unix and `.exe' if Win32 or OS/2.
+
+
+
+
Macro:AC_EMXOS2
+
+
+Similar to AC_CYGWIN but checks for the EMX environment on OS/2
+and sets EMXOS2.
+
+
+
+
Macro:AC_ERROR
+
+
+AC_MSG_ERROR
+
+
+
+
Macro:AC_FIND_X
+
+
+AC_PATH_X
+
+
+
+
Macro:AC_FIND_XTRA
+
+
+AC_PATH_XTRA
+
+
+
+
Macro:AC_FUNC_CHECK
+
+
+AC_CHECK_FUNC
+
+
+
+
Macro:AC_FUNC_WAIT3
+
+
+
+If wait3 is found and fills in the contents of its third argument
+(a `struct rusage *'), which HP-UX does not do, define
+HAVE_WAIT3.
+
+These days portable programs should use waitpid, not
+wait3, as wait3 is being removed from the Open Group
+standards, and will not appear in the next revision of POSIX.
+
+
+This macro is equivalent to calling AC_CHECK_LIB with a
+function argument of main. In addition, library can
+be written as any of `foo', @option{-lfoo}, or `libfoo.a'. In
+all of those cases, the compiler is passed @option{-lfoo}. However,
+library cannot be a shell variable; it must be a literal name.
+
+
+
+If the C type int is 16 bits wide, define INT_16_BITS.
+Use `AC_CHECK_SIZEOF(int)' instead.
+
+
+
+
Macro:AC_IRIX_SUN
+
+
+If on IRIX (Silicon Graphics UNIX), add @option{-lsun} to output
+LIBS. If you were using it to get getmntent, use
+AC_FUNC_GETMNTENT instead. If you used it for the NIS versions
+of the password and group functions, use `AC_CHECK_LIB(sun,
+getpwnam)'. Up to Autoconf 2.13, it used to be
+
+
+
+
+
+Define LONG_64_BITS if the C type long int is 64 bits wide.
+Use the generic macro `AC_CHECK_SIZEOF([long int])' instead.
+
+
+
+
Macro:AC_LONG_DOUBLE
+
+
+AC_C_LONG_DOUBLE
+
+
+
+
Macro:AC_LONG_FILE_NAMES
+
+
+AC_SYS_LONG_FILE_NAMES
+
+
+
+
Macro:AC_MAJOR_HEADER
+
+
+AC_HEADER_MAJOR
+
+
+
+
Macro:AC_MEMORY_H
+
+
+
+Used to define NEED_MEMORY_H if the mem functions were
+defined in `memory.h'. Today it is equivalent to
+`AC_CHECK_HEADERS(memory.h)'. Adjust your code to depend upon
+HAVE_MEMORY_H, not NEED_MEMORY_H, see See section Standard Symbols.
+
+
+
+
Macro:AC_MINGW32
+
+
+Similar to AC_CYGWIN but checks for the MingW32 compiler
+environment and sets MINGW32.
+
+
+
+
Macro:AC_MINUS_C_MINUS_O
+
+
+AC_PROG_CC_C_O
+
+
+
+
Macro:AC_MMAP
+
+
+AC_FUNC_MMAP
+
+
+
+
Macro:AC_MODE_T
+
+
+AC_TYPE_MODE_T
+
+
+
+
Macro:AC_OBJEXT
+
+
+
+Defined the output variable OBJEXT based on the output of the
+compiler, after .c files have been excluded. Typically set to `o'
+if Unix, `obj' if Win32. Now the compiler checking macros handle
+this automatically.
+
+
+Make m4 print a message to the standard error output warning that
+this-macro-name is obsolete, and giving the file and line number
+where it was called. this-macro-name should be the name of the
+macro that is calling AC_OBSOLETE. If suggestion is given,
+it is printed at the end of the warning message; for example, it can be
+a suggestion for what to use instead of this-macro-name.
+
+For instance
+
+
+
+AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
+
+
+You are encouraged to use AU_DEFUN instead, since it gives better
+services to the user.
+
+
+Specify additional shell commands to run at the end of
+`config.status', and shell commands to initialize any variables
+from @command{configure}. This macro may be called multiple times. It is
+obsolete, replaced by AC_CONFIG_COMMANDS.
+
+Here is an unrealistic example:
+
+
+
+fubar=27
+AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
+ [fubar=$fubar])
+AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
+ [echo init bit])
+
+
+Aside from the fact that AC_CONFIG_COMMANDS requires an
+additional key, an important difference is that
+AC_OUTPUT_COMMANDS is quoting its arguments twice, while
+AC_CONFIG_COMMANDS. This means that AC_CONFIG_COMMANDS
+can safely be given macro calls as arguments:
+
+
+
+AC_CONFIG_COMMANDS(foo, [my_FOO()])
+
+
+conversely, where one level of quoting was enough for literal strings
+with AC_OUTPUT_COMMANDS, you need two with
+AC_CONFIG_COMMANDS. The following lines are equivalent:
+
+
+
+
+
+If the system automatically restarts a system call that is interrupted
+by a signal, define HAVE_RESTARTABLE_SYSCALLS. This macro does
+not check if system calls are restarted in general--it tests whether a
+signal handler installed with signal (but not sigaction)
+causes system calls to be restarted. It does not test if system calls
+can be restarted when interrupted by signals that have no handler.
+
+These days portable programs should use sigaction with
+SA_RESTART if they want restartable system calls. They should
+not rely on HAVE_RESTARTABLE_SYSCALLS, since nowadays whether a
+system call is restartable is a dynamic issue, not a configuration-time
+issue.
+
+
+
+
Macro:AC_SYS_SIGLIST_DECLARED
+
+
+AC_DECL_SYS_SIGLIST
+
+
+
+
Macro:AC_TEST_CPP
+
+
+AC_TRY_CPP
+
+
+
+
Macro:AC_TEST_PROGRAM
+
+
+AC_TRY_RUN
+
+
+
+
Macro:AC_TIMEZONE
+
+
+AC_STRUCT_TIMEZONE
+
+
+
+
Macro:AC_TIME_WITH_SYS_TIME
+
+
+AC_HEADER_TIME
+
+
+
+
Macro:AC_UID_T
+
+
+AC_TYPE_UID_T
+
+
+
+
Macro:AC_UNISTD_H
+
+
+Same as `AC_CHECK_HEADERS(unistd.h)'.
+
+
+
+
Macro:AC_USG
+
+
+
+Define USG if the BSD string functions are defined in
+`strings.h'. You should no longer depend upon USG, but on
+HAVE_STRING_H, see See section Standard Symbols.
+
+
+If the cache file is inconsistent with the current host, target and
+build system types, it used to execute cmd or print a default
+error message.
+
+This is now handled by default.
+
+
+
+
Macro:AC_VERBOSE(result-description)
+
+
+AC_MSG_RESULT.
+
+
+
+
Macro:AC_VFORK
+
+
+AC_FUNC_VFORK
+
+
+
+
Macro:AC_VPRINTF
+
+
+AC_FUNC_VPRINTF
+
+
+
+
Macro:AC_WAIT3
+
+
+AC_FUNC_WAIT3
+
+
+
+
Macro:AC_WARN
+
+
+AC_MSG_WARN
+
+
+
+
Macro:AC_WORDS_BIGENDIAN
+
+
+AC_C_BIGENDIAN
+
+
+
+
Macro:AC_XENIX_DIR
+
+
+
+This macro used to add @option{-lx} to output variable LIBS if on
+Xenix. Also, if `dirent.h' is being checked for, added
+@option{-ldir} to LIBS. Now it is merely an alias of
+AC_HEADER_DIRENT instead, plus some code to detect whether
+running XENIX on which you should not depend:
+
+
+
+Autoconf version 2 is mostly backward compatible with version 1.
+However, it introduces better ways to do some things, and doesn't
+support some of the ugly things in version 1. So, depending on how
+sophisticated your `configure.ac' files are, you might have to do
+some manual work in order to upgrade to version 2. This chapter points
+out some problems to watch for when upgrading. Also, perhaps your
+@command{configure} scripts could benefit from some of the new features in
+version 2; the changes are summarized in the file `NEWS' in the
+Autoconf distribution.
+
+
+
+
+
+If you have an `aclocal.m4' installed with Autoconf (as opposed to
+in a particular package's source directory), you must rename it to
+`acsite.m4'. See section Using @command{autoconf} to Create @command{configure}.
+
+
+
+If you distribute `install.sh' with your package, rename it to
+`install-sh' so make builtin rules won't inadvertently
+create a file called `install' from it. AC_PROG_INSTALL
+looks for the script under both names, but it is best to use the new name.
+
+
+
+If you were using `config.h.top', `config.h.bot', or
+`acconfig.h', you still can, but you will have less clutter if you
+use the AH_ macros. See section Autoheader Macros.
+
+
+
+
+
+Add `@CFLAGS@', `@CPPFLAGS@', and `@LDFLAGS@' in
+your `Makefile.in' files, so they can take advantage of the values
+of those variables in the environment when @command{configure} is run.
+Doing this isn't necessary, but it's a convenience for users.
+
+
+
+Also add `@configure_input@' in a comment to each input file for
+AC_OUTPUT, so that the output files will contain a comment saying
+they were produced by @command{configure}. Automatically selecting the
+right comment syntax for all the kinds of files that people call
+AC_OUTPUT on became too much work.
+
+
+
+Add `config.log' and `config.cache' to the list of files you
+remove in distclean targets.
+
+
+
+If you have the following in `Makefile.in':
+
+
+
+
+prefix = /usr/local
+exec_prefix = $(prefix)
+
+
+
+you must change it to:
+
+
+
+
+prefix = @prefix@
+exec_prefix = @exec_prefix@
+
+
+
+The old behavior of replacing those variables without `@'
+characters around them has been removed.
+
+
+
+
+
+Many of the macros were renamed in Autoconf version 2. You can still
+use the old names, but the new ones are clearer, and it's easier to find
+the documentation for them. See section Obsolete Macros, for a table showing the
+new names for the old macros. Use the @command{autoupdate} program to
+convert your `configure.ac' to using the new macro names.
+See section Using @command{autoupdate} to Modernize @file{configure.ac}.
+
+
+
+Some macros have been superseded by similar ones that do the job better,
+but are not call-compatible. If you get warnings about calling obsolete
+macros while running @command{autoconf}, you may safely ignore them, but
+your @command{configure} script will generally work better if you follow
+the advice it prints about what to replace the obsolete macros with. In
+particular, the mechanism for reporting the results of tests has
+changed. If you were using echo or AC_VERBOSE (perhaps
+via AC_COMPILE_CHECK), your @command{configure} script's output will
+look better if you switch to AC_MSG_CHECKING and
+AC_MSG_RESULT. See section Printing Messages. Those macros work best
+in conjunction with cache variables. See section Caching Results.
+
+
+
+
+
+If you were checking the results of previous tests by examining the
+shell variable DEFS, you need to switch to checking the values of
+the cache variables for those tests. DEFS no longer exists while
+@command{configure} is running; it is only created when generating output
+files. This difference from version 1 is because properly quoting the
+contents of that variable turned out to be too cumbersome and
+inefficient to do every time AC_DEFINE is called. See section Cache Variable Names.
+
+
+
+For example, here is a `configure.ac' fragment written for Autoconf
+version 1:
+
+
+
+
+AC_HAVE_FUNCS(syslog)
+case "$DEFS" in
+*-DHAVE_SYSLOG*) ;;
+*) # syslog is not in the default libraries. See if it's in some other.
+ saved_LIBS="$LIBS"
+ for lib in bsd socket inet; do
+ AC_CHECKING(for syslog in -l$lib)
+ LIBS="$saved_LIBS -l$lib"
+ AC_HAVE_FUNCS(syslog)
+ case "$DEFS" in
+ *-DHAVE_SYSLOG*) break ;;
+ *) ;;
+ esac
+ LIBS="$saved_LIBS"
+ done ;;
+esac
+
+
+
+Here is a way to write it for version 2:
+
+
+
+
+AC_CHECK_FUNCS(syslog)
+if test $ac_cv_func_syslog = no; then
+ # syslog is not in the default libraries. See if it's in some other.
+ for lib in bsd socket inet; do
+ AC_CHECK_LIB($lib, syslog, [AC_DEFINE(HAVE_SYSLOG)
+ LIBS="$LIBS -l$lib"; break])
+ done
+fi
+
+
+
+If you were working around bugs in AC_DEFINE_UNQUOTED by adding
+backslashes before quotes, you need to remove them. It now works
+predictably, and does not treat quotes (except back quotes) specially.
+See section Setting Output Variables.
+
+
+
+All of the boolean shell variables set by Autoconf macros now use
+`yes' for the true value. Most of them use `no' for false,
+though for backward compatibility some use the empty string instead. If
+you were relying on a shell variable being set to something like 1 or
+`t' for true, you need to change your tests.
+
+
+
+
+
+When defining your own macros, you should now use AC_DEFUN
+instead of define. AC_DEFUN automatically calls
+AC_PROVIDE and ensures that macros called via AC_REQUIRE
+do not interrupt other macros, to prevent nested `checking...'
+messages on the screen. There's no actual harm in continuing to use the
+older way, but it's less convenient and attractive. See section Macro Definitions.
+
+
+
+You probably looked at the macros that came with Autoconf as a guide for
+how to do things. It would be a good idea to take a look at the new
+versions of them, as the style is somewhat improved and they take
+advantage of some new features.
+
+
+
+If you were doing tricky things with undocumented Autoconf internals
+(macros, variables, diversions), check whether you need to change
+anything to account for changes that have been made. Perhaps you can
+even use an officially supported technique in version 2 instead of
+kludging. Or perhaps not.
+
+
+
+To speed up your locally written feature tests, add caching to them.
+See whether any of your tests are of general enough usefulness to
+encapsulate into macros that you can share.
+
+
+
+
+
+The introduction of the previous section (see section Upgrading From Version 1) perfectly
+suits this section...
+
+
+
+
+
+Autoconf version 2.50 is mostly backward compatible with version 2.13.
+However, it introduces better ways to do some things, and doesn't
+support some of the ugly things in version 2.13. So, depending on how
+sophisticated your `configure.ac' files are, you might have to do
+some manual work in order to upgrade to version 2.50. This chapter
+points out some problems to watch for when upgrading. Also, perhaps
+your @command{configure} scripts could benefit from some of the new
+features in version 2.50; the changes are summarized in the file
+`NEWS' in the Autoconf distribution.
+
+The most important changes are invisible to you: the implementation of
+most macros have completely changed. This allowed more factorization of
+the code, better error messages, a higher uniformity of the user's
+interface etc. Unfortunately, as a side effect, some construct which
+used to (miraculously) work might break starting with Autoconf 2.50.
+The most common culprit is bad quotation.
+
+
+
+For instance, in the following example, the message is not properly
+quoted:
+
+
+
+
+Because Autoconf has been dormant for years, Automake provided
+Autoconf-like macros for a while. Autoconf 2.50 now provides better
+versions of these macros, integrated in the AC_ namespace,
+instead of AM_. But in order to ease the upgrading via
+@command{autoupdate}, bindings to such AM_ macros are provided.
+
+
+
+Unfortunately Automake did not quote the name of these macros!
+Therefore, when @command{m4} finds something like
+`AC_DEFUN(AM_TYPE_PTRDIFF_T, ...)' in `aclocal.m4',
+AM_TYPE_PTRDIFF_T is
+expanded, replaced with its Autoconf definition.
+
+
+
+Fortunately Autoconf catches pre-AC_INIT expansions, and will
+complain, in its own words:
+
+
+
+
+$ cat configure.in
+AC_INIT
+AM_TYPE_PTRDIFF_T
+$ aclocal-1.4
+$ autoconf
+./aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
+actypes.m4:289: AM_TYPE_PTRDIFF_T is expanded from...
+./aclocal.m4:17: the top level
+$
+
+
+
+Future versions of Automake will simply no longer define most of these
+macros, and will properly quote the names of the remaining macros.
+But you don't have to wait for it to happen to do the right thing right
+now: do not depend upon macros from Automake as it is simply not its job
+to provide macros (but the one it requires by itself):
+
+
+
+
+Based on the experience of compiler writers, and after long public
+debates, many aspects of the cross-compilation chain have changed:
+
+
+
+
+
+
+the relationship between the build, host, and target architecture types,
+
+
+
+the command line interface for specifying them to @command{configure},
+
+
+
+the variables defined in @command{configure},
+
+
+
+the enabling of cross-compilation mode.
+
+
+
+The relationship between build, host, and target have been cleaned up:
+the chain of default is now simply: target defaults to host, host to
+build, and build to the result of @command{config.guess}. Nevertheless,
+in order to ease the transition from 2.13 to 2.50, the following
+transition scheme is implemented. Do not rely on it, as it will
+be completely disabled in a couple of releases (we cannot keep it, as it
+proves to cause more problems than to cure).
+
+
+
+They all default to the result of running @command{config.guess}, unless
+you specify either @option{--build} or @option{--host}. In this case,
+the default becomes the system type you specified. If you specify both,
+and they're different, @command{configure} will enter cross compilation
+mode, so it won't run any tests that require execution.
+
+
+
+Hint: if you mean to override the result of @command{config.guess},
+prefer @option{--build} over @option{--host}. In the future,
+@option{--host} will not override the name of the build system type.
+Whenever you specify --host, be sure to specify --build
+too.
+
+
+
+For backward compatibility, @command{configure} will accept a system
+type as an option by itself. Such an option will override the defaults
+for build, host and target system types. The following configure
+statement will configure a cross toolchain that will run on NetBSD/alpha
+but generate code for GNU Hurd/sparc, which is also the build platform.
+
+
+
+
+./configure --host=alpha-netbsd sparc-gnu
+
+
+
+In Autoconf, the variables build, host, and target
+had a different semantics before and after the invocation of
+AC_CANONICAL_BUILD etc. Now, the argument of @option{--build} is
+strictly copied into build_alias, and is left empty otherwise.
+After the AC_CANONICAL_BUILD, build is set to the
+canonicalized build type. To ease the transition, before, its contents
+is the same as that of build_alias. Do not rely on this
+broken feature.
+
+
+
+For consistency with the backward compatibility scheme exposed above,
+when @option{--host} is specified by @option{--build} isn't, the build
+system will be assumed to be the same as @option{--host}, and
+`build_alias' will be set to that value. Eventually, this
+historically incorrect behavior will go away.
+
+
+
+The former scheme to enable cross-compilation proved to cause more harm
+than good, in particular, it used to be triggered too easily, leaving
+regular end users puzzled in front of cryptic error messages.
+@command{configure} could even enter cross-compilation mode, only
+because the compiler was not functional. This is mainly because
+@command{configure} used to try to detect cross-compilation, instead of
+waiting for an explicit flag from the user.
+
+
+
+That's the short documentation. To ease the transition between 2.13 and
+its successors, a more complicated scheme is implemented. Do not
+rely on the following, as it will be removed in a near future.
+
+
+
+If you specify @option{--host}, but not @option{--build}, when
+@command{configure} performs the first compiler test it will try to run
+an executable produced by the compiler. If the execution fails, it will
+enter cross-compilation mode. This is fragile. Moreover, by the time
+the compiler test is performed, it may be too late to modify the
+build-system type: other tests may have already been performed.
+Therefore, whenever you specify --host, be sure to specify
+--build too.
+
+
+
+
+will enter cross-compilation mode. The former interface, which
+consisted in setting the compiler to a cross-compiler without informing
+@command{configure} is obsolete. For instance, @command{configure} will
+fail if it can't run the code generated by the specified compiler if you
+configure as follows:
+
+
+
+
+Up to Autoconf 2.13, the replacement of functions was triggered via the
+variable LIBOBJS. Since Autoconf 2.50, the macro
+AC_LIBOBJ should be used instead (see section Generic Function Checks).
+Starting at Autoconf 2.53, the use of LIBOBJS is an error.
+
+
+
+This change is mandated by the unification of the GNU Build System
+components. In particular, the various fragile techniques used to parse
+a `configure.ac' are all replaced with the use of traces. As a
+consequence, any action must be traceable, which obsoletes critical
+variable assignments. Fortunately, LIBOBJS was the only problem.
+
+
+
+At the time this documentation is written, Automake does not rely on
+traces yet, but this is planed for a near future. Nevertheless, to
+ease the transition, and to guarantee this future Automake release will
+be able to use Autoconf 2.53, using LIBOBJS directly will make
+@command{autoconf} fail. But note that the output, @command{configure},
+is correct and fully functional: you have some delay to adjust your
+source.
+
+
+
+There are two typical uses of LIBOBJS: asking for a replacement
+function, and adjusting LIBOBJS for Automake and/or Libtool.
+
+
+
+As for function replacement, the fix is immediate: use
+AC_LIBOBJ. For instance:
+
+
+
+
+When asked for automatic de-ANSI-fication, Automake needs
+LIBOBJS'ed filenames to have `$U' appended to the
+base names. Libtool requires the definition of LTLIBOBJS, which
+suffixes are mapped to `.lo'. Although Autoconf provides them with
+means to free the user to do that by herself, by the time of this
+writing, none do. Therefore, it is common to see `configure.ac'
+end with:
+
+
+
+
+# This is necessary so that .o files in LIBOBJS are also built via
+# the ANSI2KNR-filtering rules.
+LIBOBJS=`echo "$LIBOBJS" | sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
+LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.o/\.lo/g'`
+AC_SUBST(LTLIBOBJS)
+
+
+
+First, note that this code is wrong, because `.o' is not the
+only possible extension(4)! Because the token LIBOBJS is now
+forbidden, you will have to replace this snippet with:
+
+
+
+
+# This is necessary so that .o files in LIBOBJS are also built via
+# the ANSI2KNR-filtering rules.
+LIB@&t@OBJS=`echo "$LIB@&t@OBJS" |
+ sed 's,\.[[^.]]* ,$U&,g;s,\.[[^.]]*$,$U&,'`
+LTLIBOBJS=`echo "$LIB@&t@OBJS" |
+ sed 's,\.[[^.]]* ,.lo ,g;s,\.[[^.]]*$,.lo,'`
+AC_SUBST(LTLIBOBJS)
+
+
+
+Unfortunately, @command{autoupdate} cannot help here, since... this is
+not a macro! Of course, first make sure your release of Automake and/or
+Libtool still requires these.
+
+
+
+
+
+Note: This section describes an experimental feature which will
+be part of Autoconf in a forthcoming release. Although we believe
+Autotest is stabilizing, this documentation describes an interface which
+might change in the future: do not depend upon Autotest without
+subscribing to the Autoconf mailing lists.
+
+
+
+It is paradoxical that portable projects depend on nonportable tools to
+run their test suite. Autoconf by itself is the paragon of this
+problem: although it aims at perfectly portability, up to 2.13, its test
+suite was using DejaGNU, a rich and complex testing framework, but which
+is far from being standard on Unix systems. Worse yet, it was likely to
+be missing on the most fragile platforms, the very platforms that are
+most likely to torture Autoconf and exhibit deficiencies.
+
+
+
+To circumvent this problem many package maintainers have developed their
+own testing framework, based on simple shell scripts whose sole output
+are their exit status: the test succeeded, or failed. In addition, most
+of these tests share some common patterns, what results in lots of
+duplicated code, tedious maintenance etc.
+
+
+
+Following exactly the same reasoning that yielded to the inception of
+Autoconf, Autotest provides a test suite generation frame work, based on
+M4 macros, building a portable shell script. The suite itself is
+equipped with automatic logging and tracing facilities which greatly
+diminish the interaction with bug reporters, and simple timing reports.
+
+
+
+Autoconf itself has been using Autotest for years, and we do attest that
+it has considerably improved the strength of the test suite, and the
+quality of bug reports. Other projects are known to use some generation
+of Autotest, such as Bison, Free Recode, Free Wdiff, GNU Tar, each of
+them having different needs, what slowly polishes Autotest as a general
+testing framework.
+
+
+
+Nonetheless, compared to DejaGNU, Autotest is inadequate for interactive
+tool testing, which is probably its main limitation.
+
+
+
+
+
+Generating testing or validation suites using Autotest is rather easy.
+The whole validation suite is held in a file to be processed through
+@command{autom4te}, itself using GNU m4 under the scene, to
+produce a stand-alone Bourne shell script which then gets distributed.
+Neither @command{autom4te} nor GNU m4 are not needed anymore at
+the installer end.
+
+
+
+
+Each test of the validation suite should be part of some test group. A
+test group is a sequence of interwoven tests that ought to be
+executed together, usually because one test in the group creates data
+files than a later test in the same group needs to read. Complex test
+groups make later debugging more tedious. It is much better keeping
+keep only a few tests per test group, and if you can put only one test
+per test group, this is just ideal.
+
+
+
+For all but the simplest packages, some file such as `testsuite.at'
+does not fully hold all test sources, as these are often easier to
+maintain in separate files. Each of these separate files holds a single
+test group, or a sequence of test groups all addressing some common
+functionality in the package. In such cases, file `testsuite.at'
+only initializes the whole validation suite, and sometimes do elementary
+health checking, before listing include statements for all other test
+files. The special file `package.m4', containing the
+identification of the package, is automatically included if found.
+
+
+
+The validation scripts that Autotest produces are by convention called
+@command{testsuite}. When run, @command{testsuite} executes each test
+group in turn, producing only one summary line per test to say if that
+particular test succeeded or failed. At end of all tests, summarizing
+counters get printed. If any test failed, one debugging script gets
+automatically generated for each test group which failed. These
+debugging scripts are named `testsuite.nn', where nn is
+the sequence number of the test group. In the ideal situation, none of
+the tests fail, and consequently, no debugging script is generated out
+of validation.
+
+
+
+The automatic generation of debugging scripts for failed test has the
+purpose of easing the chase for bugs.
+
+
+
+It often happens in practice that individual tests in the validation
+suite need to get information coming out of the configuration process.
+Some of this information, common for all validation suites, is provided
+through the file `atconfig', automatically created by
+AC_CONFIG_TESTDIR. For configuration informations which your
+testing environment specifically needs, you might prepare an optional
+file named `atlocal.in', instantiated by AC_CONFIG_FILES.
+The configuration process produces `atconfig' and `atlocal'
+out of these two input files, and these two produced files are
+automatically read by the `testsuite' script.
+
+
+
+Here is a diagram showing the relationship between files.
+
+
+
+Files used in preparing a software package for distribution:
+
+
+
+
+When run, the test suite creates a log file named after itself, e.g., a
+test suite named @command{testsuite} creates `testsuite.log'. It
+contains a lot of information, usually more than maintainers actually
+need, but therefore most of the time it contains all that is needed:
+
+
+
+
+
command line arguments
+
+A very bad Unix habit which is unfortunately wide spread consists of
+setting environment variables before the command, such as in
+`CC=my-home-grown-cc ./testsuite'. This results in the test suite
+not knowing this change, hence (i) it can't report it to you, and (ii)
+it cannot preserve the value of CC for subsequent runs(5). Autoconf faced exactly the same problem, and solved it by asking
+users to pass the variable definitions as command line arguments.
+Autotest requires this rule too, but has no means to enforce it; the log
+then contains a trace of the variables the user changed.
+
+
`ChangeLog' excerpts
+
+The topmost lines of all the `ChangeLog's found in the source
+hierarchy. This is especially useful when bugs are reported against
+development versions of the package, since the version string does not
+provide sufficient information to know the exact state of the sources
+the user compiled. Of course this relies on the use of a
+`ChangeLog'.
+
+
build machine
+
+Running a test suite in a cross-compile environment is not an easy task,
+since it would mean having the test suite run on a machine build,
+while running programs on a machine host. It is much simpler to
+run both the test suite and the programs on host, but then, from
+the point of view of the test suite, there remains a single environment,
+host = build. The log contains relevant information on the
+state of the build machine, including some important environment
+variables.
+
+
tested programs
+
+The absolute path and answers to @option{--version} of the tested
+programs (see section Writing `testsuite.at', AT_TESTED).
+
+
configuration log
+
+The contents of `config.log', as created by @command{configure},
+are appended. It contains the configuration flags and a detailed report
+on the configuration itself.
+
+The `testsuite.at' is a Bourne shell script making use of special
+Autotest M4 macros. It often contains a call to AT_INIT nears
+its beginning followed by one call to m4_include per source file
+for tests. Each such included file, or the remainder of
+`testsuite.at' if include files are not used, contain a sequence of
+test groups. Each test group begins with one call to AT_SETUP,
+it contains an arbitrary number of shell commands or calls to
+AT_CHECK, and it completes with one call to AT_CLEANUP.
+
+
+
+
+
Macro:AT_INIT(@ovar{name})
+
+
+Initialize Autotest. Giving a name to the test suite is
+encouraged if your package includes several test suites. In any case,
+the test suite always displays the package name and version. It also
+inherits the package bug report address.
+
+
+
+
+
+
Macro:AT_TESTED(executables)
+
+
+Log the path and answer to @option{--version} of each program in
+space-separated list executables. Several invocations register
+new executables, in other words, don't fear registering one program
+several times.
+
+
+
+
+Autotest test suites rely on the PATH to find the tested program.
+This saves from generating the absolute paths to the various tools, and
+makes it possible to test installed programs. Therefore, knowing what
+programs are being exercised is crucial to understand some problems in
+the test suite itself, or its occasional misuses. It is a good idea to
+also subscribe foreign programs you depend upon, to ease incompatibility
+diagnostics.
+
+
+
+
+
Macro:AT_SETUP(test-group-name)
+
+
+This macro starts a group of related tests, all to be executed in the
+same subshell. It accepts a single argument, which holds a few words
+(no more than about 30 or 40 characters) quickly describing the purpose
+of the test group being started.
+
+
+
+
+
+
Macro:AT_KEYWORDS(keywords)
+
+
+Associate the space-separated list of keywords to the enclosing
+test group. This makes it possible to run "slices" of the test suite.
+For instance if some of your test groups exercise some `foo'
+feature, then using `AT_KEYWORDS(foo)' lets you run
+`./testsuite -k foo' to run exclusively these test groups. The
+title of the test group is automatically recorded to
+AT_KEYWORDS.
+
+
+
+Several invocations within a test group accumulate new keywords. In
+other words, don't fear registering several times the same keyword in a
+test group.
+
+
+
+
+
+
Macro:AT_CLEANUP
+
+
+End the current test group.
+
+
+
+
+
+
Macro:AT_DATA(file, contents)
+
+
+Initialize an input data file with given contents. Of
+course, the contents have to be properly quoted between square
+brackets to protect against included commas or spurious m4
+expansion. The contents ought to end with an end of line.
+
+
+Execute a test by performing given shell commands. These commands
+should normally exit with status, while producing expected
+stdout and stderr contents. If commands exit with
+status 77, then the whole test group is skipped.
+
+
+
+The commandsmust not redirect the standard output, nor the
+standard error.
+
+
+
+If status, or stdout, or stderr is `ignore', then
+the corresponding value is not checked.
+
+
+
+The special value `expout' for stdout means the expected
+output of the commands is the content of the file `expout'.
+If stdout is `stdout', then the standard output of the
+commands is available for further tests in the file `stdout'.
+Similarly for stderr with `expout' and `stderr'.
+
+Autotest test suites support the following arguments:
+
+
+
+
+
`--help'
+
+
`-h'
+
+Display the list of options and exit successfully.
+
+
`--version'
+
+
`-V'
+
+Display the version of the test suite and exit successfully.
+
+
`--clean'
+
+
`-c'
+
+Remove all the files the test suite might have created and exit. Meant
+for clean Makefile targets.
+
+
`--list'
+
+
`-l'
+
+List all the tests (or only the selection), including their possible
+keywords.
+
+
+
+By default all the tests are performed (or described with
+@option{--list}) in the default environment first silently, then
+verbosely, but the environment, set of tests, and verbosity level can be
+tuned:
+
+
+
+
+
`variable=value'
+
+Set the environment variable to value. Do not run
+`FOO=foo ./testsuite' as debugging scripts would then run in a
+different environment.
+
+
+The variable AUTOTEST_PATH specifies the testing path to prepend
+to PATH. It handles specially relative paths (not starting with
+`/'): they are considered to be relative to the top level of the
+package being built. All the directories are made absolute, first
+starting from the top level build tree, then from the
+source tree. For instance `./testsuite
+AUTOTEST_PATH=tests:bin' for a `/src/foo-1.0' source package built
+in `/tmp/foo' results in `/tmp/foo/tests:/tmp/foo/bin' and
+then `/src/foo-1.0/tests:/src/foo-1.0/bin' being prepended to
+PATH.
+
+
`number'
+
+
`number-number'
+
+
`number-'
+
+
`-number'
+
+Add the corresponding test groups, with obvious semantics, to the
+selection.
+
+
`--keywords=keywords'
+
+
`-k keywords'
+
+Add to the selection the test groups which title or keywords (arguments
+to AT_SETUP or AT_KEYWORDS) match all the keywords
+of the comma separated list keywords.
+
+Running `./testsuite -k autoupdate,FUNC' will select all the tests
+tagged with `autoupdate'and`FUNC' (as in
+`AC_CHECK_FUNC', `AC_FUNC_FNMATCH' etc.) while
+`./testsuite -k autoupdate -k FUNC' runs all the tests tagged with
+`autoupdate'or`FUNC'.
+
+
`--errexit'
+
+
`-e'
+
+If any test fails, immediately abort testing. It implies
+@option{--debug}: post test group clean up, debugging script generation,
+and logging are inhibited. This option is meant for the full test
+suite, it is not really useful for generated debugging scripts.
+
+
`--verbose'
+
+
`-v'
+
+Force more verbosity in the detailed output of what is being done. This
+is the default for debugging scripts.
+
+
`--debug'
+
+
`-d'
+
+Do not remove the files after a test group was performed --but they are
+still removed before, therefore using this option is sane when
+running several test groups. Do not create debugging scripts. Do not
+log (in order to preserve supposedly existing full log file). This is
+the default for debugging scripts.
+
+
+For putting Autotest into movement, you need some configuration and
+Makefile machinery. We recommend, at least if your package uses deep or
+shallow hierarchies, that you use `tests/' as the name of the
+directory holding all your tests and their `Makefile'. Here is a
+check list of things to do.
+
+
+
+
+
+
+
+
+Make sure to create the file `package.m4', which defines the
+identity of the package. It must define AT_PACKAGE_STRING, the
+full signature of the package, and AT_PACKAGE_BUGREPORT, the
+address to which bug reports should be sent. For sake of completeness,
+we suggest that you also define AT_PACKAGE_NAME,
+AT_PACKAGE_TARNAME, and AT_PACKAGE_VERSION.
+See section Initializing @command{configure}, for a description of these variables. We
+suggest the following Makefile excerpt:
+
+
+
+
+Be sure to distribute `package.m4' and to put it into the source
+hierarchy: the test suite ought to be shipped!
+
+
+
+Use the AT_CONFIG macro from within file `configure.ac'.
+This macro accepts one argument, which is the directory, relative to the
+test directory, where the executables are prepared.
+
+
+
+Still within `configure.ac', ensure that some
+AC_CONFIG_FILES command includes substitution for
+`tests/atconfig' and also, as appropriate, `tests/atlocal'.
+
+
+
+The `tests/Makefile.in' should be modified so the validation in
+your package is triggered by `make check'. An example is provided
+below.
+
+
+
+
+With Automake, here is a minimal example about how to link `make
+check' with a validation suite.
+
+
+
+
+What are the restrictions on distributing @command{configure}
+scripts that Autoconf generates? How does that affect my
+programs that use them?
+
+
+
+There are no restrictions on how the configuration scripts that Autoconf
+produces may be distributed or used. In Autoconf version 1, they were
+covered by the GNU General Public License. We still encourage
+software authors to distribute their work under terms like those of the
+GPL, but doing so is not required to use Autoconf.
+
+
+
+Of the other files that might be used with @command{configure},
+`config.h.in' is under whatever copyright you use for your
+`configure.ac'. `config.sub' and `config.guess' have an
+exception to the GPL when they are used with an Autoconf-generated
+@command{configure} script, which permits you to distribute them under the
+same terms as the rest of your package. `install-sh' is from the X
+Consortium and is not copyrighted.
+
+
+
+
+
+Many M4 implementations have hard-coded limitations on the size and
+number of macros that Autoconf exceeds. They also lack several
+builtin macros that it would be difficult to get along without in a
+sophisticated application like Autoconf, including:
+
+
+
+
+Autoconf requires version 1.4 or above of GNU M4 because it uses
+frozen state files.
+
+
+
+Since only software maintainers need to use Autoconf, and since GNU
+M4 is simple to configure and install, it seems reasonable to require
+GNU M4 to be installed also. Many maintainers of GNU and
+other free software already have most of the GNU utilities
+installed, since they prefer them.
+
+
+
+
+
+If Autoconf requires GNU M4 and GNU M4 has an Autoconf
+@command{configure} script, how do I bootstrap? It seems like a chicken
+and egg problem!
+
+
+
+This is a misunderstanding. Although GNU M4 does come with a
+@command{configure} script produced by Autoconf, Autoconf is not required
+in order to run the script and install GNU M4. Autoconf is only
+required if you want to change the M4 @command{configure} script, which few
+people have to do (mainly its maintainer).
+
+
+
+
+
+Why not use Imake instead of @command{configure} scripts?
+
+
+
+Several people have written addressing this question, so I include
+adaptations of their explanations here.
+
+
+
+The following answer is based on one written by Richard Pixley:
+
+
+
+
+
+Autoconf generated scripts frequently work on machines that it has
+never been set up to handle before. That is, it does a good job of
+inferring a configuration for a new system. Imake cannot do this.
+
+
+
+Imake uses a common database of host specific data. For X11, this makes
+sense because the distribution is made as a collection of tools, by one
+central authority who has control over the database.
+
+
+
+GNU tools are not released this way. Each GNU tool has a
+maintainer; these maintainers are scattered across the world. Using a
+common database would be a maintenance nightmare. Autoconf may appear
+to be this kind of database, but in fact it is not. Instead of listing
+host dependencies, it lists program requirements.
+
+
+
+If you view the GNU suite as a collection of native tools, then the
+problems are similar. But the GNU development tools can be
+configured as cross tools in almost any host+target permutation. All of
+these configurations can be installed concurrently. They can even be
+configured to share host independent files across hosts. Imake doesn't
+address these issues.
+
+
+
+Imake templates are a form of standardization. The GNU coding
+standards address the same issues without necessarily imposing the same
+restrictions.
+
+
+
+Here is some further explanation, written by Per Bothner:
+
+
+
+
+
+One of the advantages of Imake is that it easy to generate large
+Makefiles using cpp's `#include' and macro mechanisms.
+However, cpp is not programmable: it has limited conditional
+facilities, and no looping. And cpp cannot inspect its
+environment.
+
+
+
+All of these problems are solved by using sh instead of
+cpp. The shell is fully programmable, has macro substitution,
+can execute (or source) other shell scripts, and can inspect its
+environment.
+
+
+
+Paul Eggert elaborates more:
+
+
+
+
+
+With Autoconf, installers need not assume that Imake itself is already
+installed and working well. This may not seem like much of an advantage
+to people who are accustomed to Imake. But on many hosts Imake is not
+installed or the default installation is not working well, and requiring
+Imake to install a package hinders the acceptance of that package on
+those hosts. For example, the Imake template and configuration files
+might not be installed properly on a host, or the Imake build procedure
+might wrongly assume that all source files are in one big directory
+tree, or the Imake configuration might assume one compiler whereas the
+package or the installer needs to use another, or there might be a
+version mismatch between the Imake expected by the package and the Imake
+supported by the host. These problems are much rarer with Autoconf,
+where each package comes with its own independent configuration
+processor.
+
+
+
+Also, Imake often suffers from unexpected interactions between
+make and the installer's C preprocessor. The fundamental problem
+here is that the C preprocessor was designed to preprocess C programs,
+not `Makefile's. This is much less of a problem with Autoconf,
+which uses the general-purpose preprocessor m4, and where the
+package's author (rather than the installer) does the preprocessing in a
+standard way.
+
+
+
+Finally, Mark Eichin notes:
+
+
+
+
+
+Imake isn't all that extensible, either. In order to add new features to
+Imake, you need to provide your own project template, and duplicate most
+of the features of the existing one. This means that for a sophisticated
+project, using the vendor-provided Imake templates fails to provide any
+leverage--since they don't cover anything that your own project needs
+(unless it is an X11 program).
+
+
+
+On the other side, though:
+
+
+
+The one advantage that Imake has over @command{configure}:
+`Imakefile's tend to be much shorter (likewise, less redundant)
+than `Makefile.in's. There is a fix to this, however--at least
+for the Kerberos V5 tree, we've modified things to call in common
+`post.in' and `pre.in'`Makefile' fragments for the
+entire tree. This means that a lot of common things don't have to be
+duplicated, even though they normally are in @command{configure} setups.
+
+You may be wondering, Why was Autoconf originally written? How did it
+get into its present form? (Why does it look like gorilla spit?) If
+you're not wondering, then this chapter contains no information useful
+to you, and you might as well skip it. If you are wondering,
+then let there be light...
+
+
+
+
+
+In June 1991 I was maintaining many of the GNU utilities for the
+Free Software Foundation. As they were ported to more platforms and
+more programs were added, the number of @option{-D} options that users
+had to select in the `Makefile' (around 20) became burdensome.
+Especially for me--I had to test each new release on a bunch of
+different systems. So I wrote a little shell script to guess some of
+the correct settings for the fileutils package, and released it as part
+of fileutils 2.0. That @command{configure} script worked well enough that
+the next month I adapted it (by hand) to create similar @command{configure}
+scripts for several other GNU utilities packages. Brian Berliner
+also adapted one of my scripts for his CVS revision control system.
+
+
+
+Later that summer, I learned that Richard Stallman and Richard Pixley
+were developing similar scripts to use in the GNU compiler tools;
+so I adapted my @command{configure} scripts to support their evolving
+interface: using the file name `Makefile.in' as the templates;
+adding `+srcdir', the first option (of many); and creating
+`config.status' files.
+
+
+
+
+
+As I got feedback from users, I incorporated many improvements, using
+Emacs to search and replace, cut and paste, similar changes in each of
+the scripts. As I adapted more GNU utilities packages to use
+@command{configure} scripts, updating them all by hand became impractical.
+Rich Murphey, the maintainer of the GNU graphics utilities, sent me
+mail saying that the @command{configure} scripts were great, and asking if
+I had a tool for generating them that I could send him. No, I thought,
+but I should! So I started to work out how to generate them. And the
+journey from the slavery of hand-written @command{configure} scripts to the
+abundance and ease of Autoconf began.
+
+
+
+Cygnus @command{configure}, which was being developed at around that time,
+is table driven; it is meant to deal mainly with a discrete number of
+system types with a small number of mainly unguessable features (such as
+details of the object file format). The automatic configuration system
+that Brian Fox had developed for Bash takes a similar approach. For
+general use, it seems to me a hopeless cause to try to maintain an
+up-to-date database of which features each variant of each operating
+system has. It's easier and more reliable to check for most features on
+the fly--especially on hybrid systems that people have hacked on
+locally or that have patches from vendors installed.
+
+
+
+I considered using an architecture similar to that of Cygnus
+@command{configure}, where there is a single @command{configure} script that
+reads pieces of `configure.in' when run. But I didn't want to have
+to distribute all of the feature tests with every package, so I settled
+on having a different @command{configure} made from each
+`configure.in' by a preprocessor. That approach also offered more
+control and flexibility.
+
+
+
+I looked briefly into using the Metaconfig package, by Larry Wall,
+Harlan Stenn, and Raphael Manfredi, but I decided not to for several
+reasons. The @command{Configure} scripts it produces are interactive,
+which I find quite inconvenient; I didn't like the ways it checked for
+some features (such as library functions); I didn't know that it was
+still being maintained, and the @command{Configure} scripts I had
+seen didn't work on many modern systems (such as System V R4 and NeXT);
+it wasn't very flexible in what it could do in response to a feature's
+presence or absence; I found it confusing to learn; and it was too big
+and complex for my needs (I didn't realize then how much Autoconf would
+eventually have to grow).
+
+
+
+I considered using Perl to generate my style of @command{configure}
+scripts, but decided that M4 was better suited to the job of simple
+textual substitutions: it gets in the way less, because output is
+implicit. Plus, everyone already has it. (Initially I didn't rely on
+the GNU extensions to M4.) Also, some of my friends at the
+University of Maryland had recently been putting M4 front ends on
+several programs, including tvtwm, and I was interested in trying
+out a new language.
+
+
+
+
+
+Since my @command{configure} scripts determine the system's capabilities
+automatically, with no interactive user intervention, I decided to call
+the program that generates them Autoconfig. But with a version number
+tacked on, that name would be too long for old UNIX file systems,
+so I shortened it to Autoconf.
+
+
+
+In the fall of 1991 I called together a group of fellow questers after
+the Holy Grail of portability (er, that is, alpha testers) to give me
+feedback as I encapsulated pieces of my handwritten scripts in M4 macros
+and continued to add features and improve the techniques used in the
+checks. Prominent among the testers were Fran@,cois Pinard, who came up
+with the idea of making an `autoconf' shell script to run m4
+and check for unresolved macro calls; Richard Pixley, who suggested
+running the compiler instead of searching the file system to find
+include files and symbols, for more accurate results; Karl Berry, who
+got Autoconf to configure TeX and added the macro index to the
+documentation; and Ian Lance Taylor, who added support for creating a C
+header file as an alternative to putting @option{-D} options in a
+`Makefile', so he could use Autoconf for his UUCP package.
+The alpha testers cheerfully adjusted their files again and again as the
+names and calling conventions of the Autoconf macros changed from
+release to release. They all contributed many specific checks, great
+ideas, and bug fixes.
+
+
+
+
+
+In July 1992, after months of alpha testing, I released Autoconf 1.0,
+and converted many GNU packages to use it. I was surprised by how
+positive the reaction to it was. More people started using it than I
+could keep track of, including people working on software that wasn't
+part of the GNU Project (such as TCL, FSP, and Kerberos V5).
+Autoconf continued to improve rapidly, as many people using the
+@command{configure} scripts reported problems they encountered.
+
+
+
+Autoconf turned out to be a good torture test for M4 implementations.
+UNIX m4 started to dump core because of the length of the
+macros that Autoconf defined, and several bugs showed up in GNU
+m4 as well. Eventually, we realized that we needed to use some
+features that only GNU M4 has. 4.3BSD m4, in
+particular, has an impoverished set of builtin macros; the System V
+version is better, but still doesn't provide everything we need.
+
+
+
+More development occurred as people put Autoconf under more stresses
+(and to uses I hadn't anticipated). Karl Berry added checks for X11.
+david zuhn contributed C++ support. Fran@,cois Pinard made it diagnose
+invalid arguments. Jim Blandy bravely coerced it into configuring
+GNU Emacs, laying the groundwork for several later improvements.
+Roland McGrath got it to configure the GNU C Library, wrote the
+@command{autoheader} script to automate the creation of C header file
+templates, and added a @option{--verbose} option to @command{configure}.
+Noah Friedman added the @option{--autoconf-dir} option and
+AC_MACRODIR environment variable. (He also coined the term
+autoconfiscate to mean "adapt a software package to use
+Autoconf".) Roland and Noah improved the quoting protection in
+AC_DEFINE and fixed many bugs, especially when I got sick of
+dealing with portability problems from February through June, 1993.
+
+
+
+
+
+A long wish list for major features had accumulated, and the effect of
+several years of patching by various people had left some residual
+cruft. In April 1994, while working for Cygnus Support, I began a major
+revision of Autoconf. I added most of the features of the Cygnus
+@command{configure} that Autoconf had lacked, largely by adapting the
+relevant parts of Cygnus @command{configure} with the help of david zuhn
+and Ken Raeburn. These features include support for using
+`config.sub', `config.guess', @option{--host}, and
+@option{--target}; making links to files; and running @command{configure}
+scripts in subdirectories. Adding these features enabled Ken to convert
+GNU as, and Rob Savoye to convert DejaGNU, to using
+Autoconf.
+
+
+
+I added more features in response to other peoples' requests. Many
+people had asked for @command{configure} scripts to share the results of
+the checks between runs, because (particularly when configuring a large
+source tree, like Cygnus does) they were frustratingly slow. Mike
+Haertel suggested adding site-specific initialization scripts. People
+distributing software that had to unpack on MS-DOS asked for a way to
+override the `.in' extension on the file names, which produced file
+names like `config.h.in' containing two dots. Jim Avera did an
+extensive examination of the problems with quoting in AC_DEFINE
+and AC_SUBST; his insights led to significant improvements.
+Richard Stallman asked that compiler output be sent to `config.log'
+instead of `/dev/null', to help people debug the Emacs
+@command{configure} script.
+
+
+
+I made some other changes because of my dissatisfaction with the quality
+of the program. I made the messages showing results of the checks less
+ambiguous, always printing a result. I regularized the names of the
+macros and cleaned up coding style inconsistencies. I added some
+auxiliary utilities that I had developed to help convert source code
+packages to use Autoconf. With the help of Fran@,cois Pinard, I made
+the macros not interrupt each others' messages. (That feature revealed
+some performance bottlenecks in GNU m4, which he hastily
+corrected!) I reorganized the documentation around problems people want
+to solve. And I began a test suite, because experience had shown that
+Autoconf has a pronounced tendency to regress when we change it.
+
+
+
+Again, several alpha testers gave invaluable feedback, especially
+Fran@,cois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
+and Mark Eichin.
+
+
+
+Finally, version 2.0 was ready. And there was much rejoicing. (And I
+have free time again. I think. Yeah, right.)
+
+
+
+
+
+Copyright (C) 2000 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+
+
+
+
+
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document free in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially. Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of "copyleft", which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+
+
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The "Document", below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as "you".
+
+A "Modified Version" of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A "Secondary Section" is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The "Invariant Sections" are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+The "Cover Texts" are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+A "Transparent" copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not "Transparent" is called "Opaque".
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format,
+@acronym{SGML} or @acronym{XML} using a publicly available
+@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
+for human modification. Opaque formats include PostScript,
+@acronym{PDF}, proprietary formats that can be read and edited only by
+proprietary word processors, @acronym{SGML} or @acronym{XML} for which
+the @acronym{DTD} and/or processing tools are not generally available,
+and the machine-generated @acronym{HTML} produced by some word
+processors for output purposes only.
+
+The "Title Page" means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, "Title Page" means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+
+
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+
+
+COPYING IN QUANTITY
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+
+
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+
+
+
+
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+
+
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has less than five).
+
+
+
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+
+
+Preserve all the copyright notices of the Document.
+
+
+
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+
+
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+
+
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+
+
+Include an unaltered copy of this License.
+
+
+
+Preserve the section entitled "History", and its title, and add to
+it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section entitled "History" in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+
+
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the "History" section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+
+
+In any section entitled "Acknowledgments" or "Dedications",
+preserve the section's title, and preserve in the section all the
+substance and tone of each of the contributor acknowledgments
+and/or dedications given therein.
+
+
+
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
+
+
+Delete any section entitled "Endorsements". Such a section
+may not be included in the Modified Version.
+
+
+
+Do not retitle any existing section as "Endorsements"
+or to conflict in title with any Invariant Section.
+
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled "Endorsements", provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+
+
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled "History"
+in the various original documents, forming one section entitled
+"History"; likewise combine any sections entitled "Acknowledgments",
+and any sections entitled "Dedications". You must delete all sections
+entitled "Endorsements."
+
+
+
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+
+
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an "aggregate", and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
+
+
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
+
+
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+
+
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+http://www.gnu.org/copyleft/.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+
+
+
+ Copyright (C) yearyour name.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1
+ or any later version published by the Free Software Foundation;
+ with the Invariant Sections being list their titles, with the
+ Front-Cover Texts being list, and with the Back-Cover Texts being list.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
+
+
+
+If you have no Invariant Sections, write "with no Invariant Sections"
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write "no Front-Cover Texts" instead of
+"Front-Cover Texts being list"; likewise for Back-Cover Texts.
+
+
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+
+
+
+
+This is an alphabetical list of the variables that Autoconf can
+substitute into files that it creates, typically one or more
+`Makefile's. See section Setting Output Variables, for more information
+on how this is done.
+
+
+
+This is an alphabetical list of the C preprocessor symbols that the
+Autoconf macros define. To work with Autoconf, C source code needs to
+use these names in #if directives.
+
+
+
+This is an alphabetical list of the M4, M4sugar, and M4sh macros. To
+make the list easier to use, the macros are listed without their
+preceding `m4_' or `AS_'.
+
+
+
+Bison is a general-purpose parser generator that converts a
+grammar description for an LALR(1) context-free grammar into a C
+program to parse that grammar. Once you are proficient with Bison,
+you may use it to develop a wide range of language parsers, from those
+used in simple desk calculators to complex programming languages.
+
+
+
+Bison is upward compatible with Yacc: all properly-written Yacc grammars
+ought to work with Bison with no change. Anyone familiar with Yacc
+should be able to use Bison with little trouble. You need to be fluent in
+C programming in order to use Bison or to understand this manual.
+
+
+
+We begin with tutorial chapters that explain the basic concepts of using
+Bison and show three explained examples, each building on the last. If you
+don't know Bison or Yacc, start by reading these chapters. Reference
+chapters follow which describe specific aspects of Bison in detail.
+
+
+
+Bison was written primarily by Robert Corbett; Richard Stallman made it
+Yacc-compatible. Wilfred Hansen of Carnegie Mellon University added
+multi-character string literals and other features.
+
+
+
+This edition corresponds to version 1.30 of Bison.
+
+
+
+
+
+As of Bison version 1.24, we have changed the distribution terms for
+yyparse to permit using Bison's output in nonfree programs.
+Formerly, Bison parsers could be used only in programs that were free
+software.
+
+
+
+The other GNU programming tools, such as the GNU C compiler, have never
+had such a requirement. They could always be used for nonfree
+software. The reason Bison was different was not due to a special
+policy decision; it resulted from applying the usual General Public
+License to all of the Bison source code.
+
+
+
+The output of the Bison utility--the Bison parser file--contains a
+verbatim copy of a sizable piece of Bison, which is the code for the
+yyparse function. (The actions from your grammar are inserted
+into this function at one point, but the rest of the function is not
+changed.) When we applied the GPL terms to the code for yyparse,
+the effect was to restrict the use of Bison output to free software.
+
+
+
+We didn't change the terms because of sympathy for people who want to
+make software proprietary. Software should be free. But we
+concluded that limiting Bison's use to free software was doing little to
+encourage people to make other software free. So we decided to make the
+practical conditions for using Bison match the practical conditions for
+using the other GNU tools.
+
+
+
+
+
+Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+ The licenses for most software are designed to take away your
+freedom to share and change it. By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users. This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it. (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.) You can apply it to
+your programs, too.
+
+
+
+ When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+
+
+ To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+
+
+ For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have. You must make sure that they, too, receive or can get the
+source code. And you must show them these terms so they know their
+rights.
+
+
+
+ We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+
+
+ Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software. If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+
+
+ Finally, any free program is threatened constantly by software
+patents. We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary. To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+
+
+ The precise terms and conditions for copying, distribution and
+modification follow.
+
+
+
+
+
+
+This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License. The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language. (Hereinafter, translation is included without limitation in
+the term "modification".) Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope. The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+
+
+You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+
+
+You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+
+
+
+
+You must cause the modified files to carry prominent notices
+stating that you changed the files and the date of any change.
+
+
+
+You must cause any work that you distribute or publish, that in
+whole or in part contains or is derived from the Program or any
+part thereof, to be licensed as a whole at no charge to all third
+parties under the terms of this License.
+
+
+
+If the modified program normally reads commands interactively
+when run, you must cause it, when started running for such
+interactive use in the most ordinary way, to print or display an
+announcement including an appropriate copyright notice and a
+notice that there is no warranty (or else, saying that you provide
+a warranty) and that users may redistribute the program under
+these conditions, and telling the user how to view a copy of this
+License. (Exception: if the Program itself is interactive but
+does not normally print such an announcement, your work based on
+the Program is not required to print an announcement.)
+
+
+These requirements apply to the modified work as a whole. If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works. But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+
+
+You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+
+
+
+
+Accompany it with the complete corresponding machine-readable
+source code, which must be distributed under the terms of Sections
+1 and 2 above on a medium customarily used for software interchange; or,
+
+
+
+Accompany it with a written offer, valid for at least three
+years, to give any third party, for a charge no more than your
+cost of physically performing source distribution, a complete
+machine-readable copy of the corresponding source code, to be
+distributed under the terms of Sections 1 and 2 above on a medium
+customarily used for software interchange; or,
+
+
+
+Accompany it with the information you received as to the offer
+to distribute corresponding source code. (This alternative is
+allowed only for noncommercial distribution and only if you
+received the program in object code or executable form with such
+an offer, in accord with Subsection b above.)
+
+
+The source code for a work means the preferred form of the work for
+making modifications to it. For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable. However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+
+
+You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+
+
+You are not required to accept this License, since you have not
+signed it. However, nothing else grants you permission to modify or
+distribute the Program or its derivative works. These actions are
+prohibited by law if you do not accept this License. Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+
+
+Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions. You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+
+
+If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all. For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices. Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+
+
+If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded. In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+
+
+The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time. Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation. If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+
+
+If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission. For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this. Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+
+
+
NO WARRANTY
+
+
+
+BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+ If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+
+
+ To do so, attach the following notices to the program. It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+
+
+
+one line to give the program's name and a brief idea of what it does.
+Copyright (C) yyyyname of author
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+
+
+
+Also add information on how to contact you by electronic and paper mail.
+
+
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+
+
+
+Gnomovision version 69, Copyright (C) 19yyname of author
+Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+This is free software, and you are welcome to redistribute it
+under certain conditions; type `show c' for details.
+
+
+
+The hypothetical commands `show w' and `show c' should show
+the appropriate parts of the General Public License. Of course, the
+commands you use may be called something other than `show w' and
+`show c'; they could even be mouse-clicks or menu items--whatever
+suits your program.
+
+
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary. Here is a sample; alter the names:
+
+
+
+
+Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+`Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+signature of Ty Coon, 1 April 1989
+Ty Coon, President of Vice
+
+
+
+This General Public License does not permit incorporating your program into
+proprietary programs. If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library. If this is what you want to do, use the GNU Library General
+Public License instead of this License.
+
+
+
+
+
+This chapter introduces many of the basic concepts without which the
+details of Bison will not make sense. If you do not already know how to
+use Bison or Yacc, we suggest you start by reading this chapter carefully.
+
+
+
+
+
+
+
+In order for Bison to parse a language, it must be described by a
+context-free grammar. This means that you specify one or more
+syntactic groupings and give rules for constructing them from their
+parts. For example, in the C language, one kind of grouping is called an
+`expression'. One rule for making an expression might be, "An expression
+can be made of a minus sign and another expression". Another would be,
+"An expression can be an integer". As you can see, rules are often
+recursive, but there must be at least one rule which leads out of the
+recursion.
+
+
+
+
+
+The most common formal system for presenting such rules for humans to read
+is Backus-Naur Form or "BNF", which was developed in order to
+specify the language Algol 60. Any grammar expressed in BNF is a
+context-free grammar. The input to Bison is essentially machine-readable
+BNF.
+
+
+
+Not all context-free languages can be handled by Bison, only those
+that are LALR(1). In brief, this means that it must be possible to
+tell how to parse any portion of an input string with just a single
+token of look-ahead. Strictly speaking, that is a description of an
+LR(1) grammar, and LALR(1) involves additional restrictions that are
+hard to explain simply; but it is rare in actual practice to find an
+LR(1) grammar that fails to be LALR(1). See section Mysterious Reduce/Reduce Conflicts, for more information on this.
+
+
+
+
+
+
+
+In the formal grammatical rules for a language, each kind of syntactic unit
+or grouping is named by a symbol. Those which are built by grouping
+smaller constructs according to grammatical rules are called
+nonterminal symbols; those which can't be subdivided are called
+terminal symbols or token types. We call a piece of input
+corresponding to a single terminal symbol a token, and a piece
+corresponding to a single nonterminal symbol a grouping.
+
+
+We can use the C language as an example of what symbols, terminal and
+nonterminal, mean. The tokens of C are identifiers, constants (numeric and
+string), and the various keywords, arithmetic operators and punctuation
+marks. So the terminal symbols of a grammar for C include `identifier',
+`number', `string', plus one symbol for each keyword, operator or
+punctuation mark: `if', `return', `const', `static', `int', `char',
+`plus-sign', `open-brace', `close-brace', `comma' and many more. (These
+tokens can be subdivided into characters, but that is a matter of
+lexicography, not grammar.)
+
+
+
+Here is a simple C function subdivided into tokens:
+
+
+
+
+The syntactic groupings of C include the expression, the statement, the
+declaration, and the function definition. These are represented in the
+grammar of C by nonterminal symbols `expression', `statement',
+`declaration' and `function definition'. The full grammar uses dozens of
+additional language constructs, each with its own nonterminal symbol, in
+order to express the meanings of these four. The example above is a
+function definition; it contains one declaration, and one statement. In
+the statement, each `x' is an expression and so is `x * x'.
+
+
+
+Each nonterminal symbol must have grammatical rules showing how it is made
+out of simpler constructs. For example, one kind of C statement is the
+return statement; this would be described with a grammar rule which
+reads informally as follows:
+
+
+
+
+
+A `statement' can be made of a `return' keyword, an `expression' and a
+`semicolon'.
+
+
+
+There would be many other rules for `statement', one for each kind of
+statement in C.
+
+
+
+
+One nonterminal symbol must be distinguished as the special one which
+defines a complete utterance in the language. It is called the start
+symbol. In a compiler, this means a complete input program. In the C
+language, the nonterminal symbol `sequence of definitions and declarations'
+plays this role.
+
+
+
+For example, `1 + 2' is a valid C expression--a valid part of a C
+program--but it is not valid as an entire C program. In the
+context-free grammar of C, this follows from the fact that `expression' is
+not the start symbol.
+
+
+
+The Bison parser reads a sequence of tokens as its input, and groups the
+tokens using the grammar rules. If the input is valid, the end result is
+that the entire token sequence reduces to a single grouping whose symbol is
+the grammar's start symbol. If we use a grammar for C, the entire input
+must be a `sequence of definitions and declarations'. If not, the parser
+reports a syntax error.
+
+
+
+
+
+A formal grammar is a mathematical construct. To define the language
+for Bison, you must write a file expressing the grammar in Bison syntax:
+a Bison grammar file. See section Bison Grammar Files.
+
+
+
+A nonterminal symbol in the formal grammar is represented in Bison input
+as an identifier, like an identifier in C. By convention, it should be
+in lower case, such as expr, stmt or declaration.
+
+
+
+The Bison representation for a terminal symbol is also called a token
+type. Token types as well can be represented as C-like identifiers. By
+convention, these identifiers should be upper case to distinguish them from
+nonterminals: for example, INTEGER, IDENTIFIER, IF or
+RETURN. A terminal symbol that stands for a particular keyword in
+the language should be named after that keyword converted to upper case.
+The terminal symbol error is reserved for error recovery.
+See section Symbols, Terminal and Nonterminal.
+
+
+
+A terminal symbol can also be represented as a character literal, just like
+a C character constant. You should do this whenever a token is just a
+single character (parenthesis, plus-sign, etc.): use that same character in
+a literal as the terminal symbol for that token.
+
+
+
+A third way to represent a terminal symbol is with a C string constant
+containing several characters. See section Symbols, Terminal and Nonterminal, for more information.
+
+
+
+The grammar rules also have an expression in Bison syntax. For example,
+here is the Bison rule for a C return statement. The semicolon in
+quotes is a literal character token, representing part of the C syntax for
+the statement; the naked semicolon, and the colon, are Bison punctuation
+used in every rule.
+
+
+
+
+A formal grammar selects tokens only by their classifications: for example,
+if a rule mentions the terminal symbol `integer constant', it means that
+any integer constant is grammatically valid in that position. The
+precise value of the constant is irrelevant to how to parse the input: if
+`x+4' is grammatical then `x+1' or `x+3989' is equally
+grammatical.
+
+
+But the precise value is very important for what the input means once it is
+parsed. A compiler is useless if it fails to distinguish between 4, 1 and
+3989 as constants in the program! Therefore, each token in a Bison grammar
+has both a token type and a semantic value. See section Defining Language Semantics,
+for details.
+
+
+
+The token type is a terminal symbol defined in the grammar, such as
+INTEGER, IDENTIFIER or ','. It tells everything
+you need to know to decide where the token may validly appear and how to
+group it with other tokens. The grammar rules know nothing about tokens
+except their types.
+
+
+The semantic value has all the rest of the information about the
+meaning of the token, such as the value of an integer, or the name of an
+identifier. (A token such as ',' which is just punctuation doesn't
+need to have any semantic value.)
+
+
+
+For example, an input token might be classified as token type
+INTEGER and have the semantic value 4. Another input token might
+have the same token type INTEGER but value 3989. When a grammar
+rule says that INTEGER is allowed, either of these tokens is
+acceptable because each is an INTEGER. When the parser accepts the
+token, it keeps track of the token's semantic value.
+
+
+
+Each grouping can also have a semantic value as well as its nonterminal
+symbol. For example, in a calculator, an expression typically has a
+semantic value that is a number. In a compiler for a programming
+language, an expression typically has a semantic value that is a tree
+structure describing the meaning of the expression.
+
+
+
+
+
+In order to be useful, a program must do more than parse input; it must
+also produce some output based on the input. In a Bison grammar, a grammar
+rule can have an action made up of C statements. Each time the
+parser recognizes a match for that rule, the action is executed.
+See section Actions.
+
+
+
+Most of the time, the purpose of an action is to compute the semantic value
+of the whole construct from the semantic values of its parts. For example,
+suppose we have a rule which says an expression can be the sum of two
+expressions. When the parser recognizes such a sum, each of the
+subexpressions has a semantic value which describes how it was built up.
+The action for this rule should create a similar sort of value for the
+newly recognized larger expression.
+
+
+
+For example, here is a rule that says an expression can be the sum of
+two subexpressions:
+
+
+
+
+expr: expr '+' expr { $$ = $1 + $3; }
+ ;
+
+
+
+The action says how to produce the semantic value of the sum expression
+from the values of the two subexpressions.
+
+
+
+
+
+Many applications, like interpreters or compilers, have to produce verbose
+and useful error messages. To achieve this, one must be able to keep track of
+the textual position, or location, of each syntactic construct.
+Bison provides a mechanism for handling these locations.
+
+
+
+Each token has a semantic value. In a similar fashion, each token has an
+associated location, but the type of locations is the same for all tokens and
+groupings. Moreover, the output parser is equipped with a default data
+structure for storing locations (see section Tracking Locations, for more details).
+
+
+
+Like semantic values, locations can be reached in actions using a dedicated
+set of constructs. In the example above, the location of the whole grouping
+is @$, while the locations of the subexpressions are @1 and
+@3.
+
+
+
+When a rule is matched, a default action is used to compute the semantic value
+of its left hand side (see section Actions). In the same way, another default
+action is used for locations. However, the action for locations is general
+enough for most cases, meaning there is usually no need to describe for each
+rule how @$ should be formed. When building a new location for a given
+grouping, the default behavior of the output parser is to take the beginning
+of the first symbol, and the end of the last symbol.
+
+
+
+
+
+When you run Bison, you give it a Bison grammar file as input. The output
+is a C source file that parses the language described by the grammar.
+This file is called a Bison parser. Keep in mind that the Bison
+utility and the Bison parser are two distinct programs: the Bison utility
+is a program whose output is the Bison parser that becomes part of your
+program.
+
+
+
+The job of the Bison parser is to group tokens into groupings according to
+the grammar rules--for example, to build identifiers and operators into
+expressions. As it does this, it runs the actions for the grammar rules it
+uses.
+
+
+
+The tokens come from a function called the lexical analyzer that you
+must supply in some fashion (such as by writing it in C). The Bison parser
+calls the lexical analyzer each time it wants a new token. It doesn't know
+what is "inside" the tokens (though their semantic values may reflect
+this). Typically the lexical analyzer makes the tokens by parsing
+characters of text, but Bison does not depend on this. See section The Lexical Analyzer Function yylex.
+
+
+
+The Bison parser file is C code which defines a function named
+yyparse which implements that grammar. This function does not make
+a complete C program: you must supply some additional functions. One is
+the lexical analyzer. Another is an error-reporting function which the
+parser calls to report an error. In addition, a complete C program must
+start with a function called main; you have to provide this, and
+arrange for it to call yyparse or the parser will never run.
+See section Parser C-Language Interface.
+
+
+
+Aside from the token type names and the symbols in the actions you
+write, all variable and function names used in the Bison parser file
+begin with `yy' or `YY'. This includes interface functions
+such as the lexical analyzer function yylex, the error reporting
+function yyerror and the parser function yyparse itself.
+This also includes numerous identifiers used for internal purposes.
+Therefore, you should avoid using C identifiers starting with `yy'
+or `YY' in the Bison grammar file except for the ones defined in
+this manual.
+
+
+
+
+
+The actual language-design process using Bison, from grammar specification
+to a working compiler or interpreter, has these parts:
+
+
+
+
+
+
+Formally specify the grammar in a form recognized by Bison
+(see section Bison Grammar Files). For each grammatical rule in the language,
+describe the action that is to be taken when an instance of that rule
+is recognized. The action is described by a sequence of C statements.
+
+
+
+Write a lexical analyzer to process input and pass tokens to the
+parser. The lexical analyzer may be written by hand in C
+(see section The Lexical Analyzer Function yylex). It could also be produced using Lex, but the use
+of Lex is not discussed in this manual.
+
+
+
+Write a controlling function that calls the Bison-produced parser.
+
+
+
+Write error-reporting routines.
+
+
+
+To turn this source code as written into a runnable program, you
+must follow these steps:
+
+
+
+
+
+
+Run Bison on the grammar to produce the parser.
+
+
+
+Compile the code output by Bison, as well as any other source files.
+
+
+
+Link the object files to produce the finished product.
+
+The `%%', `%{' and `%}' are punctuation that appears
+in every Bison grammar file to separate the sections.
+
+
+
+The C declarations may define types and variables used in the actions.
+You can also use preprocessor commands to define macros used there, and use
+#include to include header files that do any of these things.
+
+
+
+The Bison declarations declare the names of the terminal and nonterminal
+symbols, and may also describe operator precedence and the data types of
+semantic values of various symbols.
+
+
+
+The grammar rules define how to construct each nonterminal symbol from its
+parts.
+
+
+
+The additional C code can contain any C code you want to use. Often the
+definition of the lexical analyzer yylex goes here, plus subroutines
+called by the actions in the grammar rules. In a simple program, all the
+rest of the program can go here.
+
+
+
+
+
+Now we show and explain three sample programs written using Bison: a
+reverse polish notation calculator, an algebraic (infix) notation
+calculator, and a multi-function calculator. All three have been tested
+under BSD Unix 4.3; each produces a usable, though limited, interactive
+desk-top calculator.
+
+
+
+These examples are simple, but Bison grammars for real programming
+languages are written the same way.
+
+
+
+
+
+The first example is that of a simple double-precision reverse polish
+notation calculator (a calculator using postfix operators). This example
+provides a good starting point, since operator precedence is not an issue.
+The second example will illustrate how operator precedence is handled.
+
+
+
+The source code for this calculator is named `rpcalc.y'. The
+`.y' extension is a convention used for Bison input files.
+
+
+
+
+
+The C declarations section (see section The C Declarations Section) contains two
+preprocessor directives.
+
+
+
+The #define directive defines the macro YYSTYPE, thus
+specifying the C data type for semantic values of both tokens and groupings
+(see section Data Types of Semantic Values). The Bison parser will use whatever type
+YYSTYPE is defined as; if you don't define it, int is the
+default. Because we specify double, each token and each expression
+has an associated value, which is a floating point number.
+
+
+
+The #include directive is used to declare the exponentiation
+function pow.
+
+
+
+The second section, Bison declarations, provides information to Bison about
+the token types (see section The Bison Declarations Section). Each terminal symbol that is
+not a single-character literal must be declared here. (Single-character
+literals normally don't need to be declared.) In this example, all the
+arithmetic operators are designated by single-character literals, so the
+only terminal symbol that needs to be declared is NUM, the token
+type for numeric constants.
+
+
+
+
+
+The groupings of the rpcalc "language" defined here are the expression
+(given the name exp), the line of input (line), and the
+complete input transcript (input). Each of these nonterminal
+symbols has several alternate rules, joined by the `|' punctuator
+which is read as "or". The following sections explain what these rules
+mean.
+
+
+
+The semantics of the language is determined by the actions taken when a
+grouping is recognized. The actions are the C code that appears inside
+braces. See section Actions.
+
+
+
+You must specify these actions in C, but Bison provides the means for
+passing semantic values between the rules. In each action, the
+pseudo-variable $$ stands for the semantic value for the grouping
+that the rule is going to construct. Assigning a value to $$ is the
+main job of most actions. The semantic values of the components of the
+rule are referred to as $1, $2, and so on.
+
+
+
+
+
+This definition reads as follows: "A complete input is either an empty
+string, or a complete input followed by an input line". Notice that
+"complete input" is defined in terms of itself. This definition is said
+to be left recursive since input appears always as the
+leftmost symbol in the sequence. See section Recursive Rules.
+
+
+
+The first alternative is empty because there are no symbols between the
+colon and the first `|'; this means that input can match an
+empty string of input (no tokens). We write the rules this way because it
+is legitimate to type Ctrl-d right after you start the calculator.
+It's conventional to put an empty alternative first and write the comment
+`/* empty */' in it.
+
+
+
+The second alternate rule (input line) handles all nontrivial input.
+It means, "After reading any number of lines, read one more line if
+possible." The left recursion makes this rule into a loop. Since the
+first alternative matches empty input, the loop can be executed zero or
+more times.
+
+
+
+The parser function yyparse continues to process input until a
+grammatical error is seen or the lexical analyzer says there are no more
+input tokens; we will arrange for the latter to happen at end of file.
+
+
+
+
+
+The first alternative is a token which is a newline character; this means
+that rpcalc accepts a blank line (and ignores it, since there is no
+action). The second alternative is an expression followed by a newline.
+This is the alternative that makes rpcalc useful. The semantic value of
+the exp grouping is the value of $1 because the exp in
+question is the first symbol in the alternative. The action prints this
+value, which is the result of the computation the user asked for.
+
+
+
+This action is unusual because it does not assign a value to $$. As
+a consequence, the semantic value associated with the line is
+uninitialized (its value will be unpredictable). This would be a bug if
+that value were ever used, but we don't use it: once rpcalc has printed the
+value of the user's input line, that value is no longer needed.
+
+
+
+
+
+The exp grouping has several rules, one for each kind of expression.
+The first rule handles the simplest expressions: those that are just numbers.
+The second handles an addition-expression, which looks like two expressions
+followed by a plus-sign. The third handles subtraction, and so on.
+
+
+
+
+Most of the rules have actions that compute the value of the expression in
+terms of the value of its parts. For example, in the rule for addition,
+$1 refers to the first component exp and $2 refers to
+the second one. The third component, '+', has no meaningful
+associated semantic value, but if it had one you could refer to it as
+$3. When yyparse recognizes a sum expression using this
+rule, the sum of the two subexpressions' values is produced as the value of
+the entire expression. See section Actions.
+
+
+
+You don't have to give an action for every rule. When a rule has no
+action, Bison by default copies the value of $1 into $$.
+This is what happens in the first rule (the one that uses NUM).
+
+
+
+The formatting shown here is the recommended convention, but Bison does
+not require it. You can add or change whitespace as much as you wish.
+For example, this:
+
+
+
+
+The lexical analyzer's job is low-level parsing: converting characters or
+sequences of characters into tokens. The Bison parser gets its tokens by
+calling the lexical analyzer. See section The Lexical Analyzer Function yylex.
+
+
+
+Only a simple lexical analyzer is needed for the RPN calculator. This
+lexical analyzer skips blanks and tabs, then reads in numbers as
+double and returns them as NUM tokens. Any other character
+that isn't part of a number is a separate token. Note that the token-code
+for such a single-character token is the character itself.
+
+
+
+The return value of the lexical analyzer function is a numeric code which
+represents a token type. The same text used in Bison rules to stand for
+this token type is also a C expression for the numeric code for the type.
+This works in two ways. If the token type is a character literal, then its
+numeric code is the ASCII code for that character; you can use the same
+character literal in the lexical analyzer to express the number. If the
+token type is an identifier, that identifier is defined by Bison as a C
+macro whose definition is the appropriate number. In this example,
+therefore, NUM becomes a macro for yylex to use.
+
+
+
+The semantic value of the token (if it has one) is stored into the global
+variable yylval, which is where the Bison parser will look for it.
+(The C data type of yylval is YYSTYPE, which was defined
+at the beginning of the grammar; see section Declarations for rpcalc.)
+
+
+
+A token type code of zero is returned if the end-of-file is encountered.
+(Bison recognizes any nonpositive value as indicating the end of the
+input.)
+
+
+
+Here is the code for the lexical analyzer:
+
+
+
+
+/* Lexical analyzer returns a double floating point
+ number on the stack and the token NUM, or the ASCII
+ character read if not a number. Skips all blanks
+ and tabs, returns 0 for EOF. */
+
+#include <ctype.h>
+
+int
+yylex (void)
+{
+ int c;
+
+ /* skip white space */
+ while ((c = getchar ()) == ' ' || c == '\t')
+ ;
+ /* process numbers */
+ if (c == '.' || isdigit (c))
+ {
+ ungetc (c, stdin);
+ scanf ("%lf", &yylval);
+ return NUM;
+ }
+ /* return end-of-file */
+ if (c == EOF)
+ return 0;
+ /* return single chars */
+ return c;
+}
+
+In keeping with the spirit of this example, the controlling function is
+kept to the bare minimum. The only requirement is that it call
+yyparse to start the process of parsing.
+
+
+
+
+When yyparse detects a syntax error, it calls the error reporting
+function yyerror to print an error message (usually but not
+always "parse error"). It is up to the programmer to supply
+yyerror (see section Parser C-Language Interface), so
+here is the definition we will use:
+
+
+
+
+#include <stdio.h>
+
+void
+yyerror (const char *s) /* Called by yyparse on error */
+{
+ printf ("%s\n", s);
+}
+
+
+
+After yyerror returns, the Bison parser may recover from the error
+and continue parsing if the grammar contains a suitable error rule
+(see section Error Recovery). Otherwise, yyparse returns nonzero. We
+have not written any error rules in this example, so any invalid input will
+cause the calculator program to exit. This is not clean behavior for a
+real calculator, but it is adequate for the first example.
+
+
+
+
+
+Before running Bison to produce a parser, we need to decide how to
+arrange all the source code in one or more source files. For such a
+simple example, the easiest thing is to put everything in one file. The
+definitions of yylex, yyerror and main go at the
+end, in the "additional C code" section of the file (see section The Overall Layout of a Bison Grammar).
+
+
+
+For a large project, you would probably have several source files, and use
+make to arrange to recompile them.
+
+
+
+With all the source in a single file, you use the following command to
+convert it into a parser file:
+
+
+
+
+bison file_name.y
+
+
+
+In this example the file was called `rpcalc.y' (for "Reverse Polish
+CALCulator"). Bison produces a file named `file_name.tab.c',
+removing the `.y' from the original file name. The file output by
+Bison contains the source code for yyparse. The additional
+functions in the input file (yylex, yyerror and main)
+are copied verbatim to the output.
+
+
+
+
+
+Here is how to compile and run the parser file:
+
+
+
+
+# List files in current directory.
+% ls
+rpcalc.tab.c rpcalc.y
+
+# Compile the Bison parser.
+# `-lm' tells compiler to search math library for pow.
+% cc rpcalc.tab.c -lm -o rpcalc
+
+# List files again.
+% ls
+rpcalc rpcalc.tab.c rpcalc.y
+
+
+
+The file `rpcalc' now contains the executable code. Here is an
+example session using rpcalc.
+
+
+
+
+We now modify rpcalc to handle infix operators instead of postfix. Infix
+notation involves the concept of operator precedence and the need for
+parentheses nested to arbitrary depth. Here is the Bison code for
+`calc.y', an infix desk-top calculator.
+
+
+
+
+The functions yylex, yyerror and main can be the
+same as before.
+
+
+
+There are two important new features shown in this code.
+
+
+
+In the second section (Bison declarations), %left declares token
+types and says they are left-associative operators. The declarations
+%left and %right (right associativity) take the place of
+%token which is used to declare a token type name without
+associativity. (These tokens are single-character literals, which
+ordinarily don't need to be declared. We declare them here to specify
+the associativity.)
+
+
+
+Operator precedence is determined by the line ordering of the
+declarations; the higher the line number of the declaration (lower on
+the page or screen), the higher the precedence. Hence, exponentiation
+has the highest precedence, unary minus (NEG) is next, followed
+by `*' and `/', and so on. See section Operator Precedence.
+
+
+
+The other important new feature is the %prec in the grammar section
+for the unary minus operator. The %prec simply instructs Bison that
+the rule `| '-' exp' has the same precedence as NEG---in this
+case the next-to-highest. See section Context-Dependent Precedence.
+
+
+
+Up to this point, this manual has not addressed the issue of error
+recovery---how to continue parsing after the parser detects a syntax
+error. All we have handled is error reporting with yyerror.
+Recall that by default yyparse returns after calling
+yyerror. This means that an erroneous input line causes the
+calculator program to exit. Now we show how to rectify this deficiency.
+
+
+
+The Bison language itself includes the reserved word error, which
+may be included in the grammar rules. In the example below it has
+been added to one of the alternatives for line:
+
+
+
+
+This addition to the grammar allows for simple error recovery in the
+event of a parse error. If an expression that cannot be evaluated is
+read, the error will be recognized by the third rule for line,
+and parsing will continue. (The yyerror function is still called
+upon to print its message as well.) The action executes the statement
+yyerrok, a macro defined automatically by Bison; its meaning is
+that error recovery is complete (see section Error Recovery). Note the
+difference between yyerrok and yyerror; neither one is a
+misprint.
+
+
+This form of error recovery deals with syntax errors. There are other
+kinds of errors; for example, division by zero, which raises an exception
+signal that is normally fatal. A real calculator program must handle this
+signal and use longjmp to return to main and resume parsing
+input lines; it would also have to discard the rest of the current line of
+input. We won't discuss this issue further because it is not specific to
+Bison programs.
+
+
+
+
+
+This example extends the infix notation calculator with location tracking.
+This feature will be used to improve error reporting, and provide better
+error messages.
+
+
+
+For the sake of clarity, we will switch for this example to an integer
+calculator, since most of the work needed to use locations will be done
+in the lexical analyser.
+
+
+
+
+
+In the code above, there are no declarations specific to locations. Defining
+a data type for storing locations is not needed: we will use the type provided
+by default (see section Data Type of Locations), which is a four
+member structure with the following integer fields: first_line,
+first_column, last_line and last_column.
+
+
+
+
+
+Whether you choose to handle locations or not has no effect on the syntax of
+your language. Therefore, grammar rules for this example will be very close to
+those of the previous example: we will only modify them to benefit from the new
+informations we will have.
+
+
+
+Here, we will use locations to report divisions by zero, and locate the wrong
+expressions or subexpressions.
+
+
+
+
+This code shows how to reach locations inside of semantic actions, by
+using the pseudo-variables @n for rule components, and the
+pseudo-variable @$ for groupings.
+
+
+
+In this example, we never assign a value to @$, because the
+output parser can do this automatically. By default, before executing
+the C code of each action, @$ is set to range from the beginning
+of @1 to the end of @n, for a rule with n
+components.
+
+
+
+Of course, this behavior can be redefined (see section Default Action for Locations), and for very specific rules,
+@$ can be computed by hand.
+
+
+
+
+
+Until now, we relied on Bison's defaults to enable location tracking. The next
+step is to rewrite the lexical analyser, and make it able to feed the parser
+with locations of tokens, as he already does for semantic values.
+
+
+
+To do so, we must take into account every single character of the input text,
+to avoid the computed locations of being fuzzy or wrong:
+
+
+
+
+Basically, the lexical analyzer does the same processing as before: it skips
+blanks and tabs, and reads numbers or single-character tokens. In addition
+to this, it updates the yylloc global variable (of type YYLTYPE),
+where the location of tokens is stored.
+
+
+
+Now, each time this function returns a token, the parser has it's number as
+well as it's semantic value, and it's position in the text. The last needed
+change is to initialize yylloc, for example in the controlling
+function:
+
+
+
+
+Remember that computing locations is not a matter of syntax. Every character
+must be associated to a location update, whether it is in valid input, in
+comments, in literal strings, and so on...
+
+
+
+
+
+Now that the basics of Bison have been discussed, it is time to move on to
+a more advanced problem. The above calculators provided only five
+functions, `+', `-', `*', `/' and `^'. It would
+be nice to have a calculator that provides other mathematical functions such
+as sin, cos, etc.
+
+
+
+It is easy to add new operators to the infix calculator as long as they are
+only single-character literals. The lexical analyzer yylex passes
+back all nonnumber characters as tokens, so new grammar rules suffice for
+adding a new operator. But we want something more flexible: built-in
+functions whose syntax has this form:
+
+
+
+
+function_name (argument)
+
+
+
+At the same time, we will add memory to the calculator, by allowing you
+to create named variables, store values in them, and use them later.
+Here is a sample session with the multi-function calculator:
+
+
+
+
+Here are the C and Bison declarations for the multi-function calculator.
+
+
+
+
+%{
+#include <math.h> /* For math functions, cos(), sin(), etc. */
+#include "calc.h" /* Contains definition of `symrec' */
+%}
+%union {
+double val; /* For returning numbers. */
+symrec *tptr; /* For returning symbol-table pointers */
+}
+
+%token <val> NUM /* Simple double precision number */
+%token <tptr> VAR FNCT /* Variable and Function */
+%type <val> exp
+
+%right '='
+%left '-' '+'
+%left '*' '/'
+%left NEG /* Negation--unary minus */
+%right '^' /* Exponentiation */
+
+/* Grammar follows */
+
+%%
+
+
+
+The above grammar introduces only two new features of the Bison language.
+These features allow semantic values to have various data types
+(see section More Than One Value Type).
+
+
+
+The %union declaration specifies the entire list of possible types;
+this is instead of defining YYSTYPE. The allowable types are now
+double-floats (for exp and NUM) and pointers to entries in
+the symbol table. See section The Collection of Value Types.
+
+
+
+Since values can now have various types, it is necessary to associate a
+type with each grammar symbol whose semantic value is used. These symbols
+are NUM, VAR, FNCT, and exp. Their
+declarations are augmented with information about their data type (placed
+between angle brackets).
+
+
+
+The Bison construct %type is used for declaring nonterminal symbols,
+just as %token is used for declaring token types. We have not used
+%type before because nonterminal symbols are normally declared
+implicitly by the rules that define them. But exp must be declared
+explicitly so we can specify its value type. See section Nonterminal Symbols.
+
+
+
+
+
+Here are the grammar rules for the multi-function calculator.
+Most of them are copied directly from calc; three rules,
+those which mention VAR or FNCT, are new.
+
+
+
+
+The multi-function calculator requires a symbol table to keep track of the
+names and meanings of variables and functions. This doesn't affect the
+grammar rules (except for the actions) or the Bison declarations, but it
+requires some additional C functions for support.
+
+
+
+The symbol table itself consists of a linked list of records. Its
+definition, which is kept in the header `calc.h', is as follows. It
+provides for either functions or variables to be placed in the table.
+
+
+
+
+/* Fonctions type. */
+typedef double (*func_t) (double);
+
+/* Data type for links in the chain of symbols. */
+struct symrec
+{
+ char *name; /* name of symbol */
+ int type; /* type of symbol: either VAR or FNCT */
+ union
+ {
+ double var; /* value of a VAR */
+ func_t fnctptr; /* value of a FNCT */
+ } value;
+ struct symrec *next; /* link field */
+};
+
+typedef struct symrec symrec;
+
+/* The symbol table: a chain of `struct symrec'. */
+extern symrec *sym_table;
+
+symrec *putsym (const char *, func_t);
+symrec *getsym (const char *);
+
+
+
+The new version of main includes a call to init_table, a
+function that initializes the symbol table. Here it is, and
+init_table as well:
+
+
+
+
+By simply editing the initialization list and adding the necessary include
+files, you can add additional functions to the calculator.
+
+
+
+Two important functions allow look-up and installation of symbols in the
+symbol table. The function putsym is passed a name and the type
+(VAR or FNCT) of the object to be installed. The object is
+linked to the front of the list, and a pointer to the object is returned.
+The function getsym is passed the name of the symbol to look up. If
+found, a pointer to that symbol is returned; otherwise zero is returned.
+
+
+
+
+The function yylex must now recognize variables, numeric values, and
+the single-character arithmetic operators. Strings of alphanumeric
+characters with a leading non-digit are recognized as either variables or
+functions depending on what the symbol table says about them.
+
+
+
+The string is passed to getsym for look up in the symbol table. If
+the name appears in the table, a pointer to its location and its type
+(VAR or FNCT) is returned to yyparse. If it is not
+already in the table, then it is installed as a VAR using
+putsym. Again, a pointer and its type (which must be VAR) is
+returned to yyparse.
+
+
+No change is needed in the handling of numeric values and arithmetic
+operators in yylex.
+
+
+
+
+#include <ctype.h>
+
+int
+yylex (void)
+{
+ int c;
+
+ /* Ignore whitespace, get first nonwhite character. */
+ while ((c = getchar ()) == ' ' || c == '\t');
+
+ if (c == EOF)
+ return 0;
+
+ /* Char starts a number => parse the number. */
+ if (c == '.' || isdigit (c))
+ {
+ ungetc (c, stdin);
+ scanf ("%lf", &yylval.val);
+ return NUM;
+ }
+
+ /* Char starts an identifier => read the name. */
+ if (isalpha (c))
+ {
+ symrec *s;
+ static char *symbuf = 0;
+ static int length = 0;
+ int i;
+
+ /* Initially make the buffer long enough
+ for a 40-character symbol name. */
+ if (length == 0)
+ length = 40, symbuf = (char *)malloc (length + 1);
+
+ i = 0;
+ do
+ {
+ /* If buffer is full, make it bigger. */
+ if (i == length)
+ {
+ length *= 2;
+ symbuf = (char *)realloc (symbuf, length + 1);
+ }
+ /* Add this character to the buffer. */
+ symbuf[i++] = c;
+ /* Get another character. */
+ c = getchar ();
+ }
+ while (c != EOF && isalnum (c));
+
+ ungetc (c, stdin);
+ symbuf[i] = '\0';
+
+ s = getsym (symbuf);
+ if (s == 0)
+ s = putsym (symbuf, VAR);
+ yylval.tptr = s;
+ return s->type;
+ }
+
+ /* Any other character is a token by itself. */
+ return c;
+}
+
+
+
+This program is both powerful and flexible. You may easily add new
+functions, and it is a simple job to modify this code to install predefined
+variables such as pi or e as well.
+
+
+
+
+
+
+Add some new functions from `math.h' to the initialization list.
+
+
+
+Add another array that contains constants and their values. Then
+modify init_table to add these constants to the symbol table.
+It will be easiest to give the constants type VAR.
+
+
+
+Make the program report an error if the user refers to an
+uninitialized variable in any way except to store a value in it.
+
+The C declarations section contains macro definitions and
+declarations of functions and variables that are used in the actions in the
+grammar rules. These are copied to the beginning of the parser file so
+that they precede the definition of yyparse. You can use
+`#include' to get the declarations from a header file. If you don't
+need any C declarations, you may omit the `%{' and `%}'
+delimiters that bracket this section.
+
+
+
+
+
+The Bison declarations section contains declarations that define
+terminal and nonterminal symbols, specify precedence, and so on.
+In some simple grammars you may not need any declarations.
+See section Bison Declarations.
+
+
+
+
+
+The grammar rules section contains one or more Bison grammar
+rules, and nothing else. See section Syntax of Grammar Rules.
+
+
+
+There must always be at least one grammar rule, and the first
+`%%' (which precedes the grammar rules) may never be omitted even
+if it is the first thing in the file.
+
+
+
+
+
+The additional C code section is copied verbatim to the end of the
+parser file, just as the C declarations section is copied to the
+beginning. This is the most convenient place to put anything that you
+want to have in the parser file but which need not come before the
+definition of yyparse. For example, the definitions of
+yylex and yyerror often go here. See section Parser C-Language Interface.
+
+
+
+If the last section is empty, you may omit the `%%' that separates it
+from the grammar rules.
+
+
+
+The Bison parser itself contains many static variables whose names start
+with `yy' and many macros whose names start with `YY'. It is a
+good idea to avoid using any such names (except those documented in this
+manual) in the additional C code section of the grammar file.
+
+
+
+
+
+Symbols in Bison grammars represent the grammatical classifications
+of the language.
+
+
+
+A terminal symbol (also known as a token type) represents a
+class of syntactically equivalent tokens. You use the symbol in grammar
+rules to mean that a token in that class is allowed. The symbol is
+represented in the Bison parser by a numeric code, and the yylex
+function returns a token type code to indicate what kind of token has been
+read. You don't need to know what the code value is; you can use the
+symbol to stand for it.
+
+
+
+A nonterminal symbol stands for a class of syntactically equivalent
+groupings. The symbol name is used in writing grammar rules. By convention,
+it should be all lower case.
+
+
+
+Symbol names can contain letters, digits (not at the beginning),
+underscores and periods. Periods make sense only in nonterminals.
+
+
+
+There are three ways of writing terminal symbols in the grammar:
+
+
+
+
+
+
+A named token type is written with an identifier, like an
+identifier in C. By convention, it should be all upper case. Each
+such name must be defined with a Bison declaration such as
+%token. See section Token Type Names.
+
+
+
+
+
+
+A character token type (or literal character token) is
+written in the grammar using the same syntax used in C for character
+constants; for example, '+' is a character token type. A
+character token type doesn't need to be declared unless you need to
+specify its semantic value data type (see section Data Types of Semantic Values), associativity, or precedence (see section Operator Precedence).
+
+By convention, a character token type is used only to represent a
+token that consists of that particular character. Thus, the token
+type '+' is used to represent the character `+' as a
+token. Nothing enforces this convention, but if you depart from it,
+your program will confuse other readers.
+
+All the usual escape sequences used in character literals in C can be
+used in Bison as well, but you must not use the null character as a
+character literal because its ASCII code, zero, is the code yylex
+returns for end-of-input (see section Calling Convention for yylex).
+
+
+
+
+
+
+A literal string token is written like a C string constant; for
+example, "<=" is a literal string token. A literal string token
+doesn't need to be declared unless you need to specify its semantic
+value data type (see section Data Types of Semantic Values), associativity, or precedence
+(see section Operator Precedence).
+
+You can associate the literal string token with a symbolic name as an
+alias, using the %token declaration (see section Token Type Names). If you don't do that, the lexical analyzer has to
+retrieve the token number for the literal string token from the
+yytname table (see section Calling Convention for yylex).
+
+WARNING: literal string tokens do not work in Yacc.
+
+By convention, a literal string token is used only to represent a token
+that consists of that particular string. Thus, you should use the token
+type "<=" to represent the string `<=' as a token. Bison
+does not enforce this convention, but if you depart from it, people who
+read your program will be confused.
+
+All the escape sequences used in string literals in C can be used in
+Bison as well. A literal string token must contain two or more
+characters; for a token containing just one character, use a character
+token (see above).
+
+
+
+How you choose to write a terminal symbol has no effect on its
+grammatical meaning. That depends only on where it appears in rules and
+on when the parser function returns that symbol.
+
+
+
+The value returned by yylex is always one of the terminal symbols
+(or 0 for end-of-input). Whichever way you write the token type in the
+grammar rules, you write it the same way in the definition of yylex.
+The numeric code for a character token type is simply the ASCII code for
+the character, so yylex can use the identical character constant to
+generate the requisite code. Each named token type becomes a C macro in
+the parser file, so yylex can use the name to stand for the code.
+(This is why periods don't make sense in terminal symbols.)
+See section Calling Convention for yylex.
+
+
+
+If yylex is defined in a separate file, you need to arrange for the
+token-type macro definitions to be available there. Use the `-d'
+option when you run Bison, so that it will write these macro definitions
+into a separate header file `name.tab.h' which you can include
+in the other source files that need it. See section Invoking Bison.
+
+
+
+The symbol error is a terminal symbol reserved for error recovery
+(see section Error Recovery); you shouldn't use it for any other purpose.
+In particular, yylex should never return this value.
+
+
+
+
+
+A Bison grammar rule has the following general form:
+
+
+
+
+result: components...
+ ;
+
+
+
+where result is the nonterminal symbol that this rule describes,
+and components are various terminal and nonterminal symbols that
+are put together by this rule (see section Symbols, Terminal and Nonterminal).
+
+
+
+For example,
+
+
+
+
+exp: exp '+' exp
+ ;
+
+
+
+says that two groupings of type exp, with a `+' token in between,
+can be combined into a larger grouping of type exp.
+
+
+
+Whitespace in rules is significant only to separate symbols. You can add
+extra whitespace as you wish.
+
+
+
+Scattered among the components can be actions that determine
+the semantics of the rule. An action looks like this:
+
+
+
+
+{C statements}
+
+
+
+Usually there is only one action and it follows the components.
+See section Actions.
+
+
+
+
+Multiple rules for the same result can be written separately or can
+be joined with the vertical-bar character `|' as follows:
+
+
+
+
+They are still considered distinct rules even when joined in this way.
+
+
+
+If components in a rule is empty, it means that result can
+match the empty string. For example, here is how to define a
+comma-separated sequence of zero or more exp groupings:
+
+
+
+
+A rule is called recursive when its result nonterminal appears
+also on its right hand side. Nearly all Bison grammars need to use
+recursion, because that is the only way to define a sequence of any number
+of a particular thing. Consider this recursive definition of a
+comma-separated sequence of one or more expressions:
+
+
+
+
+expseq1: exp
+ | expseq1 ',' exp
+ ;
+
+
+
+
+
+Since the recursive use of expseq1 is the leftmost symbol in the
+right hand side, we call this left recursion. By contrast, here
+the same construct is defined using right recursion:
+
+
+
+
+expseq1: exp
+ | exp ',' expseq1
+ ;
+
+
+
+Any kind of sequence can be defined using either left recursion or
+right recursion, but you should always use left recursion, because it
+can parse a sequence of any number of elements with bounded stack
+space. Right recursion uses up space on the Bison stack in proportion
+to the number of elements in the sequence, because all the elements
+must be shifted onto the stack before the rule can be applied even
+once. See section The Bison Parser Algorithm, for
+further explanation of this.
+
+
+
+
+Indirect or mutual recursion occurs when the result of the
+rule does not appear directly on its right hand side, but does appear
+in rules for other nonterminals which do appear on its right hand
+side.
+
+
+
+The grammar rules for a language determine only the syntax. The semantics
+are determined by the semantic values associated with various tokens and
+groupings, and by the actions taken when various groupings are recognized.
+
+
+
+For example, the calculator calculates properly because the value
+associated with each expression is the proper number; it adds properly
+because the action for the grouping `x + y' is to add
+the numbers associated with x and y.
+
+
+
+
+
+In a simple program it may be sufficient to use the same data type for
+the semantic values of all language constructs. This was true in the
+RPN and infix calculator examples (see section Reverse Polish Notation Calculator).
+
+
+
+Bison's default is to use type int for all semantic values. To
+specify some other type, define YYSTYPE as a macro, like this:
+
+
+
+
+#define YYSTYPE double
+
+
+
+This macro definition must go in the C declarations section of the grammar
+file (see section Outline of a Bison Grammar).
+
+
+
+
+
+In most programs, you will need different data types for different kinds
+of tokens and groupings. For example, a numeric constant may need type
+int or long, while a string constant needs type char *,
+and an identifier might need a pointer to an entry in the symbol table.
+
+
+
+To use more than one data type for semantic values in one parser, Bison
+requires you to do two things:
+
+
+
+
+
+
+Specify the entire collection of possible data types, with the
+%union Bison declaration (see section The Collection of Value Types).
+
+
+
+Choose one of those types for each symbol (terminal or nonterminal) for
+which semantic values are used. This is done for tokens with the
+%token Bison declaration (see section Token Type Names)
+and for groupings with the %type Bison declaration (see section Nonterminal Symbols).
+
+An action accompanies a syntactic rule and contains C code to be executed
+each time an instance of that rule is recognized. The task of most actions
+is to compute a semantic value for the grouping built by the rule from the
+semantic values associated with tokens or smaller groupings.
+
+
+
+An action consists of C statements surrounded by braces, much like a
+compound statement in C. It can be placed at any position in the rule; it
+is executed at that position. Most rules have just one action at the end
+of the rule, following all the components. Actions in the middle of a rule
+are tricky and used only for special purposes (see section Actions in Mid-Rule).
+
+
+
+The C code in an action can refer to the semantic values of the components
+matched by the rule with the construct $n, which stands for
+the value of the nth component. The semantic value for the grouping
+being constructed is $$. (Bison translates both of these constructs
+into array element references when it copies the actions into the parser
+file.)
+
+
+
+Here is a typical example:
+
+
+
+
+exp: ...
+ | exp '+' exp
+ { $$ = $1 + $3; }
+
+
+
+This rule constructs an exp from two smaller exp groupings
+connected by a plus-sign token. In the action, $1 and $3
+refer to the semantic values of the two component exp groupings,
+which are the first and third symbols on the right hand side of the rule.
+The sum is stored into $$ so that it becomes the semantic value of
+the addition-expression just recognized by the rule. If there were a
+useful semantic value associated with the `+' token, it could be
+referred to as $2.
+
+
+
+If you don't specify an action for a rule, Bison supplies a default:
+$$ = $1. Thus, the value of the first symbol in the rule becomes
+the value of the whole rule. Of course, the default rule is valid only
+if the two data types match. There is no meaningful default action for
+an empty rule; every empty rule must have an explicit action unless the
+rule's value does not matter.
+
+
+
+$n with n zero or negative is allowed for reference
+to tokens and groupings on the stack before those that match the
+current rule. This is a very risky practice, and to use it reliably
+you must be certain of the context in which the rule is applied. Here
+is a case in which you can use this reliably:
+
+
+
+
+If you have chosen a single data type for semantic values, the $$
+and $n constructs always have that data type.
+
+
+
+If you have used %union to specify a variety of data types, then you
+must declare a choice among these types for each terminal or nonterminal
+symbol that can have a semantic value. Then each time you use $$ or
+$n, its data type is determined by which symbol it refers to
+in the rule. In this example,
+
+
+
+exp: ...
+ | exp '+' exp
+ { $$ = $1 + $3; }
+
+
+
+$1 and $3 refer to instances of exp, so they all
+have the data type declared for the nonterminal symbol exp. If
+$2 were used, it would have the data type declared for the
+terminal symbol '+', whatever that might be.
+
+
+Alternatively, you can specify the data type when you refer to the value,
+by inserting `<type>' after the `$' at the beginning of the
+reference. For example, if you have defined types as shown here:
+
+
+
+
+%union {
+ int itype;
+ double dtype;
+}
+
+
+
+then you can write $<itype>1 to refer to the first subunit of the
+rule as an integer, or $<dtype>1 to refer to it as a double.
+
+
+
+
+
+Occasionally it is useful to put an action in the middle of a rule.
+These actions are written just like usual end-of-rule actions, but they
+are executed before the parser even recognizes the following components.
+
+
+
+A mid-rule action may refer to the components preceding it using
+$n, but it may not refer to subsequent components because
+it is run before they are parsed.
+
+
+
+The mid-rule action itself counts as one of the components of the rule.
+This makes a difference when there is another action later in the same rule
+(and usually there is another at the end): you have to count the actions
+along with the symbols when working out which number n to use in
+$n.
+
+
+
+The mid-rule action can also have a semantic value. The action can set
+its value with an assignment to $$, and actions later in the rule
+can refer to the value using $n. Since there is no symbol
+to name the action, there is no way to declare a data type for the value
+in advance, so you must use the `$<...>n' construct to
+specify a data type each time you refer to this value.
+
+
+
+There is no way to set the value of the entire rule with a mid-rule
+action, because assignments to $$ do not have that effect. The
+only way to set the value for the entire rule is with an ordinary action
+at the end of the rule.
+
+
+
+Here is an example from a hypothetical compiler, handling a let
+statement that looks like `let (variable) statement' and
+serves to create a variable named variable temporarily for the
+duration of statement. To parse this construct, we must put
+variable into the symbol table while statement is parsed, then
+remove it afterward. Here is how it is done:
+
+
+
+
+As soon as `let (variable)' has been recognized, the first
+action is run. It saves a copy of the current semantic context (the
+list of accessible variables) as its semantic value, using alternative
+context in the data-type union. Then it calls
+declare_variable to add the new variable to that list. Once the
+first action is finished, the embedded statement stmt can be
+parsed. Note that the mid-rule action is component number 5, so the
+`stmt' is component number 6.
+
+
+
+After the embedded statement is parsed, its semantic value becomes the
+value of the entire let-statement. Then the semantic value from the
+earlier action is used to restore the prior list of variables. This
+removes the temporary let-variable from the list so that it won't
+appear to exist while the rest of the program is parsed.
+
+
+
+Taking action before a rule is completely recognized often leads to
+conflicts since the parser must commit to a parse in order to execute the
+action. For example, the following two rules, without mid-rule actions,
+can coexist in a working parser because the parser can shift the open-brace
+token and look at what follows before deciding whether there is a
+declaration or not:
+
+
+
+
+Now the parser is forced to decide whether to run the mid-rule action
+when it has read no farther than the open-brace. In other words, it
+must commit to using one rule or the other, without sufficient
+information to do it correctly. (The open-brace token is what is called
+the look-ahead token at this time, since the parser is still
+deciding what to do about it. See section Look-Ahead Tokens.)
+
+
+
+You might think that you could correct the problem by putting identical
+actions into the two rules, like this:
+
+
+
+
+But this does not help, because Bison does not realize that the two actions
+are identical. (Bison never tries to understand the C code in an action.)
+
+
+
+If the grammar is such that a declaration can be distinguished from a
+statement by the first token (which is true in C), then one solution which
+does work is to put the action after the open-brace, like this:
+
+
+
+
+Now Bison can execute the action in the rule for subroutine without
+deciding which rule for compound it will eventually use. Note that
+the action is now at the end of its rule. Any mid-rule action can be
+converted to an end-of-rule action in this way, and this is what Bison
+actually does to implement mid-rule actions.
+
+
+
+
+
+Though grammar rules and semantic actions are enough to write a fully
+functional parser, it can be useful to process some additionnal informations,
+especially symbol locations.
+
+
+
+The way locations are handled is defined by providing a data type, and actions
+to take when rules are matched.
+
+
+
+
+
+Defining a data type for locations is much simpler than for semantic values,
+since all tokens and groupings always use the same type.
+
+
+
+The type of locations is specified by defining a macro called YYLTYPE.
+When YYLTYPE is not defined, Bison uses a default structure type with
+four members:
+
+
+
+
+struct
+{
+ int first_line;
+ int first_column;
+ int last_line;
+ int last_column;
+}
+
+Actions are not only useful for defining language semantics, but also for
+describing the behavior of the output parser with locations.
+
+
+
+The most obvious way for building locations of syntactic groupings is very
+similar to the way semantic values are computed. In a given rule, several
+constructs can be used to access the locations of the elements being matched.
+The location of the nth component of the right hand side is
+@n, while the location of the left hand side grouping is
+@$.
+
+
+
+Here is a basic example using the default data type for locations:
+
+
+
+
+As for semantic values, there is a default action for locations that is
+run each time a rule is matched. It sets the beginning of @$ to the
+beginning of the first symbol, and the end of @$ to the end of the
+last symbol.
+
+
+
+With this default action, the location tracking can be fully automatic. The
+example above simply rewrites this way:
+
+
+
+
+Actually, actions are not the best place to compute locations. Since locations
+are much more general than semantic values, there is room in the output parser
+to redefine the default action to take for each rule. The
+YYLLOC_DEFAULT macro is called each time a rule is matched, before the
+associated action is run.
+
+
+
+Most of the time, this macro is general enough to suppress location
+dedicated code from semantic actions.
+
+
+
+The YYLLOC_DEFAULT macro takes three parameters. The first one is
+the location of the grouping (the result of the computation). The second one
+is an array holding locations of all right hand side elements of the rule
+being matched. The last one is the size of the right hand side rule.
+
+
+
+The Bison declarations section of a Bison grammar defines the symbols
+used in formulating the grammar and the data types of semantic values.
+See section Symbols, Terminal and Nonterminal.
+
+
+
+All token type names (but not single-character literal tokens such as
+'+' and '*') must be declared. Nonterminal symbols must be
+declared if you need to specify which data type to use for the semantic
+value (see section More Than One Value Type).
+
+
+
+The first rule in the file also specifies the start symbol, by default.
+If you want some other symbol to be the start symbol, you must declare
+it explicitly (see section Languages and Context-Free Grammars).
+
+
+
+
+
+The basic way to declare a token type name (terminal symbol) is as follows:
+
+
+
+
+%token name
+
+
+
+Bison will convert this into a #define directive in
+the parser, so that the function yylex (if it is in this file)
+can use the name name to stand for this token type's code.
+
+
+
+Alternatively, you can use %left, %right, or
+%nonassoc instead of %token, if you wish to specify
+associativity and precedence. See section Operator Precedence.
+
+
+
+You can explicitly specify the numeric code for a token type by appending
+an integer value in the field immediately following the token name:
+
+
+
+
+%token NUM 300
+
+
+
+It is generally best, however, to let Bison choose the numeric codes for
+all token types. Bison will automatically select codes that don't conflict
+with each other or with ASCII characters.
+
+
+
+In the event that the stack type is a union, you must augment the
+%token or other token declaration to include the data type
+alternative delimited by angle-brackets (see section More Than One Value Type).
+
+
+
+For example:
+
+
+
+
+%union { /* define stack type */
+ double val;
+ symrec *tptr;
+}
+%token <val> NUM /* define token NUM and its type */
+
+
+
+You can associate a literal string token with a token type name by
+writing the literal string at the end of a %token
+declaration which declares the name. For example:
+
+
+
+
+%token arrow "=>"
+
+
+
+For example, a grammar for the C language might specify these names with
+equivalent literal string tokens:
+
+
+
+
+%token <operator> OR "||"
+%token <operator> LE 134 "<="
+%left OR "<="
+
+
+
+Once you equate the literal string and the token name, you can use them
+interchangeably in further declarations or the grammar rules. The
+yylex function can use the token name or the literal string to
+obtain the token type code number (see section Calling Convention for yylex).
+
+
+
+
+
+Use the %left, %right or %nonassoc declaration to
+declare a token and specify its precedence and associativity, all at
+once. These are called precedence declarations.
+See section Operator Precedence, for general information on operator precedence.
+
+
+
+The syntax of a precedence declaration is the same as that of
+%token: either
+
+
+
+
+%left symbols...
+
+
+
+or
+
+
+
+
+%left <type> symbols...
+
+
+
+And indeed any of these declarations serves the purposes of %token.
+But in addition, they specify the associativity and relative precedence for
+all the symbols:
+
+
+
+
+
+
+The associativity of an operator op determines how repeated uses
+of the operator nest: whether `xopyop
+z' is parsed by grouping x with y first or by
+grouping y with z first. %left specifies
+left-associativity (grouping x with y first) and
+%right specifies right-associativity (grouping y with
+z first). %nonassoc specifies no associativity, which
+means that `xopyopz' is
+considered a syntax error.
+
+
+
+The precedence of an operator determines how it nests with other operators.
+All the tokens declared in a single precedence declaration have equal
+precedence and nest together according to their associativity.
+When two tokens declared in different precedence declarations associate,
+the one declared later has the higher precedence and is grouped first.
+
+The %union declaration specifies the entire collection of possible
+data types for semantic values. The keyword %union is followed by a
+pair of braces containing the same thing that goes inside a union in
+C.
+
+
+
+For example:
+
+
+
+
+%union {
+ double val;
+ symrec *tptr;
+}
+
+
+
+This says that the two alternative types are double and symrec
+*. They are given names val and tptr; these names are used
+in the %token and %type declarations to pick one of the types
+for a terminal or nonterminal symbol (see section Nonterminal Symbols).
+
+
+
+Note that, unlike making a union declaration in C, you do not write
+a semicolon after the closing brace.
+
+
+
+
+
+When you use %union to specify multiple value types, you must
+declare the value type of each nonterminal symbol for which values are
+used. This is done with a %type declaration, like this:
+
+
+
+
+%type <type> nonterminal...
+
+
+
+Here nonterminal is the name of a nonterminal symbol, and type
+is the name given in the %union to the alternative that you want
+(see section The Collection of Value Types). You can give any number of nonterminal symbols in
+the same %type declaration, if they have the same value type. Use
+spaces to separate the symbol names.
+
+
+
+You can also declare the value type of a terminal symbol. To do this,
+use the same <type> construction in a declaration for the
+terminal symbol. All kinds of token declarations allow
+<type>.
+
+
+
+
+
+Bison normally warns if there are any conflicts in the grammar
+(see section Shift/Reduce Conflicts), but most real grammars have harmless shift/reduce
+conflicts which are resolved in a predictable way and would be difficult to
+eliminate. It is desirable to suppress the warning about these conflicts
+unless the number of conflicts changes. You can do this with the
+%expect declaration.
+
+
+
+The declaration looks like this:
+
+
+
+
+%expect n
+
+
+
+Here n is a decimal integer. The declaration says there should be no
+warning if there are n shift/reduce conflicts and no reduce/reduce
+conflicts. The usual warning is given if there are either more or fewer
+conflicts, or if there are any reduce/reduce conflicts.
+
+
+
+In general, using %expect involves these steps:
+
+
+
+
+
+
+Compile your grammar without %expect. Use the `-v' option
+to get a verbose list of where the conflicts occur. Bison will also
+print the number of conflicts.
+
+
+
+Check each of the conflicts to make sure that Bison's default
+resolution is what you really want. If not, rewrite the grammar and
+go back to the beginning.
+
+
+
+Add an %expect declaration, copying the number n from the
+number which Bison printed.
+
+
+
+Now Bison will stop annoying you about the conflicts you have checked, but
+it will warn you again if changes in the grammar result in additional
+conflicts.
+
+
+
+
+
+Bison assumes by default that the start symbol for the grammar is the first
+nonterminal specified in the grammar specification section. The programmer
+may override this restriction with the %start declaration as follows:
+
+
+
+
+A reentrant program is one which does not alter in the course of
+execution; in other words, it consists entirely of pure (read-only)
+code. Reentrancy is important whenever asynchronous execution is possible;
+for example, a non-reentrant program may not be safe to call from a signal
+handler. In systems with multiple threads of control, a non-reentrant
+program must be called only within interlocks.
+
+
+
+Normally, Bison generates a parser which is not reentrant. This is
+suitable for most uses, and it permits compatibility with YACC. (The
+standard YACC interfaces are inherently nonreentrant, because they use
+statically allocated variables for communication with yylex,
+including yylval and yylloc.)
+
+
+
+Alternatively, you can generate a pure, reentrant parser. The Bison
+declaration %pure_parser says that you want the parser to be
+reentrant. It looks like this:
+
+
+
+
+%pure_parser
+
+
+
+The result is that the communication variables yylval and
+yylloc become local variables in yyparse, and a different
+calling convention is used for the lexical analyzer function
+yylex. See section Calling Conventions for Pure Parsers, for the details of this. The variable yynerrs also
+becomes local in yyparse (see section The Error Reporting Function yyerror). The convention for calling
+yyparse itself is unchanged.
+
+
+
+Whether the parser is pure has nothing to do with the grammar rules.
+You can generate either a pure parser or a nonreentrant parser from any
+valid grammar.
+
+
+
+
+
+Here is a summary of all Bison declarations:
+
+
+
+
+
%union
+
+Declare the collection of data types that semantic values may have
+(see section The Collection of Value Types).
+
+
%token
+
+Declare a terminal symbol (token type name) with no precedence
+or associativity specified (see section Token Type Names).
+
+
%right
+
+Declare a terminal symbol (token type name) that is right-associative
+(see section Operator Precedence).
+
+
%left
+
+Declare a terminal symbol (token type name) that is left-associative
+(see section Operator Precedence).
+
+
%nonassoc
+
+Declare a terminal symbol (token type name) that is nonassociative
+(using it in a way that would be associative is a syntax error)
+(see section Operator Precedence).
+
+
%type
+
+Declare the type of semantic values for a nonterminal symbol
+(see section Nonterminal Symbols).
+
+
%start
+
+Specify the grammar's start symbol (see section The Start-Symbol).
+
+
+Pretend the option @option{--yacc} was given, i.e., imitate Yacc,
+including its naming conventions. See section Bison Options, for more.
+
+
%locations
+
+Generate the code processing the locations (see section Special Features for Use in Actions). This mode is enabled as soon as
+the grammar uses the special `@n' tokens, but if your
+grammar does not use it, using `%locations' allows for more
+accurate parse error messages.
+
+
+Do not include any C code in the parser file; generate tables only. The
+parser file contains just #define directives and static variable
+declarations.
+
+This option also tells Bison to write the C code for the grammar actions
+into a file named `filename.act', in the form of a
+brace-surrounded body fit for a switch statement.
+
+
%no_lines
+
+Don't generate any #line preprocessor commands in the parser
+file. Ordinarily Bison writes these commands in the parser file so that
+the C compiler and debuggers will associate errors and object code with
+your source file (the grammar file). This directive causes them to
+associate errors with the parser file, treating it an independent source
+file in its own right.
+
+
%debug
+
+Output a definition of the macro YYDEBUG into the parser file, so
+that the debugging facilities are compiled. See section Debugging Your Parser.
+
+
%defines
+
+Write an extra output file containing macro definitions for the token
+type names defined in the grammar and the semantic value type
+YYSTYPE, as well as a few extern variable declarations.
+
+If the parser output file is named `name.c' then this file
+is named `name.h'.
+This output file is essential if you wish to put the definition of
+yylex in a separate source file, because yylex needs to
+be able to refer to token type codes and the variable
+yylval. See section Semantic Values of Tokens.
+
%verbose
+
+Write an extra output file containing verbose descriptions of the
+parser states and what is done for each type of look-ahead token in
+that state.
+
+This file also describes all the conflicts, both those resolved by
+operator precedence and the unresolved ones.
+
+The file's name is made by removing `.tab.c' or `.c' from
+the parser output file name, and adding `.output' instead.
+Therefore, if the input file is `foo.y', then the parser file is
+called `foo.tab.c' by default. As a consequence, the verbose
+output file is called `foo.output'.
+
%token_table
+
+Generate an array of token names in the parser file. The name of the
+array is yytname; yytname[i] is the name of the
+token whose internal Bison token code number is i. The first three
+elements of yytname are always "$", "error", and
+"$illegal"; after these come the symbols defined in the grammar
+file.
+
+For single-character literal tokens and literal string tokens, the name
+in the table includes the single-quote or double-quote characters: for
+example, "'+'" is a single-character literal and "\"<=\""
+is a literal string token. All the characters of the literal string
+token appear verbatim in the string found in the table; even
+double-quote characters are not escaped. For example, if the token
+consists of three characters `*"*', its string in yytname
+contains `"*"*"'. (In C, that would be written as
+"\"*\"*\"").
+
+When you specify %token_table, Bison also generates macro
+definitions for macros YYNTOKENS, YYNNTS, and
+YYNRULES, and YYNSTATES:
+
+
+
+
YYNTOKENS
+
+The highest token number, plus one.
+
YYNNTS
+
+The number of nonterminal symbols.
+
YYNRULES
+
+The number of grammar rules,
+
YYNSTATES
+
+The number of parser states (see section Parser States).
+
+Most programs that use Bison parse only one language and therefore contain
+only one Bison parser. But what if you want to parse more than one
+language with the same program? Then you need to avoid a name conflict
+between different definitions of yyparse, yylval, and so on.
+
+
+
+The easy way to do this is to use the option `-p prefix'
+(see section Invoking Bison). This renames the interface functions and
+variables of the Bison parser to start with prefix instead of
+`yy'. You can use this to give each parser distinct names that do
+not conflict.
+
+
+
+The precise list of symbols renamed is yyparse, yylex,
+yyerror, yynerrs, yylval, yychar and
+yydebug. For example, if you use `-p c', the names become
+cparse, clex, and so on.
+
+
+
+All the other variables and macros associated with Bison are not
+renamed. These others are not global; there is no conflict if the same
+name is used in different parsers. For example, YYSTYPE is not
+renamed, but defining this in different ways in different parsers causes
+no trouble (see section Data Types of Semantic Values).
+
+
+
+The `-p' option works by adding macro definitions to the beginning
+of the parser source file, defining yyparse as
+prefixparse, and so on. This effectively substitutes one
+name for the other in the entire parser file.
+
+
+
+
+
+The Bison parser is actually a C function named yyparse. Here we
+describe the interface conventions of yyparse and the other
+functions that it needs to use.
+
+
+
+Keep in mind that the parser uses many C identifiers starting with
+`yy' and `YY' for internal purposes. If you use such an
+identifier (aside from those in this manual) in an action or in additional
+C code in the grammar file, you are likely to run into trouble.
+
+
+
+
+
+You call the function yyparse to cause parsing to occur. This
+function reads tokens, executes actions, and ultimately returns when it
+encounters end-of-input or an unrecoverable syntax error. You can also
+write an action which directs yyparse to return immediately
+without reading further.
+
+
+
+The value returned by yyparse is 0 if parsing was successful (return
+is due to end-of-input).
+
+
+
+The value is 1 if parsing failed (return is due to a syntax error).
+
+
+
+In an action, you can cause immediate return from yyparse by using
+these macros:
+
+
+
+
+
YYACCEPT
+
+
+Return immediately with value 0 (to report success).
+
+
YYABORT
+
+
+Return immediately with value 1 (to report failure).
+
+The lexical analyzer function, yylex, recognizes tokens from
+the input stream and returns them to the parser. Bison does not create
+this function automatically; you must write it so that yyparse can
+call it. The function is sometimes referred to as a lexical scanner.
+
+
+
+In simple programs, yylex is often defined at the end of the Bison
+grammar file. If yylex is defined in a separate source file, you
+need to arrange for the token-type macro definitions to be available there.
+To do this, use the `-d' option when you run Bison, so that it will
+write these macro definitions into a separate header file
+`name.tab.h' which you can include in the other source files
+that need it. See section Invoking Bison.
+
+
+
+
+The value that yylex returns must be the numeric code for the type
+of token it has just found, or 0 for end-of-input.
+
+
+
+When a token is referred to in the grammar rules by a name, that name
+in the parser file becomes a C macro whose definition is the proper
+numeric code for that token type. So yylex can use the name
+to indicate that type. See section Symbols, Terminal and Nonterminal.
+
+
+
+When a token is referred to in the grammar rules by a character literal,
+the numeric code for that character is also the code for the token type.
+So yylex can simply return that character code. The null character
+must not be used this way, because its code is zero and that is what
+signifies end-of-input.
+
+
+
+Here is an example showing these things:
+
+
+
+
+int
+yylex (void)
+{
+ ...
+ if (c == EOF) /* Detect end of file. */
+ return 0;
+ ...
+ if (c == '+' || c == '-')
+ return c; /* Assume token type for `+' is '+'. */
+ ...
+ return INT; /* Return the type of the token. */
+ ...
+}
+
+
+
+This interface has been designed so that the output from the lex
+utility can be used without change as the definition of yylex.
+
+
+
+If the grammar uses literal string tokens, there are two ways that
+yylex can determine the token type codes for them:
+
+
+
+
+
+
+If the grammar defines symbolic token names as aliases for the
+literal string tokens, yylex can use these symbolic names like
+all others. In this case, the use of the literal string tokens in
+the grammar file has no effect on yylex.
+
+
+
+yylex can find the multicharacter token in the yytname
+table. The index of the token in the table is the token type's code.
+The name of a multicharacter token is recorded in yytname with a
+double-quote, the token's characters, and another double-quote. The
+token's characters are not escaped in any way; they appear verbatim in
+the contents of the string in the table.
+
+Here's code for looking up a token in yytname, assuming that the
+characters of the token are stored in token_buffer.
+
+
+
+
+In an ordinary (non-reentrant) parser, the semantic value of the token must
+be stored into the global variable yylval. When you are using
+just one data type for semantic values, yylval has that type.
+Thus, if the type is int (the default), you might write this in
+yylex:
+
+
+
+
+ ...
+ yylval = value; /* Put value onto Bison stack. */
+ return INT; /* Return the type of the token. */
+ ...
+
+
+
+When you are using multiple data types, yylval's type is a union
+made from the %union declaration (see section The Collection of Value Types). So when
+you store a token's value, you must use the proper member of the union.
+If the %union declaration looks like this:
+
+
+
+
+
+If you are using the `@n'-feature (see section Tracking Locations) in actions to keep track of the
+textual locations of tokens and groupings, then you must provide this
+information in yylex. The function yyparse expects to
+find the textual location of a token just parsed in the global variable
+yylloc. So yylex must store the proper data in that
+variable.
+
+
+
+By default, the value of yylloc is a structure and you need only
+initialize the members that are going to be used by the actions. The
+four members are called first_line, first_column,
+last_line and last_column. Note that the use of this
+feature makes the parser noticeably slower.
+
+
+
+
+The data type of yylloc has the name YYLTYPE.
+
+
+
+
+
+When you use the Bison declaration %pure_parser to request a
+pure, reentrant parser, the global communication variables yylval
+and yylloc cannot be used. (See section A Pure (Reentrant) Parser.) In such parsers the two global variables are replaced by
+pointers passed as arguments to yylex. You must declare them as
+shown here, and pass the information back by storing it through those
+pointers.
+
+
+
+
+int
+yylex (YYSTYPE *lvalp, YYLTYPE *llocp)
+{
+ ...
+ *lvalp = value; /* Put value onto Bison stack. */
+ return INT; /* Return the type of the token. */
+ ...
+}
+
+
+
+If the grammar file does not use the `@' constructs to refer to
+textual positions, then the type YYLTYPE will not be defined. In
+this case, omit the second argument; yylex will be called with
+only one argument.
+
+
+
+
+If you use a reentrant parser, you can optionally pass additional
+parameter information to it in a reentrant way. To do so, define the
+macro YYPARSE_PARAM as a variable name. This modifies the
+yyparse function to accept one argument, of type void *,
+with that name.
+
+
+
+When you call yyparse, pass the address of an object, casting the
+address to void *. The grammar actions can refer to the contents
+of the object by casting the pointer value back to its proper type and
+then dereferencing it. Here's an example. Write this in the parser:
+
+
+
+
+%{
+struct parser_control
+{
+ int nastiness;
+ int randomness;
+};
+
+#define YYPARSE_PARAM parm
+%}
+
+
+
+Then call the parser like this:
+
+
+
+
+struct parser_control
+{
+ int nastiness;
+ int randomness;
+};
+
+...
+
+{
+ struct parser_control foo;
+ ... /* Store proper data in foo. */
+ value = yyparse ((void *) &foo);
+ ...
+}
+
+
+
+In the grammar actions, use expressions like this to refer to the data:
+
+
+
+
+((struct parser_control *) parm)->randomness
+
+
+
+
+If you wish to pass the additional parameter data to yylex,
+define the macro YYLEX_PARAM just like YYPARSE_PARAM, as
+shown here:
+
+
+
+
+%{
+struct parser_control
+{
+ int nastiness;
+ int randomness;
+};
+
+#define YYPARSE_PARAM parm
+#define YYLEX_PARAM parm
+%}
+
+
+
+You should then define yylex to accept one additional
+argument--the value of parm. (This makes either two or three
+arguments in total, depending on whether an argument of type
+YYLTYPE is passed.) You can declare the argument as a pointer to
+the proper object type, or you can declare it as void * and
+access the contents as shown above.
+
+
+
+You can use `%pure_parser' to request a reentrant parser without
+also using YYPARSE_PARAM. Then you should call yyparse
+with no arguments, as usual.
+
+
+
+
+
+The Bison parser detects a parse error or syntax error
+whenever it reads a token which cannot satisfy any syntax rule. An
+action in the grammar can also explicitly proclaim an error, using the
+macro YYERROR (see section Special Features for Use in Actions).
+
+
+
+The Bison parser expects to report the error by calling an error
+reporting function named yyerror, which you must supply. It is
+called by yyparse whenever a syntax error is found, and it
+receives one argument. For a parse error, the string is normally
+"parse error".
+
+
+
+
+If you define the macro YYERROR_VERBOSE in the Bison declarations
+section (see section The Bison Declarations Section),
+then Bison provides a more verbose and specific error message string
+instead of just plain "parse error". It doesn't matter what
+definition you use for YYERROR_VERBOSE, just whether you define
+it.
+
+
+
+The parser can detect one other kind of error: stack overflow. This
+happens when the input contains constructions that are very deeply
+nested. It isn't likely you will encounter this, since the Bison
+parser extends its stack automatically up to a very large limit. But
+if overflow happens, yyparse calls yyerror in the usual
+fashion, except that the argument string is "parser stack
+overflow".
+
+
+
+The following definition suffices in simple programs:
+
+
+
+
+After yyerror returns to yyparse, the latter will attempt
+error recovery if you have written suitable error recovery grammar rules
+(see section Error Recovery). If recovery is impossible, yyparse will
+immediately return 1.
+
+
+
+
+The variable yynerrs contains the number of syntax errors
+encountered so far. Normally this variable is global; but if you
+request a pure parser (see section A Pure (Reentrant) Parser) then it is a local variable
+which only the actions can access.
+
+
+
+
+
+
+Unshift a token. This macro is allowed only for rules that reduce
+a single value, and only when there is no look-ahead token.
+It installs a look-ahead token with token type token and
+semantic value value; then it discards the value that was
+going to be reduced by this rule.
+
+If the macro is used when it is not valid, such as when there is
+a look-ahead token already, then it reports a syntax error with
+a message `cannot back up' and performs ordinary error
+recovery.
+
+In either case, the rest of the action is not executed.
+
+
`YYEMPTY'
+
+
+Value stored in yychar when there is no look-ahead token.
+
+
`YYERROR;'
+
+
+Cause an immediate syntax error. This statement initiates error
+recovery just as if the parser itself had detected an error; however, it
+does not call yyerror, and does not print any message. If you
+want to print an error message, call yyerror explicitly before
+the `YYERROR;' statement. See section Error Recovery.
+
+
`YYRECOVERING'
+
+This macro stands for an expression that has the value 1 when the parser
+is recovering from a syntax error, and 0 the rest of the time.
+See section Error Recovery.
+
+
`yychar'
+
+Variable containing the current look-ahead token. (In a pure parser,
+this is actually a local variable within yyparse.) When there is
+no look-ahead token, the value YYEMPTY is stored in the variable.
+See section Look-Ahead Tokens.
+
+
`yyclearin;'
+
+Discard the current look-ahead token. This is useful primarily in
+error rules. See section Error Recovery.
+
+
`yyerrok;'
+
+Resume generating error messages immediately for subsequent syntax
+errors. This is useful primarily in error rules.
+See section Error Recovery.
+
+
`@$'
+
+
+Acts like a structure variable containing information on the textual position
+of the grouping made by the current rule. See section Tracking Locations.
+
+
`@n'
+
+
+Acts like a structure variable containing information on the textual position
+of the nth component of the current rule. See section Tracking Locations.
+
+
+As Bison reads tokens, it pushes them onto a stack along with their
+semantic values. The stack is called the parser stack. Pushing a
+token is traditionally called shifting.
+
+
+
+For example, suppose the infix calculator has read `1 + 5 *', with a
+`3' to come. The stack will have four elements, one for each token
+that was shifted.
+
+
+
+But the stack does not always have an element for each token read. When
+the last n tokens and groupings shifted match the components of a
+grammar rule, they can be combined according to that rule. This is called
+reduction. Those tokens and groupings are replaced on the stack by a
+single grouping whose symbol is the result (left hand side) of that rule.
+Running the rule's action is part of the process of reduction, because this
+is what computes the semantic value of the resulting grouping.
+
+
+
+For example, if the infix calculator's parser stack contains this:
+
+
+
+
+1 + 5 * 3
+
+
+
+and the next input token is a newline character, then the last three
+elements can be reduced to 15 via the rule:
+
+
+
+
+expr: expr '*' expr;
+
+
+
+Then the stack contains just these three elements:
+
+
+
+
+1 + 15
+
+
+
+At this point, another reduction can be made, resulting in the single value
+16. Then the newline token can be shifted.
+
+
+
+The parser tries, by shifts and reductions, to reduce the entire input down
+to a single grouping whose symbol is the grammar's start-symbol
+(see section Languages and Context-Free Grammars).
+
+
+
+This kind of parser is known in the literature as a bottom-up parser.
+
+
+
+
+
+The Bison parser does not always reduce immediately as soon as the
+last n tokens and groupings match a rule. This is because such a
+simple strategy is inadequate to handle most languages. Instead, when a
+reduction is possible, the parser sometimes "looks ahead" at the next
+token in order to decide what to do.
+
+
+
+When a token is read, it is not immediately shifted; first it becomes the
+look-ahead token, which is not on the stack. Now the parser can
+perform one or more reductions of tokens and groupings on the stack, while
+the look-ahead token remains off to the side. When no more reductions
+should take place, the look-ahead token is shifted onto the stack. This
+does not mean that all possible reductions have been done; depending on the
+token type of the look-ahead token, some rules may choose to delay their
+application.
+
+
+
+Here is a simple case where look-ahead is needed. These three rules define
+expressions which contain binary addition operators and postfix unary
+factorial operators (`!'), and allow parentheses for grouping.
+
+
+
+
+expr: term '+' expr
+ | term
+ ;
+
+term: '(' expr ')'
+ | term '!'
+ | NUMBER
+ ;
+
+
+
+Suppose that the tokens `1 + 2' have been read and shifted; what
+should be done? If the following token is `)', then the first three
+tokens must be reduced to form an expr. This is the only valid
+course, because shifting the `)' would produce a sequence of symbols
+term ')', and no rule allows this.
+
+
+
+If the following token is `!', then it must be shifted immediately so
+that `2 !' can be reduced to make a term. If instead the
+parser were to reduce before shifting, `1 + 2' would become an
+expr. It would then be impossible to shift the `!' because
+doing so would produce on the stack the sequence of symbols expr
+'!'. No rule allows that sequence.
+
+
+
+Suppose we are parsing a language which has if-then and if-then-else
+statements, with a pair of rules like this:
+
+
+
+
+if_stmt:
+ IF expr THEN stmt
+ | IF expr THEN stmt ELSE stmt
+ ;
+
+
+
+Here we assume that IF, THEN and ELSE are
+terminal symbols for specific keyword tokens.
+
+
+
+When the ELSE token is read and becomes the look-ahead token, the
+contents of the stack (assuming the input is valid) are just right for
+reduction by the first rule. But it is also legitimate to shift the
+ELSE, because that would lead to eventual reduction by the second
+rule.
+
+
+
+This situation, where either a shift or a reduction would be valid, is
+called a shift/reduce conflict. Bison is designed to resolve
+these conflicts by choosing to shift, unless otherwise directed by
+operator precedence declarations. To see the reason for this, let's
+contrast it with the other alternative.
+
+
+
+Since the parser prefers to shift the ELSE, the result is to attach
+the else-clause to the innermost if-statement, making these two inputs
+equivalent:
+
+
+
+
+if x then if y then win (); else lose;
+
+if x then do; if y then win (); else lose; end;
+
+
+
+But if the parser chose to reduce when possible rather than shift, the
+result would be to attach the else-clause to the outermost if-statement,
+making these two inputs equivalent:
+
+
+
+
+if x then if y then win (); else lose;
+
+if x then do; if y then win (); end; else lose;
+
+
+
+The conflict exists because the grammar as written is ambiguous: either
+parsing of the simple nested if-statement is legitimate. The established
+convention is that these ambiguities are resolved by attaching the
+else-clause to the innermost if-statement; this is what Bison accomplishes
+by choosing to shift rather than reduce. (It would ideally be cleaner to
+write an unambiguous grammar, but that is very hard to do in this case.)
+This particular ambiguity was first encountered in the specifications of
+Algol 60 and is called the "dangling else" ambiguity.
+
+
+
+To avoid warnings from Bison about predictable, legitimate shift/reduce
+conflicts, use the %expect n declaration. There will be no
+warning as long as the number of shift/reduce conflicts is exactly n.
+See section Suppressing Conflict Warnings.
+
+
+
+The definition of if_stmt above is solely to blame for the
+conflict, but the conflict does not actually appear without additional
+rules. Here is a complete Bison input file that actually manifests the
+conflict:
+
+
+
+
+%token IF THEN ELSE variable
+%%
+stmt: expr
+ | if_stmt
+ ;
+
+if_stmt:
+ IF expr THEN stmt
+ | IF expr THEN stmt ELSE stmt
+ ;
+
+expr: variable
+ ;
+
+Another situation where shift/reduce conflicts appear is in arithmetic
+expressions. Here shifting is not always the preferred resolution; the
+Bison declarations for operator precedence allow you to specify when to
+shift and when to reduce.
+
+
+
+
+
+Suppose the parser has seen the tokens `1', `-' and `2';
+should it reduce them via the rule for the subtraction operator? It
+depends on the next token. Of course, if the next token is `)', we
+must reduce; shifting is invalid because no single rule can reduce the
+token sequence `- 2 )' or anything starting with that. But if
+the next token is `*' or `<', we have a choice: either
+shifting or reduction would allow the parse to complete, but with
+different results.
+
+
+
+To decide which one Bison should do, we must consider the results. If
+the next operator token op is shifted, then it must be reduced
+first in order to permit another opportunity to reduce the difference.
+The result is (in effect) `1 - (2 op 3)'. On the other
+hand, if the subtraction is reduced before shifting op, the result
+is `(1 - 2) op 3'. Clearly, then, the choice of shift or
+reduce should depend on the relative precedence of the operators
+`-' and op: `*' should be shifted first, but not
+`<'.
+
+
+
+
+What about input such as `1 - 2 - 5'; should this be
+`(1 - 2) - 5' or should it be `1 - (2 - 5)'? For most
+operators we prefer the former, which is called left association.
+The latter alternative, right association, is desirable for
+assignment operators. The choice of left or right association is a
+matter of whether the parser chooses to shift or reduce when the stack
+contains `1 - 2' and the look-ahead token is `-': shifting
+makes right-associativity.
+
+
+
+
+
+Bison allows you to specify these choices with the operator precedence
+declarations %left and %right. Each such declaration
+contains a list of tokens, which are operators whose precedence and
+associativity is being declared. The %left declaration makes all
+those operators left-associative and the %right declaration makes
+them right-associative. A third alternative is %nonassoc, which
+declares that it is a syntax error to find the same operator twice "in a
+row".
+
+
+
+The relative precedence of different operators is controlled by the
+order in which they are declared. The first %left or
+%right declaration in the file declares the operators whose
+precedence is lowest, the next such declaration declares the operators
+whose precedence is a little higher, and so on.
+
+
+
+
+
+In our example, we would want the following declarations:
+
+
+
+
+%left '<'
+%left '-'
+%left '*'
+
+
+
+In a more complete example, which supports other operators as well, we
+would declare them in groups of equal precedence. For example, '+' is
+declared with '-':
+
+
+
+
+%left '<' '>' '=' NE LE GE
+%left '+' '-'
+%left '*' '/'
+
+
+
+(Here NE and so on stand for the operators for "not equal"
+and so on. We assume that these tokens are more than one character long
+and therefore are represented by names, not character literals.)
+
+
+
+
+
+The first effect of the precedence declarations is to assign precedence
+levels to the terminal symbols declared. The second effect is to assign
+precedence levels to certain rules: each rule gets its precedence from the
+last terminal symbol mentioned in the components. (You can also specify
+explicitly the precedence of a rule. See section Context-Dependent Precedence.)
+
+
+
+Finally, the resolution of conflicts works by comparing the
+precedence of the rule being considered with that of the
+look-ahead token. If the token's precedence is higher, the
+choice is to shift. If the rule's precedence is higher, the
+choice is to reduce. If they have equal precedence, the choice
+is made based on the associativity of that precedence level. The
+verbose output file made by `-v' (see section Invoking Bison) says
+how each conflict was resolved.
+
+
+
+Not all rules and not all tokens have precedence. If either the rule or
+the look-ahead token has no precedence, then the default is to shift.
+
+
+
+
+
+Often the precedence of an operator depends on the context. This sounds
+outlandish at first, but it is really very common. For example, a minus
+sign typically has a very high precedence as a unary operator, and a
+somewhat lower precedence (lower than multiplication) as a binary operator.
+
+
+
+The Bison precedence declarations, %left, %right and
+%nonassoc, can only be used once for a given token; so a token has
+only one precedence declared in this way. For context-dependent
+precedence, you need to use an additional mechanism: the %prec
+modifier for rules.
+
+
+The %prec modifier declares the precedence of a particular rule by
+specifying a terminal symbol whose precedence should be used for that rule.
+It's not necessary for that symbol to appear otherwise in the rule. The
+modifier's syntax is:
+
+
+
+
+%prec terminal-symbol
+
+
+
+and it is written after the components of the rule. Its effect is to
+assign the rule the precedence of terminal-symbol, overriding
+the precedence that would be deduced for it in the ordinary way. The
+altered rule precedence then affects how conflicts involving that rule
+are resolved (see section Operator Precedence).
+
+
+
+Here is how %prec solves the problem of unary minus. First, declare
+a precedence for a fictitious terminal symbol named UMINUS. There
+are no tokens of this type, but the symbol serves to stand for its
+precedence:
+
+
+
+
+...
+%left '+' '-'
+%left '*'
+%left UMINUS
+
+
+
+Now the precedence of UMINUS can be used in specific rules:
+
+
+
+
+The function yyparse is implemented using a finite-state machine.
+The values pushed on the parser stack are not simply token type codes; they
+represent the entire sequence of terminal and nonterminal symbols at or
+near the top of the stack. The current state collects all the information
+about previous input which is relevant to deciding what to do next.
+
+
+
+Each time a look-ahead token is read, the current parser state together
+with the type of look-ahead token are looked up in a table. This table
+entry can say, "Shift the look-ahead token." In this case, it also
+specifies the new parser state, which is pushed onto the top of the
+parser stack. Or it can say, "Reduce using rule number n."
+This means that a certain number of tokens or groupings are taken off
+the top of the stack, and replaced by one grouping. In other words,
+that number of states are popped from the stack, and one new state is
+pushed.
+
+
+
+There is one other alternative: the table can say that the look-ahead token
+is erroneous in the current state. This causes error processing to begin
+(see section Error Recovery).
+
+
+
+
+
+A reduce/reduce conflict occurs if there are two or more rules that apply
+to the same sequence of input. This usually indicates a serious error
+in the grammar.
+
+
+
+For example, here is an erroneous attempt to define a sequence
+of zero or more word groupings.
+
+
+
+
+The error is an ambiguity: there is more than one way to parse a single
+word into a sequence. It could be reduced to a
+maybeword and then into a sequence via the second rule.
+Alternatively, nothing-at-all could be reduced into a sequence
+via the first rule, and this could be combined with the word
+using the third rule for sequence.
+
+
+
+There is also more than one way to reduce nothing-at-all into a
+sequence. This can be done directly via the first rule,
+or indirectly via maybeword and then the second rule.
+
+
+
+You might think that this is a distinction without a difference, because it
+does not change whether any particular input is valid or not. But it does
+affect which actions are run. One parsing order runs the second rule's
+action; the other runs the first rule's action and the third rule's action.
+In this example, the output of the program changes.
+
+
+
+Bison resolves a reduce/reduce conflict by choosing to use the rule that
+appears first in the grammar, but it is very risky to rely on this. Every
+reduce/reduce conflict must be studied and usually eliminated. Here is the
+proper way to define sequence:
+
+
+
+
+The intention here is to define a sequence which can contain either
+word or redirect groupings. The individual definitions of
+sequence, words and redirects are error-free, but the
+three together make a subtle ambiguity: even an empty input can be parsed
+in infinitely many ways!
+
+
+
+Consider: nothing-at-all could be a words. Or it could be two
+words in a row, or three, or any number. It could equally well be a
+redirects, or two, or any number. Or it could be a words
+followed by three redirects and another words. And so on.
+
+
+
+Here are two ways to correct these rules. First, to make it a single level
+of sequence:
+
+
+
+
+Sometimes reduce/reduce conflicts can occur that don't look warranted.
+Here is an example:
+
+
+
+
+%token ID
+
+%%
+def: param_spec return_spec ','
+ ;
+param_spec:
+ type
+ | name_list ':' type
+ ;
+return_spec:
+ type
+ | name ':' type
+ ;
+type: ID
+ ;
+name: ID
+ ;
+name_list:
+ name
+ | name ',' name_list
+ ;
+
+
+
+It would seem that this grammar can be parsed with only a single token
+of look-ahead: when a param_spec is being read, an ID is
+a name if a comma or colon follows, or a type if another
+ID follows. In other words, this grammar is LR(1).
+
+
+
+
+
+However, Bison, like most parser generators, cannot actually handle all
+LR(1) grammars. In this grammar, two contexts, that after an ID
+at the beginning of a param_spec and likewise at the beginning of
+a return_spec, are similar enough that Bison assumes they are the
+same. They appear similar because the same set of rules would be
+active--the rule for reducing to a name and that for reducing to
+a type. Bison is unable to determine at that stage of processing
+that the rules would require different look-ahead tokens in the two
+contexts, so it makes a single parser state for them both. Combining
+the two contexts causes a conflict later. In parser terminology, this
+occurrence means that the grammar is not LALR(1).
+
+
+
+In general, it is better to fix deficiencies than to document them. But
+this particular deficiency is intrinsically hard to fix; parser
+generators that can handle LR(1) grammars are hard to write and tend to
+produce parsers that are very large. In practice, Bison is more useful
+as it is now.
+
+
+
+When the problem arises, you can often fix it by identifying the two
+parser states that are being confused, and adding something to make them
+look distinct. In the above example, adding one rule to
+return_spec as follows makes the problem go away:
+
+
+
+
+%token BOGUS
+...
+%%
+...
+return_spec:
+ type
+ | name ':' type
+ /* This rule is never used. */
+ | ID BOGUS
+ ;
+
+
+
+This corrects the problem because it introduces the possibility of an
+additional active rule in the context after the ID at the beginning of
+return_spec. This rule is not active in the corresponding context
+in a param_spec, so the two contexts receive distinct parser states.
+As long as the token BOGUS is never generated by yylex,
+the added rule cannot alter the way actual input is parsed.
+
+
+
+In this particular example, there is another way to solve the problem:
+rewrite the rule for return_spec to use ID directly
+instead of via name. This also causes the two confusing
+contexts to have different sets of active rules, because the one for
+return_spec activates the altered rule for return_spec
+rather than the one for name.
+
+
+
+
+param_spec:
+ type
+ | name_list ':' type
+ ;
+return_spec:
+ type
+ | ID ':' type
+ ;
+
+The Bison parser stack can overflow if too many tokens are shifted and
+not reduced. When this happens, the parser function yyparse
+returns a nonzero value, pausing only to call yyerror to report
+the overflow.
+
+
+
+
+By defining the macro YYMAXDEPTH, you can control how deep the
+parser stack can become before a stack overflow occurs. Define the
+macro with a value that is an integer. This value is the maximum number
+of tokens that can be shifted (and not reduced) before overflow.
+It must be a constant expression whose value is known at compile time.
+
+
+
+The stack space allowed is not necessarily allocated. If you specify a
+large value for YYMAXDEPTH, the parser actually allocates a small
+stack at first, and then makes it bigger by stages as needed. This
+increasing allocation happens automatically and silently. Therefore,
+you do not need to make YYMAXDEPTH painfully small merely to save
+space for ordinary inputs that do not need much stack.
+
+
+
+
+The default value of YYMAXDEPTH, if you do not define it, is
+10000.
+
+
+
+
+You can control how much stack is allocated initially by defining the
+macro YYINITDEPTH. This value too must be a compile-time
+constant integer. The default is 200.
+
+
+
+
+
+It is not usually acceptable to have a program terminate on a parse
+error. For example, a compiler should recover sufficiently to parse the
+rest of the input file and check it for errors; a calculator should accept
+another expression.
+
+
+
+In a simple interactive command parser where each input is one line, it may
+be sufficient to allow yyparse to return 1 on error and have the
+caller ignore the rest of the input line when that happens (and then call
+yyparse again). But this is inadequate for a compiler, because it
+forgets all the syntactic context leading up to the error. A syntax error
+deep within a function in the compiler input should not cause the compiler
+to treat the following line like the beginning of a source file.
+
+
+
+
+You can define how to recover from a syntax error by writing rules to
+recognize the special token error. This is a terminal symbol that
+is always defined (you need not declare it) and reserved for error
+handling. The Bison parser generates an error token whenever a
+syntax error happens; if you have provided a rule to recognize this token
+in the current context, the parse can continue.
+
+
+
+The fourth rule in this example says that an error followed by a newline
+makes a valid addition to any stmnts.
+
+
+
+What happens if a syntax error occurs in the middle of an exp? The
+error recovery rule, interpreted strictly, applies to the precise sequence
+of a stmnts, an error and a newline. If an error occurs in
+the middle of an exp, there will probably be some additional tokens
+and subexpressions on the stack after the last stmnts, and there
+will be tokens to read before the next newline. So the rule is not
+applicable in the ordinary way.
+
+
+
+But Bison can force the situation to fit the rule, by discarding part of
+the semantic context and part of the input. First it discards states and
+objects from the stack until it gets back to a state in which the
+error token is acceptable. (This means that the subexpressions
+already parsed are discarded, back to the last complete stmnts.) At
+this point the error token can be shifted. Then, if the old
+look-ahead token is not acceptable to be shifted next, the parser reads
+tokens and discards them until it finds a token which is acceptable. In
+this example, Bison reads and discards input until the next newline
+so that the fourth rule can apply.
+
+
+
+The choice of error rules in the grammar is a choice of strategies for
+error recovery. A simple and useful strategy is simply to skip the rest of
+the current input line or current statement if an error is detected:
+
+
+
+
+stmnt: error ';' /* on error, skip until ';' is read */
+
+
+
+It is also useful to recover to the matching close-delimiter of an
+opening-delimiter that has already been parsed. Otherwise the
+close-delimiter will probably appear to be unmatched, and generate another,
+spurious error message:
+
+
+
+
+Error recovery strategies are necessarily guesses. When they guess wrong,
+one syntax error often leads to another. In the above example, the error
+recovery rule guesses that an error is due to bad input within one
+stmnt. Suppose that instead a spurious semicolon is inserted in the
+middle of a valid stmnt. After the error recovery rule recovers
+from the first error, another syntax error will be found straightaway,
+since the text following the spurious semicolon is also an invalid
+stmnt.
+
+
+
+To prevent an outpouring of error messages, the parser will output no error
+message for another syntax error that happens shortly after the first; only
+after three consecutive input tokens have been successfully shifted will
+error messages resume.
+
+
+
+Note that rules which accept the error token may have actions, just
+as any other rules can.
+
+
+
+
+You can make error messages resume immediately by using the macro
+yyerrok in an action. If you do this in the error rule's action, no
+error messages will be suppressed. This macro requires no arguments;
+`yyerrok;' is a valid C statement.
+
+
+
+
+The previous look-ahead token is reanalyzed immediately after an error. If
+this is unacceptable, then the macro yyclearin may be used to clear
+this token. Write the statement `yyclearin;' in the error rule's
+action.
+
+
+
+For example, suppose that on a parse error, an error handling routine is
+called that advances the input stream to some point where parsing should
+once again commence. The next symbol returned by the lexical scanner is
+probably correct. The previous look-ahead token ought to be discarded
+with `yyclearin;'.
+
+
+
+
+The macro YYRECOVERING stands for an expression that has the
+value 1 when the parser is recovering from a syntax error, and 0 the
+rest of the time. A value of 1 indicates that error messages are
+currently suppressed for new syntax errors.
+
+
+
+
+
+The Bison paradigm is to parse tokens first, then group them into larger
+syntactic units. In many languages, the meaning of a token is affected by
+its context. Although this violates the Bison paradigm, certain techniques
+(known as kludges) may enable you to write Bison parsers for such
+languages.
+
+
+
+(Actually, "kludge" means any technique that gets its job done but is
+neither clean nor robust.)
+
+
+
+
+
+The C language has a context dependency: the way an identifier is used
+depends on what its current meaning is. For example, consider this:
+
+
+
+
+foo (x);
+
+
+
+This looks like a function call statement, but if foo is a typedef
+name, then this is actually a declaration of x. How can a Bison
+parser for C decide how to parse this input?
+
+
+
+The method used in GNU C is to have two different token types,
+IDENTIFIER and TYPENAME. When yylex finds an
+identifier, it looks up the current declaration of the identifier in order
+to decide which token type to return: TYPENAME if the identifier is
+declared as a typedef, IDENTIFIER otherwise.
+
+
+
+The grammar rules can then express the context dependency by the choice of
+token type to recognize. IDENTIFIER is accepted as an expression,
+but TYPENAME is not. TYPENAME can start a declaration, but
+IDENTIFIER cannot. In contexts where the meaning of the identifier
+is not significant, such as in declarations that can shadow a
+typedef name, either TYPENAME or IDENTIFIER is
+accepted--there is one rule for each of the two token types.
+
+
+
+This technique is simple to use if the decision of which kinds of
+identifiers to allow is made at a place close to where the identifier is
+parsed. But in C this is not always so: C allows a declaration to
+redeclare a typedef name provided an explicit type has been specified
+earlier:
+
+
+
+
+typedef int foo, bar, lose;
+static foo (bar); /* redeclare bar as static variable */
+static int foo (lose); /* redeclare foo as function */
+
+
+
+Unfortunately, the name being declared is separated from the declaration
+construct itself by a complicated syntactic structure--the "declarator".
+
+
+
+As a result, part of the Bison parser for C needs to be duplicated, with
+all the nonterminal names changed: once for parsing a declaration in
+which a typedef name can be redefined, and once for parsing a
+declaration in which that can't be done. Here is a part of the
+duplication, with actions omitted for brevity:
+
+
+
+
+Here initdcl can redeclare a typedef name, but notype_initdcl
+cannot. The distinction between declarator and
+notype_declarator is the same sort of thing.
+
+
+
+There is some similarity between this technique and a lexical tie-in
+(described next), in that information which alters the lexical analysis is
+changed during parsing by other parts of the program. The difference is
+here the information is global, and is used for other purposes in the
+program. A true lexical tie-in has a special-purpose flag controlled by
+the syntactic context.
+
+
+
+
+
+One way to handle context-dependency is the lexical tie-in: a flag
+which is set by Bison actions, whose purpose is to alter the way tokens are
+parsed.
+
+
+
+For example, suppose we have a language vaguely like C, but with a special
+construct `hex (hex-expr)'. After the keyword hex comes
+an expression in parentheses in which all integers are hexadecimal. In
+particular, the token `a1b' must be treated as an integer rather than
+as an identifier if it appears in that context. Here is how you can do it:
+
+
+
+
+Here we assume that yylex looks at the value of hexflag; when
+it is nonzero, all integers are parsed in hexadecimal, and tokens starting
+with letters are parsed as integers if possible.
+
+
+
+The declaration of hexflag shown in the C declarations section of
+the parser file is needed to make it accessible to the actions
+(see section The C Declarations Section). You must also write the code in yylex
+to obey the flag.
+
+
+
+
+
+Lexical tie-ins make strict demands on any error recovery rules you have.
+See section Error Recovery.
+
+
+
+The reason for this is that the purpose of an error recovery rule is to
+abort the parsing of one construct and resume in some larger construct.
+For example, in C-like languages, a typical error recovery rule is to skip
+tokens until the next semicolon, and then start a new statement, like this:
+
+
+
+
+If there is a syntax error in the middle of a `hex (expr)'
+construct, this error rule will apply, and then the action for the
+completed `hex (expr)' will never run. So hexflag would
+remain set for the entire rest of the input, or until the next hex
+keyword, causing identifiers to be misinterpreted as integers.
+
+
+
+To avoid this problem the error recovery rule itself clears hexflag.
+
+
+
+There may also be an error recovery rule that works within expressions.
+For example, there could be a rule which applies within parentheses
+and skips to the close-parenthesis:
+
+
+
+
+If this rule acts within the hex construct, it is not going to abort
+that construct (since it applies to an inner level of parentheses within
+the construct). Therefore, it should not clear the flag: the rest of
+the hex construct should be parsed with the flag still in effect.
+
+
+
+What if there is an error recovery rule which might abort out of the
+hex construct or might not, depending on circumstances? There is no
+way you can write the action to determine whether a hex construct is
+being aborted or not. So if you are using a lexical tie-in, you had better
+make sure your error recovery rules are not of this kind. Each rule must
+be such that you can be sure that it always will, or always won't, have to
+clear the flag.
+
+
+
+
+
+If a Bison grammar compiles properly but doesn't do what you want when it
+runs, the yydebug parser-trace feature can help you figure out why.
+
+
+
+To enable compilation of trace facilities, you must define the macro
+YYDEBUG when you compile the parser. You could use
+`-DYYDEBUG=1' as a compiler option or you could put `#define
+YYDEBUG 1' in the C declarations section of the grammar file
+(see section The C Declarations Section). Alternatively, use the `-t' option when
+you run Bison (see section Invoking Bison). We always define YYDEBUG so that
+debugging is always possible.
+
+
+
+The trace facility uses stderr, so you must add #include
+<stdio.h> to the C declarations section unless it is already there.
+
+
+
+Once you have compiled the program with trace facilities, the way to
+request a trace is to store a nonzero value in the variable yydebug.
+You can do this by making the C code do it (in main, perhaps), or
+you can alter the value with a C debugger.
+
+
+
+Each step taken by the parser when yydebug is nonzero produces a
+line or two of trace information, written on stderr. The trace
+messages tell you these things:
+
+
+
+
+
+
+Each time the parser calls yylex, what kind of token was read.
+
+
+
+Each time a token is shifted, the depth and complete contents of the
+state stack (see section Parser States).
+
+
+
+Each time a rule is reduced, which rule it is, and the complete contents
+of the state stack afterward.
+
+
+
+To make sense of this information, it helps to refer to the listing file
+produced by the Bison `-v' option (see section Invoking Bison). This file
+shows the meaning of each state in terms of positions in various rules, and
+also what each state will do with each possible input token. As you read
+the successive trace messages, you can see that the parser is functioning
+according to its specification in the listing file. Eventually you will
+arrive at the place where something undesirable happens, and you will see
+which parts of the grammar are to blame.
+
+
+
+The parser file is a C program and you can use C debuggers on it, but it's
+not easy to interpret what it is doing. The parser function is a
+finite-state machine interpreter, and aside from the actions it executes
+the same code over and over. Only the values of variables show where in
+the grammar it is working.
+
+
+
+
+The debugging information normally gives the token type of each token
+read, but not its semantic value. You can optionally define a macro
+named YYPRINT to provide a way to print the value. If you define
+YYPRINT, it should take three arguments. The parser will pass a
+standard I/O stream, the numeric code for the token type, and the token
+value (from yylval).
+
+
+
+Here is an example of YYPRINT suitable for the multi-function
+calculator (see section Declarations for mfcalc):
+
+
+
+
+The usual way to invoke Bison is as follows:
+
+
+
+
+bison infile
+
+
+
+Here infile is the grammar file name, which usually ends in
+`.y'. The parser file's name is made by replacing the `.y'
+with `.tab.c'. Thus, the `bison foo.y' filename yields
+`foo.tab.c', and the `bison hack/foo.y' filename yields
+`hack/foo.tab.c'. It's is also possible, in case you are writting
+C++ code instead of C in your grammar file, to name it `foo.ypp'
+or `foo.y++'. Then, the output files will take an extention like
+the given one as input (repectively `foo.tab.cpp' and `foo.tab.c++').
+This feature takes effect with all options that manipulate filenames like
+`-o' or `-d'.
+
+
+
+For example :
+
+
+
+
+bison -d infile.yxx
+
+
+
+will produce `infile.tab.cxx' and `infile.tab.hxx'. and
+
+
+
+
+bison -d infile.y -o output.c++
+
+
+
+will produce `output.c++' and `outfile.h++'.
+
+
+
+
+
+Bison supports both traditional single-letter options and mnemonic long
+option names. Long option names are indicated with `--' instead of
+`-'. Abbreviations for option names are allowed as long as they
+are unique. When a long option takes an argument, like
+`--file-prefix', connect the option name and the argument with
+`='.
+
+
+
+Here is a list of options that can be used with Bison, alphabetized by
+short option. It is followed by a cross key alphabetized by long
+option.
+
+
+
+Operations modes:
+
+
+
@option{-h}
+
+
@option{--help}
+
+Print a summary of the command-line options to Bison and exit.
+
+
@option{-V}
+
+
@option{--version}
+
+Print the version number of Bison and exit.
+
+
@option{-y}
+
+
@option{--yacc}
+
+
@option{--fixed-output-files}
+
+Equivalent to `-o y.tab.c'; the parser output file is called
+`y.tab.c', and the other outputs are called `y.output' and
+`y.tab.h'. The purpose of this option is to imitate Yacc's output
+file name conventions. Thus, the following shell script can substitute
+for Yacc:
+
+
+bison -y $*
+
+
+
+
+
+Tuning the parser:
+
+
+
+
+
@option{-S file}
+
+
@option{--skeleton=file}
+
+Specify the skeleton to use. You probably don't need this option unless
+you are developing Bison.
+
+
@option{-t}
+
+
@option{--debug}
+
+Output a definition of the macro YYDEBUG into the parser file, so
+that the debugging facilities are compiled. See section Debugging Your Parser.
+
+
+Rename the external symbols used in the parser so that they start with
+prefix instead of `yy'. The precise list of symbols renamed
+is yyparse, yylex, yyerror, yynerrs,
+yylval, yychar and yydebug.
+
+For example, if you use `-p c', the names become cparse,
+clex, and so on.
+
+See section Multiple Parsers in the Same Program.
+
+
@option{-l}
+
+
@option{--no-lines}
+
+Don't put any #line preprocessor commands in the parser file.
+Ordinarily Bison puts them in the parser file so that the C compiler
+and debuggers will associate errors with your source file, the
+grammar file. This option causes them to associate errors with the
+parser file, treating it as an independent source file in its own right.
+
+
+Pretend that %verbose was specified, i.e., write an extra output
+file containing macro definitions for the token type names defined in
+the grammar and the semantic value type YYSTYPE, as well as a few
+extern variable declarations. See section Bison Declaration Summary.
+
+
@option{--defines=defines-file}
+
+The behaviour of --defines is the same than `-d'. The only
+difference is that it has an optionnal argument which is the name of
+the output filename.
+
+
@option{-b file-prefix}
+
+
@option{--file-prefix=prefix}
+
+Specify a prefix to use for all Bison output file names. The names are
+chosen as if the input file were named `prefix.c'.
+
+
@option{-v}
+
+
@option{--verbose}
+
+Pretend that %verbose was specified, i.e, write an extra output
+file containing verbose descriptions of the grammar and
+parser. See section Bison Declaration Summary, for more.
+
+
@option{-o outfile}
+
+
@option{--output-file=outfile}
+
+Specify the name outfile for the parser file.
+
+The other output files' names are constructed from outfile
+as described under the `-v' and `-d' options.
+
+
@option{-g}
+
+Output a VCG definition of the LALR(1) grammar automaton computed by
+Bison. If the grammar file is `foo.y', the VCG output file will
+be `foo.vcg'.
+
+
@option{--graph=graph-file}
+
+The behaviour of --graph is the same than `-g'. The only
+difference is that it has an optionnal argument which is the name of
+the output graph filename.
+
+Here is a list of environment variables which affect the way Bison
+runs.
+
+
+
+
+
`BISON_SIMPLE'
+
+
`BISON_HAIRY'
+
+Much of the parser generated by Bison is copied verbatim from a file
+called `bison.simple'. If Bison cannot find that file, or if you
+would like to direct Bison to use a different copy, setting the
+environment variable BISON_SIMPLE to the path of the file will
+cause Bison to use that copy instead.
+
+When the `%semantic_parser' declaration is used, Bison copies from
+a file called `bison.hairy' instead. The location of this file can
+also be specified or overridden in a similar fashion, with the
+BISON_HAIRY environment variable.
+
+
+The command line syntax for Bison on VMS is a variant of the usual
+Bison command syntax--adapted to fit VMS conventions.
+
+
+
+To find the VMS equivalent for any Bison option, start with the long
+option, and substitute a `/' for the leading `--', and
+substitute a `_' for each `-' in the name of the long option.
+For example, the following invocation under VMS:
+
+
+
+
+bison /debug/name_prefix=bar foo.y
+
+
+
+is equivalent to the following command under POSIX.
+
+
+
+
+bison --debug --name-prefix=bar foo.y
+
+
+
+The VMS file system does not permit filenames such as
+`foo.tab.c'. In the above example, the output file
+would instead be named `foo_tab.c'.
+
+
+
+
+
+A token name reserved for error recovery. This token may be used in
+grammar rules so as to allow the Bison parser to recognize an error in
+the grammar without halting the process. In effect, a sentence
+containing an error may be recognized as valid. On a parse error, the
+token error becomes the current look-ahead token. Actions
+corresponding to error are then executed, and the look-ahead
+token is reset to the token that originally caused the violation.
+See section Error Recovery.
+
+
YYABORT
+
+Macro to pretend that an unrecoverable syntax error has occurred, by
+making yyparse return 1 immediately. The error reporting
+function yyerror is not called. See section The Parser Function yyparse.
+
+
YYACCEPT
+
+Macro to pretend that a complete utterance of the language has been
+read, by making yyparse return 0 immediately.
+See section The Parser Function yyparse.
+
+
+Macro to pretend that a syntax error has just been detected: call
+yyerror and then perform normal error recovery if possible
+(see section Error Recovery), or (if recovery is impossible) make
+yyparse return 1. See section Error Recovery.
+
+
YYERROR_VERBOSE
+
+Macro that you define with #define in the Bison declarations
+section to request verbose, specific error message strings when
+yyerror is called.
+
+
+Macro for specifying an extra argument (or list of extra arguments) for
+yyparse to pass to yylex. See section Calling Conventions for Pure Parsers.
+
+
YYLTYPE
+
+Macro for the data type of yylloc; a structure with four
+members. See section Data Type of Locations.
+
+
+Macro used to control the use of alloca. If defined to `0',
+the parser will not use alloca but malloc when trying to
+grow its internal stacks. Do not define YYSTACK_USE_ALLOCA
+to anything else.
+
+
+External integer variable that contains the integer value of the current
+look-ahead token. (In a pure parser, it is a local variable within
+yyparse.) Error-recovery rule actions may examine this variable.
+See section Special Features for Use in Actions.
+
+
yyclearin
+
+Macro used in error-recovery rule actions. It clears the previous
+look-ahead token. See section Error Recovery.
+
+
yydebug
+
+External integer variable set to zero by default. If yydebug
+is given a nonzero value, the parser will output information on input
+symbols and parser action. See section Debugging Your Parser.
+
+
yyerrok
+
+Macro to cause parser to recover immediately to its normal mode
+after a parse error. See section Error Recovery.
+
+
yyerror
+
+User-supplied function to be called by yyparse on error. The
+function receives one argument, a pointer to a character string
+containing an error message. See section The Error Reporting Function yyerror.
+
+
yylex
+
+User-supplied lexical analyzer function, called with no arguments
+to get the next token. See section The Lexical Analyzer Function yylex.
+
+
yylval
+
+External variable in which yylex should place the semantic
+value associated with a token. (In a pure parser, it is a local
+variable within yyparse, and its address is passed to
+yylex.) See section Semantic Values of Tokens.
+
+
yylloc
+
+External variable in which yylex should place the line and column
+numbers associated with a token. (In a pure parser, it is a local
+variable within yyparse, and its address is passed to
+yylex.) You can ignore this variable if you don't use the
+`@' feature in the grammar actions. See section Textual Positions of Tokens.
+
+
yynerrs
+
+Global variable which Bison increments each time there is a parse error.
+(In a pure parser, it is a local variable within yyparse.)
+See section The Error Reporting Function yyerror.
+
+
yyparse
+
+The parser function produced by Bison; call this function to start
+parsing. See section The Parser Function yyparse.
+
+
+Bison declaration to request a pure (reentrant) parser.
+See section A Pure (Reentrant) Parser.
+
+
%right
+
+Bison declaration to assign right associativity to token(s).
+See section Operator Precedence.
+
+
%start
+
+Bison declaration to specify the start symbol. See section The Start-Symbol.
+
+
%token
+
+Bison declaration to declare token(s) without specifying precedence.
+See section Token Type Names.
+
+
%token_table
+
+Bison declaration to include a token name table in the parser file.
+See section Bison Declaration Summary.
+
+
%type
+
+Bison declaration to declare nonterminals. See section Nonterminal Symbols.
+
+
%union
+
+Bison declaration to specify several possible data types for semantic
+values. See section The Collection of Value Types.
+
+
+
+These are the punctuation and delimiters used in Bison input:
+
+
+
+
+
`%%'
+
+Delimiter used to separate the grammar rule section from the
+Bison declarations section or the additional C code section.
+See section The Overall Layout of a Bison Grammar.
+
+
`%{ %}'
+
+All code listed between `%{' and `%}' is copied directly to
+the output file uninterpreted. Such code forms the "C declarations"
+section of the input file. See section Outline of a Bison Grammar.
+
+
+Formal method of specifying context-free grammars. BNF was first used
+in the ALGOL-60 report, 1963. See section Languages and Context-Free Grammars.
+
+
Context-free grammars
+
+Grammars specified as rules that can be applied regardless of context.
+Thus, if there is a rule which says that an integer can be used as an
+expression, integers are allowed anywhere an expression is
+permitted. See section Languages and Context-Free Grammars.
+
+
Dynamic allocation
+
+Allocation of memory that occurs during execution, rather than at
+compile time or on entry to a function.
+
+
Empty string
+
+Analogous to the empty set in set theory, the empty string is a
+character string of length zero.
+
+
Finite-state stack machine
+
+A "machine" that has discrete states in which it is said to exist at
+each instant in time. As input to the machine is processed, the
+machine moves from state to state as specified by the logic of the
+machine. In the case of the parser, the input is the language being
+parsed, and the states correspond to various stages in the grammar
+rules. See section The Bison Parser Algorithm.
+
+
Grouping
+
+A language construct that is (in general) grammatically divisible;
+for example, `expression' or `declaration' in C.
+See section Languages and Context-Free Grammars.
+
+
Infix operator
+
+An arithmetic operator that is placed between the operands on which it
+performs some operation.
+
+
Input stream
+
+A continuous flow of data between devices or programs.
+
+
Language construct
+
+One of the typical usage schemas of the language. For example, one of
+the constructs of the C language is the if statement.
+See section Languages and Context-Free Grammars.
+
+
Left associativity
+
+Operators having left associativity are analyzed from left to right:
+`a+b+c' first computes `a+b' and then combines with
+`c'. See section Operator Precedence.
+
+
Left recursion
+
+A rule whose result symbol is also its first component symbol; for
+example, `expseq1 : expseq1 ',' exp;'. See section Recursive Rules.
+
+
Left-to-right parsing
+
+Parsing a sentence of a language by analyzing it token by token from
+left to right. See section The Bison Parser Algorithm.
+
+
+A token already read but not yet shifted. See section Look-Ahead Tokens.
+
+
LALR(1)
+
+The class of context-free grammars that Bison (like most other parser
+generators) can handle; a subset of LR(1). See section Mysterious Reduce/Reduce Conflicts.
+
+
LR(1)
+
+The class of context-free grammars in which at most one token of
+look-ahead is needed to disambiguate the parsing of any piece of input.
+
+
Nonterminal symbol
+
+A grammar symbol standing for a grammatical construct that can
+be expressed through rules in terms of smaller constructs; in other
+words, a construct that is not a token. See section Symbols, Terminal and Nonterminal.
+
+
Parse error
+
+An error encountered during parsing of an input stream due to invalid
+syntax. See section Error Recovery.
+
+
Parser
+
+A function that recognizes valid sentences of a language by analyzing
+the syntax structure of a set of tokens passed to it from a lexical
+analyzer.
+
+
Postfix operator
+
+An arithmetic operator that is placed after the operands upon which it
+performs some operation.
+
+
Reduction
+
+Replacing a string of nonterminals and/or terminals with a single
+nonterminal, according to a grammar rule. See section The Bison Parser Algorithm.
+
+
Reentrant
+
+A reentrant subprogram is a subprogram which can be in invoked any
+number of times in parallel, without interference between the various
+invocations. See section A Pure (Reentrant) Parser.
+
+
Reverse polish notation
+
+A language in which all operators are postfix operators.
+
+
Right recursion
+
+A rule whose result symbol is also its last component symbol; for
+example, `expseq1: exp ',' expseq1;'. See section Recursive Rules.
+
+
Semantics
+
+In computer languages, the semantics are specified by the actions
+taken for each instance of the language, i.e., the meaning of
+each statement. See section Defining Language Semantics.
+
+
Shift
+
+A parser is said to shift when it makes the choice of analyzing
+further input from the stream rather than reducing immediately some
+already-recognized rule. See section The Bison Parser Algorithm.
+
+
+The nonterminal symbol that stands for a complete valid utterance in
+the language being parsed. The start symbol is usually listed as the
+first nonterminal symbol in a language specification.
+See section The Start-Symbol.
+
+
Symbol table
+
+A data structure where symbol names and associated data are stored
+during parsing to allow for recognition and use of existing
+information in repeated uses of a symbol. See section Multi-Function Calculator: mfcalc.
+
+
Token
+
+A basic, grammatically indivisible unit of a language. The symbol
+that describes a token in the grammar is a terminal symbol.
+The input of the Bison parser is a stream of tokens which comes from
+the lexical analyzer. See section Symbols, Terminal and Nonterminal.
+
+
Terminal symbol
+
+A grammar symbol that has no rules in the grammar and therefore is
+grammatically indivisible. The piece of text it represents is a token.
+See section Languages and Context-Free Grammars.
+
+Copyright (C) 2000 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+
+
+
+
+
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document free in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially. Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of "copyleft", which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+
+
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The "Document", below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as "you".
+
+A "Modified Version" of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A "Secondary Section" is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The "Invariant Sections" are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+The "Cover Texts" are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+A "Transparent" copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not "Transparent" is called "Opaque".
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format,
+@acronym{SGML} or @acronym{XML} using a publicly available
+@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
+for human modification. Opaque formats include PostScript,
+@acronym{PDF}, proprietary formats that can be read and edited only by
+proprietary word processors, @acronym{SGML} or @acronym{XML} for which
+the @acronym{DTD} and/or processing tools are not generally available,
+and the machine-generated @acronym{HTML} produced by some word
+processors for output purposes only.
+
+The "Title Page" means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, "Title Page" means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+
+
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+
+
+COPYING IN QUANTITY
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+
+
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+
+
+
+
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+
+
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has less than five).
+
+
+
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+
+
+Preserve all the copyright notices of the Document.
+
+
+
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+
+
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+
+
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+
+
+Include an unaltered copy of this License.
+
+
+
+Preserve the section entitled "History", and its title, and add to
+it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section entitled "History" in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+
+
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the "History" section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+
+
+In any section entitled "Acknowledgments" or "Dedications",
+preserve the section's title, and preserve in the section all the
+substance and tone of each of the contributor acknowledgments
+and/or dedications given therein.
+
+
+
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
+
+
+Delete any section entitled "Endorsements". Such a section
+may not be included in the Modified Version.
+
+
+
+Do not retitle any existing section as "Endorsements"
+or to conflict in title with any Invariant Section.
+
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled "Endorsements", provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+
+
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled "History"
+in the various original documents, forming one section entitled
+"History"; likewise combine any sections entitled "Acknowledgments",
+and any sections entitled "Dedications". You must delete all sections
+entitled "Endorsements."
+
+
+
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+
+
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an "aggregate", and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
+
+
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
+
+
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+
+
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+http://www.gnu.org/copyleft/.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+
+
+
+ Copyright (C) yearyour name.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1
+ or any later version published by the Free Software Foundation;
+ with the Invariant Sections being list their titles, with the
+ Front-Cover Texts being list, and with the Back-Cover Texts being list.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
+
+
+
+If you have no Invariant Sections, write "with no Invariant Sections"
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write "no Front-Cover Texts" instead of
+"Front-Cover Texts being list"; likewise for Back-Cover Texts.
+
+
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+
+
+
+
+
+flex
+is a tool for generating
+scanners.
+A scanner is a program which recognizes lexical patterns in text.
+The
+flex
+program
+reads
+the given input files, or its standard input if no file names are given,
+for a description of a scanner to generate. The description is in
+the form of pairs
+of regular expressions and C code, called
+rules. flex
+generates as output a C source file,
+`lex.yy.c' by default,
+which defines a routine
+yylex().
+This file is compiled and linked with the
+flex runtime library
+library to produce an executable. When the executable is run,
+it analyzes its input for occurrences
+of the regular expressions. Whenever it finds one, it executes
+the corresponding C code.
+
+
+
+
+
+First some simple examples to get the flavor of how one uses
+flex.
+The following
+flex
+input specifies a scanner which whenever it encounters the string
+`username' will replace it with the user's login name:
+
+
+
+
+By default, any text not matched by a
+flex
+scanner
+is copied to the output, so the net effect of this scanner is
+to copy its input file to its output with each occurrence
+of `username' expanded.
+In this input, there is just one rule. `username' is the
+pattern
+and the `printf' is the
+action.
+The `%%' symbol marks the beginning of the rules.
+
+
+
+This scanner counts the number of characters and the number
+of lines in its input (it produces no output other than the
+final report on the counts). The first line
+declares two globals, num_lines and num_chars, which are accessible
+both inside
+yylex()
+and in the
+main()
+routine declared after the second `%%'. There are two rules, one
+which matches a newline (`\n') and increments both the line count and
+the character count, and one which matches any character other than
+a newline (indicated by the `.' regular expression).
+
+
+
+A somewhat more complicated example:
+
+
+
+
+
+
+@verbatim
+ /* scanner for a toy Pascal-like language */
+
+ %{
+ /* need this for the call to atof() below */
+ #include math.h>
+ %}
+
+ DIGIT [0-9]
+ ID [a-z][a-z0-9]*
+
+ %%
+
+ {DIGIT}+ {
+ printf( "An integer: %s (%d)\n", yytext,
+ atoi( yytext ) );
+ }
+
+ {DIGIT}+"."{DIGIT}* {
+ printf( "A float: %s (%g)\n", yytext,
+ atof( yytext ) );
+ }
+
+ if|then|begin|end|procedure|function {
+ printf( "A keyword: %s\n", yytext );
+ }
+
+ {ID} printf( "An identifier: %s\n", yytext );
+
+ "+"|"-"|"*"|"/" printf( "An operator: %s\n", yytext );
+
+ "{"[\^{}}\n]*"}" /* eat up one-line comments */
+
+ [ \t\n]+ /* eat up whitespace */
+
+ . printf( "Unrecognized character: %s\n", yytext );
+
+ %%
+
+ main( argc, argv )
+ int argc;
+ char **argv;
+ {
+ ++argv, --argc; /* skip over program name */
+ if ( argc > 0 )
+ yyin = fopen( argv[0], "r" );
+ else
+ yyin = stdin;
+
+ yylex();
+ }
+
+
+
+This is the beginnings of a simple scanner for a language like
+Pascal. It identifies different types of
+tokens
+and reports on what it has seen.
+
+
+
+The details of this example will be explained in the following
+sections.
+
+
+
+
+
+The
+definitions
+section contains declarations of simple
+name
+definitions to simplify the scanner specification, and declarations of
+start conditions,
+which are explained in a later section.
+
+
+
+
+Name definitions have the form:
+
+
+
+
+@verbatim
+ name definition
+
+
+
+The `name' is a word beginning with a letter or an underscore (`_')
+followed by zero or more letters, digits, `_', or `-' (dash).
+The definition is taken to begin at the first non-whitespace character
+following the name and continuing to the end of the line.
+The definition can subsequently be referred to using `{name}', which
+will expand to `(definition)'. For example,
+
+
+
+
+
+
+@verbatim
+ DIGIT [0-9]
+ ID [a-z][a-z0-9]*
+
+
+
+Defines `DIGIT' to be a regular expression which matches a
+single digit, and
+`ID' to be a regular expression which matches a letter
+followed by zero-or-more letters-or-digits.
+A subsequent reference to
+
+
+
+
+
+
+@verbatim
+ {DIGIT}+"."{DIGIT}*
+
+
+
+is identical to
+
+
+
+
+@verbatim
+ ([0-9])+"."([0-9])*
+
+
+
+and matches one-or-more digits followed by a '.' followed
+by zero-or-more digits.
+
+
+
+An unindented comment (i.e., a line
+beginning with `/*') is copied verbatim to the output up
+to the next `*/'.
+
+
+
+
+
+
+
+Any
+indented
+text or text enclosed in
+`%{'
+and
+`%}'
+is also copied verbatim to the output (with the %{ and %} symbols removed).
+The %{ and %} symbols must appear unindented on lines by themselves.
+
+
+
+
+
+The
+rules
+section of the
+flex
+input contains a series of rules of the form:
+
+
+
+
+@verbatim
+ pattern action
+
+
+
+where the pattern must be unindented and the action must begin
+on the same line.
+
+
+
+See section Patterns, for a further description of patterns and actions.
+
+
+
+In the rules section,
+any indented or %{ %} enclosed text appearing before the
+first rule may be used to declare variables
+which are local to the scanning routine and (after the declarations)
+code which is to be executed whenever the scanning routine is entered.
+Other indented or %{ %} text in the rule section is still copied to the output,
+but its meaning is not well-defined and it may well cause compile-time
+errors (this feature is present for
+POSIX
+compliance. See section Incompatibilities with Lex and Posix, for other such features).
+
+
+
+Any
+indented
+text or text enclosed in
+`%{'
+and
+`%}'
+is copied verbatim to the output (with the %{ and %} symbols removed).
+The %{ and %} symbols must appear unindented on lines by themselves.
+
+
+
+
+
+The user code section is simply copied to
+`lex.yy.c'
+verbatim.
+It is used for companion routines which call or are called
+by the scanner. The presence of this section is optional;
+if it is missing, the second
+`%%'
+in the input file may be skipped, too.
+
+
+
+
+
+Flex supports C-style comments, that is, anything between /* and */ is
+considered a comment. Whenever flex encounters a comment, it copies
+the entire comment verbatim to the generated source code. Comments
+may appear just about anywhere, but with the following exceptions:
+
+
+
+
+
Comments may not appear in the Rules Section wherever flex is expecting
+
+a regular expression. This means comments may not appear at the beginning of
+a line, or immediately following a list of scanner states.
+
Comments may not appear on an `%option' line in the Definitions Section.
+
+
+
+
+If you want to follow a simple rule, then always begin a comment on a new line,
+with one or more whitespace characters before the initial `/*').
+This rule will work anywhere in the input file.
+
+
+
+All the comments in the following example are OK:
+
+
+
+if X is `a', `b', `f', `n', `r', `t', or `v',
+then the ANSI-C interpretation of `\x'.
+Otherwise, a literal `X' (used to escape
+operators such as `*')
+
+
+
`\0'
+
+a NUL character (ASCII code 0)
+
+
`\123'
+
+the character with octal value 123
+
+
`\x2a'
+
+the character with hexadecimal value 2a
+
+
`(r)'
+
+match an r; parentheses are used to override
+ precedence (see below)
+
+
`rs'
+
+the regular expression r followed by the
+regular expression s; called concatenation
+
+
`r|s'
+
+either an r or an s
+
+
+
`r/s'
+
+an r but only if it is followed by an s. The
+text matched by s is included when determining
+whether this rule is the longest match,
+but is then returned to the input before
+the action is executed. So the action only
+sees the text matched by r. This type
+of pattern is called trailing context.
+(There are some combinations of r/s that flex
+cannot match correctly. See section Limitations,
+regarding
+dangerous trailing context.)
+
+
+
`^r'
+
+an r, but only at the beginning of a line (i.e.,
+when just starting to scan, or right after a
+newline has been scanned).
+
+
+
`r$'
+
+an r, but only at the end of a line (i.e., just
+before a newline). Equivalent to `r/\n'.
+
+Note that flex's notion of "newline" is exactly
+whatever the C compiler used to compile flex
+interprets `\n' as; in particular, on some DOS
+systems you must either filter out `\r's in the
+input yourself, or explicitly use `r/\r\n' for `r$'.
+
+
+
`<s>r'
+
+an r, but only in start condition s (see
+section Start Conditions for discussion of start conditions).
+
+
`<s1,s2,s3>r'
+
+same, but in any of start conditions s1,
+s2, or s3.
+
+
`<*>r'
+
+an r in any start condition, even an exclusive one.
+
+
+
`<<EOF>>'
+
+an end-of-file.
+
+
`<s1,s2><<EOF>>'
+
+an end-of-file when in start condition s1 or s2
+
+
+
+Note that inside of a character class, all regular expression operators
+lose their special meaning except escape (`\') and the character class
+operators, `-', `]]', and, at the beginning of the class, `^'.
+
+
+
+
+The regular expressions listed above are grouped according to
+precedence, from highest precedence at the top to lowest at the bottom.
+Those grouped together have equal precedence (see special note on the
+precedence of the repeat operator, `{}', under the documentation
+for the `--posix' POSIX compliance option). For example,
+
+
+
+
+
+
+@verbatim
+ foo|bar*
+
+
+
+is the same as
+
+
+
+
+@verbatim
+ (foo)|(ba(r*))
+
+
+
+since the '*' operator has higher precedence than concatenation, and
+concatenation higher than alternation ('|'). This pattern therefore
+matches either the string `foo'or the string
+`ba' followed by zero-or-more r's. To match `foo' or
+zero-or-more repetitions of the string `bar', use:
+
+
+
+
+@verbatim
+ foo|(bar)*
+
+
+
+And to match a sequence of zero or more repetitions of `foo' and
+`bar':
+
+
+
+
+
+
+@verbatim
+ (foo|bar)*
+
+
+
+
+In addition to characters and ranges of characters, character classes
+can also contain character class expressions. These are
+expressions enclosed inside `[': and `:]' delimiters (which
+themselves must appear between the `[' and `]' of the
+character class. Other elements may occur inside the character class,
+too). The valid expressions are:
+
+
+
+These expressions all designate a set of characters equivalent to
+the corresponding standard C
+isXXX
+function. For example,
+`[:alnum:]'
+designates those characters for which
+isalnum()
+returns true - i.e., any alphabetic or numeric character.
+Some systems don't provide
+isblank(),
+so flex defines
+`[:blank:]'
+as a blank or a tab.
+
+
+
+For example, the following character classes are all equivalent:
+
+
+
+
+If your scanner is case-insensitive (the `-i' flag), then
+`[:upper:]' and `[:lower:]' are equivalent to
+`[:alpha:]'.
+
+
+
+Some notes on patterns:
+
+
+
+
+
+
+
+
+
+
+A negated character class such as the example `[^A-Z]'
+above
+will match a newline
+unless `\n' (or an equivalent escape sequence) is one of the
+characters explicitly present in the negated character class
+(e.g., `[^A-Z\n]'). This is unlike how many other regular
+expression tools treat negated character classes, but unfortunately
+the inconsistency is historically entrenched.
+Matching newlines means that a pattern like `[^"]*' can match the entire
+input unless there's another quote in the input.
+
+
+
+A rule can have at most one instance of trailing context (the `/' operator
+or the `$' operator). The start condition, `^', and `<<EOF>>' patterns
+can only occur at the beginning of a pattern, and, as well as with `/' and `$',
+cannot be grouped inside parentheses. A `^' which does not occur at
+the beginning of a rule or a `$' which does not occur at the end of
+a rule loses its special properties and is treated as a normal character.
+
+
+
+The following are invalid:
+
+
+
+
+@verbatim
+ foo/bar$
+ <sc1>foo<sc2>bar
+
+
+Note that the first of these can be written `foo/bar\n'.
+
+
+
+The following will result in `$' or `^' being treated as a normal character:
+
+
+
+
+@verbatim
+ foo|(bar$)
+ foo|^bar
+
+
+If the desired meaning is a `foo' or a
+`bar'-followed-by-a-newline, the following could be used (the
+special | action is explained below, see section Actions):
+
+
+
+
+When the generated scanner is run, it analyzes its input looking for
+strings which match any of its patterns. If it finds more than one
+match, it takes the one matching the most text (for trailing context
+rules, this includes the length of the trailing part, even though it
+will then be returned to the input). If it finds two or more matches of
+the same length, the rule listed first in the flex input file is
+chosen.
+
+
+
+Once the match is determined, the text corresponding to the match
+(called the token) is made available in the global character
+pointer yytext, and its length in the global integer yyleng.
+The action corresponding to the matched pattern is then executed
+(see section Actions), and then the remaining input is scanned for another
+match.
+
+
+
+
+If no match is found, then the
+default rule
+is executed: the next character in the input is considered matched and
+copied to the standard output. Thus, the simplest valid
+flex
+input is:
+
+
+
+
+
+
+@verbatim
+ %%
+
+
+
+which generates a scanner that simply copies its input (one character
+at a time) to its output.
+
+
+
+
+
+
+
+
+
+
+Note that yytext can be defined in two different ways: either as a
+character pointer or as a character array. You can
+control which definition flex uses by including one of the
+special directives %pointer or %array in the first
+(definitions) section of your flex input. The default is
+%pointer, unless you use the `-l' lex compatibility option,
+in which case yytext will be an array. The advantage of using
+%pointer is substantially faster scanning and no buffer overflow
+when matching very large tokens (unless you run out of dynamic memory).
+The disadvantage is that you are restricted in how your actions can
+modify yytext (see section Actions), and calls to the unput()
+function destroys the present contents of yytext, which can be a
+considerable porting headache when moving between different lex
+versions.
+
+
+
+The advantage of
+%array
+is that you can then modify
+yytext
+to your heart's content, and calls to
+unput()
+do not destroy
+yytext
+(see section Actions). Furthermore, existing
+lex
+programs sometimes access
+yytext
+externally using declarations of the form:
+
+
+
+
+@verbatim
+ extern char yytext[];
+
+
+
+This definition is erroneous when used with %pointer, but correct
+for %array.
+
+
+
+The %array declaration defines yytext to be an array of
+YYLMAX characters, which defaults to a fairly large value. You
+can change the size by simply #define'ing YYLMAX to a different
+value in the first section of your flex input. As mentioned
+above, with %pointer yytext grows dynamically to accommodate
+large tokens. While this means your %pointer scanner can
+accommodate very large tokens (such as matching entire blocks of
+comments), bear in mind that each time the scanner must resize
+yytext it also must rescan the entire token from the beginning, so
+matching such tokens can prove slow. yytext presently does
+not dynamically grow if a call to unput() results in too
+much text being pushed back; instead, a run-time error results.
+
+
+
+
+Also note that you cannot use %array with C++ scanner classes
+(see section Generating C++ Scanners).
+
+
+
+
+
+Each pattern in a rule has a corresponding action, which can be any
+arbitrary C statement. The pattern ends at the first non-escaped
+whitespace character; the remainder of the line is its action. If the
+action is empty, then when the pattern is matched the input token
+is simply discarded. For example, here is the specification for a program
+which deletes all occurrences of `zap me' from its input:
+
+
+
+
+
+
+@verbatim
+ %%
+ "zap me"
+
+
+
+(It will copy all other characters in the input to the output since
+they will be matched by the default rule.)
+
+
+
+Here is a program which compresses multiple blanks and tabs down to a
+single blank, and throws away whitespace found at the end of a line:
+
+
+
+If the action contains a `}', then the action spans till the balancing `}'
+is found, and the action may cross multiple lines.
+flex
+knows about C strings and comments and won't be fooled by braces found
+within them, but also allows actions to begin with
+`%{'
+and will consider the action to be all the text up to the next
+`%}'
+(regardless of ordinary braces inside the action).
+
+
+
+An action consisting solely of a vertical bar ('|') means "same as the
+action for the next rule". See below for an illustration.
+
+
+
+Actions can include arbitrary C code, including return statements
+to return a value to whatever routine called yylex(). Each time
+yylex() is called it continues processing tokens from where it
+last left off until it either reaches the end of the file or executes a
+return.
+
+
+
+
+Actions are free to modify yytext except for lengthening it
+(adding characters to its end--these will overwrite later characters in
+the input stream). This however does not apply when using %array
+(see section How the Input Is Matched). In that case, yytext may be freely modified in
+any way.
+
+
+
+
+
+Actions are free to modify
+yyleng
+except they should not do so if the action also includes use of
+yymore()
+(see below).
+
+
+
+
+
+
+
+There are a number of special directives which can be included within
+an action:
+
+
+
+
+
ECHO
+
+
+
+copies yytext to the scanner's output.
+
+
+
BEGIN
+
+followed by the name of a start condition places the scanner in the
+corresponding start condition (see below).
+
+
+
REJECT
+
+directs the scanner to proceed on to the "second best" rule which
+matched the input (or a prefix of the input). The rule is chosen as
+described above in section How the Input Is Matched, and yytext and yyleng set
+up appropriately. It may either be one which matched as much text as
+the originally chosen rule but came later in the flex input file,
+or one which matched less text. For example, the following will both
+count the words in the input and call the routine special()
+whenever `frob' is seen:
+
+
+
+
+
+
+Without the REJECT, any occurences of `frob' in the input
+would not be counted as words, since the scanner normally executes only
+one action per token. Multiple uses of REJECT are allowed, each
+one finding the next best choice to the currently active rule. For
+example, when the following scanner scans the token `abcd', it will
+write `abcdabcaba' to the output:
+
+
+
+
+@verbatim
+ %%
+ a |
+ ab |
+ abc |
+ abcd ECHO; REJECT;
+ .|\n /* eat up any unmatched character */
+
+
+(The first three rules share the fourth's action since they use
+the special '|' action.)
+REJECT
+is a particularly expensive feature in terms of scanner performance;
+if it is used in
+any
+of the scanner's actions it will slow down
+all
+of the scanner's matching. Furthermore,
+REJECT
+cannot be used with the
+`-Cf'
+or
+`-CF'
+options (see section Invoking Flex).
+
+Note also that unlike the other special actions, REJECT is a
+branch. code immediately following it in the action will
+not be executed.
+
+
+
yymore()
+
+tells the scanner that the next time it matches a rule, the
+corresponding token should be appended onto the current value of
+yytext rather than replacing it. For example, given the input
+`mega-kludge' the following will write `mega-mega-kludge' to
+the output:
+
+
+
+
+
+
+First `mega-' is matched and echoed to the output. Then `kludge'
+is matched, but the previous `mega-' is still hanging around at the
+beginning of
+yytext
+so the
+ECHO
+for the `kludge' rule will actually write `mega-kludge'.
+
+
+
+Two notes regarding use of yymore(). First, yymore()
+depends on the value of yyleng correctly reflecting the size of
+the current token, so you must not modify yyleng if you are using
+yymore(). Second, the presence of yymore() in the
+scanner's action entails a minor performance penalty in the scanner's
+matching speed.
+
+
+
+
+yyless(n) returns all but the first n characters of the
+current token back to the input stream, where they will be rescanned
+when the scanner looks for the next match. yytext and
+yyleng are adjusted appropriately (e.g., yyleng will now be
+equal to n). For example, on the input `foobar' the
+following will write out `foobarbar':
+
+
+
+An argument of 0 to
+yyless()
+will cause the entire current input string to be scanned again. Unless you've
+changed how the scanner will subsequently process its input (using
+BEGIN,
+for example), this will result in an endless loop.
+
+
+
+Note that
+yyless()
+is a macro and can only be used in the flex input file, not from
+other source files.
+
+
+
+
+
+unput(c)
+puts the character
+c
+back onto the input stream. It will be the next character scanned.
+The following action will take the current token and cause it
+to be rescanned enclosed in parentheses.
+
+
+
+Note that since each unput() puts the given character back at the
+beginning of the input stream, pushing back strings must be done
+back-to-front.
+
+
+
+
+
+
+
+
+An important potential problem when using
+unput()
+is that if you are using
+%pointer
+(the default), a call to
+unput()
+destroys
+the contents of
+yytext,
+starting with its rightmost character and devouring one character to
+the left with each call. If you need the value of yytext preserved
+after a call to
+unput()
+(as in the above example),
+you must either first copy it elsewhere, or build your scanner using
+%array
+instead (see section How the Input Is Matched).
+
+
+
+
+
+Finally, note that you cannot put back `EOF' to attempt to mark the
+input stream with an end-of-file.
+
+
+
+
+input() reads the next character from the input stream. For
+example, the following is one way to eat up C comments:
+
+
+
+
+
+
+
+@verbatim
+ %%
+ "/*" {
+ register int c;
+
+ for ( ; ; )
+ {
+ while ( (c = input()) != '*' &&
+ c != EOF )
+ ; /* eat up text of comment */
+
+ if ( c == '*' )
+ {
+ while ( (c = input()) == '*' )
+ ;
+ if ( c == '/' )
+ break; /* found the end */
+ }
+
+ if ( c == EOF )
+ {
+ error( "EOF in comment" );
+ break;
+ }
+ }
+ }
+
+
+
+
+(Note that if the scanner is compiled using C++, then
+input() is instead referred to as yyinput(), in order to
+avoid a name clash with the C++ stream by the name of
+input.)
+
+
+
+
+YY_FLUSH_BUFFER()
+flushes the scanner's internal buffer
+so that the next time the scanner attempts to match a token, it will
+first refill the buffer using
+YY_INPUT()
+(see section The Generated Scanner). This action is a special case
+of the more general
+yy_flush_buffer()
+function, described below (see section Multiple Input Buffers)
+
+
+
+
+
+
+
+
+
+
+
+yyterminate()
+can be used in lieu of a return statement in an action. It terminates
+the scanner and returns a 0 to the scanner's caller, indicating "all done".
+By default,
+yyterminate()
+is also called when an end-of-file is encountered. It is a macro and
+may be redefined.
+
+
+
+
+
+
+The output of flex is the file `lex.yy.c', which contains
+the scanning routine yylex(), a number of tables used by it for
+matching tokens, and a number of auxiliary routines and macros. By
+default, yylex() is declared as follows:
+
+
+
+
+@verbatim
+ int yylex()
+ {
+ ... various definitions and the actions in here ...
+ }
+
+
+
+
+(If your environment supports function prototypes, then it will
+be
+ int yylex( void ).) This definition may be changed by defining
+the YY_DECL macro. For example, you could use:
+
+
+
+
+
+
+@verbatim
+ #define YY_DECL float lexscan( a, b ) float a, b;
+
+
+
+to give the scanning routine the name lexscan, returning a float,
+and taking two floats as arguments. Note that if you give arguments to
+the scanning routine using a K&R-style/non-prototyped function
+declaration, you must terminate the definition with a semi-colon (;).
+
+
+
+
+Whenever yylex() is called, it scans tokens from the global input
+file `yyin' (which defaults to stdin). It continues until it
+either reaches an end-of-file (at which point it returns the value 0) or
+one of its actions executes a return statement.
+
+
+
+
+If the scanner reaches an end-of-file, subsequent calls are undefined
+unless either `yyin' is pointed at a new input file (in which case
+scanning continues from that file), or yyrestart() is called.
+yyrestart() takes one argument, a FILE * pointer (which
+can be nil, if you've set up YY_INPUT to scan from a source other
+than yyin), and initializes `yyin' for scanning from that
+file. Essentially there is no difference between just assigning
+`yyin' to a new input file or using yyrestart() to do so;
+the latter is available for compatibility with previous versions of
+flex, and because it can be used to switch input files in the
+middle of scanning. It can also be used to throw away the current input
+buffer, by calling it with an argument of `yyin'; but it would be
+better to use YY_FLUSH_BUFFER (see section Actions). Note that
+yyrestart() does not reset the start condition to
+INITIAL (see section Start Conditions).
+
+
+
+
+If
+yylex()
+stops scanning due to executing a
+return
+statement in one of the actions, the scanner may then be called again and it
+will resume scanning where it left off.
+
+
+
+By default (and for purposes of efficiency), the scanner uses
+block-reads rather than simple getc() calls to read characters
+from `yyin'. The nature of how it gets its input can be controlled
+by defining the YY_INPUT macro. The calling sequence for
+YY_INPUT() is YY_INPUT(buf,result,max_size). Its action
+is to place up to max_size characters in the character array
+buf and return in the integer variable result either the
+number of characters read or the constant YY_NULL (0 on Unix
+systems) to indicate `EOF'. The default YY_INPUT reads from
+the global file-pointer `yyin'.
+
+
+
+
+Here is a sample definition of YY_INPUT (in the definitions
+section of the input file):
+
+
+
+This definition will change the input processing to occur
+one character at a time.
+
+
+
+
+When the scanner receives an end-of-file indication from YY_INPUT, it
+then checks the yywrap() function. If yywrap() returns
+false (zero), then it is assumed that the function has gone ahead and
+set up `yyin' to point to another input file, and scanning
+continues. If it returns true (non-zero), then the scanner terminates,
+returning 0 to its caller. Note that in either case, the start
+condition remains unchanged; it does not revert to
+INITIAL.
+
+
+
+If you do not supply your own version of yywrap(), then you must
+either use %option noyywrap (in which case the scanner behaves as
+though yywrap() returned 1), or you must link with `-lfl' to
+obtain the default version of the routine, which always returns 1.
+
+
+
+For scanning from in-memory buffers (e.g., scanning strings), see
+@xref{Scanning Strings}
+See section Multiple Input Buffers.
+
+
+
+The scanner writes its
+ECHO
+output to the
+`yyout'
+global (default, `stdout'), which may be redefined by the user simply
+by assigning it to some other
+FILE
+pointer.
+
+
+
+
+
+
+flex
+provides a mechanism for conditionally activating rules. Any rule
+whose pattern is prefixed with `<sc>' will only be active when
+the scanner is in the start condition named sc. For example,
+
+
+
+
+
+
+@verbatim
+ <STRING>[^"]* { /* eat up the string body ... */
+ ...
+ }
+
+
+
+will be active only when the scanner is in the STRING start
+condition, and
+
+
+
+will be active only when the current start condition is either
+INITIAL, STRING, or QUOTE.
+
+
+
+
+Start conditions are declared in the definitions (first) section of the
+input using unindented lines beginning with either `%s' or
+`%x' followed by a list of names. The former declares
+inclusive start conditions, the latter exclusive start
+conditions. A start condition is activated using the BEGIN
+action. Until the next BEGIN action is executed, rules with the
+given start condition will be active and rules with other start
+conditions will be inactive. If the start condition is inclusive, then
+rules with no start conditions at all will also be active. If it is
+exclusive, then only rules qualified with the start condition
+will be active. A set of rules contingent on the same exclusive start
+condition describe a scanner which is independent of any of the other
+rules in the flex input. Because of this, exclusive start
+conditions make it easy to specify "mini-scanners" which scan portions
+of the input that are syntactically different from the rest (e.g.,
+comments).
+
+
+
+If the distinction between inclusive and exclusive start conditions
+is still a little vague, here's a simple example illustrating the
+connection between the two. The set of rules:
+
+
+
+
+
+
+@verbatim
+ %s example
+ %%
+
+ <example>foo do_something();
+
+ bar something_else();
+
+Without the <INITIAL,example> qualifier, the bar pattern in
+the second example wouldn't be active (i.e., couldn't match) when in
+start condition example. If we just used example> to
+qualify bar, though, then it would only be active in
+example and not in INITIAL, while in the first example
+it's active in both, because in the first example the example
+start condition is an inclusive (%s) start condition.
+
+
+
+
+Also note that the special start-condition specifier
+<*>
+matches every start condition. Thus, the above example could also
+have been written:
+
+
+
+The default rule (to ECHO any unmatched character) remains active
+in start conditions. It is equivalent to:
+
+
+
+
+
+
+@verbatim
+ <*>.|\n ECHO;
+
+
+
+
+
+
+BEGIN(0) returns to the original state where only the rules with
+no start conditions are active. This state can also be referred to as
+the start-condition INITIAL, so BEGIN(INITIAL) is
+equivalent to BEGIN(0). (The parentheses around the start
+condition name are not required but are considered good style.)
+
+
+
+BEGIN actions can also be given as indented code at the beginning
+of the rules section. For example, the following will cause the scanner
+to enter the SPECIAL start condition whenever yylex() is
+called and the global variable enter_special is true:
+
+
+
+
+
+
+@verbatim
+ int enter_special;
+
+ %x SPECIAL
+ %%
+ if ( enter_special )
+ BEGIN(SPECIAL);
+
+ <SPECIAL>blahblahblah
+ ...more rules follow...
+
+
+
+To illustrate the uses of start conditions, here is a scanner which
+provides two different interpretations of a string like `123.456'.
+By default it will treat it as three tokens, the integer `123', a
+dot (`.'), and the integer `456'. But if the string is
+preceded earlier in the line by the string `expect-floats' it will
+treat it as a single token, the floating-point number `123.456':
+
+
+
+
+
+
+@verbatim
+ %{
+ #include <math.h>
+ %}
+ %s expect
+
+ %%
+ expect-floats BEGIN(expect);
+
+ <expect>[0-9]+`.'[0-9]+ {
+ printf( "found a float, = %f\n",
+ atof( yytext ) );
+ }
+ <expect>\n {
+ /* that's the end of the line, so
+ * we need another "expect-number"
+ * before we'll recognize any more
+ * numbers
+ */
+ BEGIN(INITIAL);
+ }
+
+ [0-9]+ {
+ printf( "found an integer, = %d\n",
+ atoi( yytext ) );
+ }
+
+ "." printf( "found a dot\n" );
+
+
+
+
+Here is a scanner which recognizes (and discards) C comments while
+maintaining a count of the current input line.
+
+
+
+
+
+
+@verbatim
+ %x comment
+ %%
+ int line_num = 1;
+
+ "/*" BEGIN(comment);
+
+ <comment>[^*\n]* /* eat anything that's not a '*' */
+ <comment>"*"+[^*/\n]* /* eat up '*'s not followed by '/'s */
+ <comment>\n ++line_num;
+ <comment>"*"+"/" BEGIN(INITIAL);
+
+
+
+This scanner goes to a bit of trouble to match as much
+text as possible with each rule. In general, when attempting to write
+a high-speed scanner try to match as much possible in each rule, as
+it's a big win.
+
+
+
+Note that start-conditions names are really integer values and
+can be stored as such. Thus, the above could be extended in the
+following fashion:
+
+
+
+
+
+
+
+@verbatim
+ %x comment foo
+ %%
+ int line_num = 1;
+ int comment_caller;
+
+ "/*" {
+ comment_caller = INITIAL;
+ BEGIN(comment);
+ }
+
+ ...
+
+ <foo>"/*" {
+ comment_caller = foo;
+ BEGIN(comment);
+ }
+
+ <comment>[^*\n]* /* eat anything that's not a '*' */
+ <comment>"*"+[^*/\n]* /* eat up '*'s not followed by '/'s */
+ <comment>\n ++line_num;
+ <comment>"*"+"/" BEGIN(comment_caller);
+
+
+
+
+Furthermore, you can access the current start condition using the
+integer-valued YY_START macro. For example, the above
+assignments to comment_caller could instead be written
+
+
+
+
+
+
+@verbatim
+ comment_caller = YY_START;
+
+
+
+
+Flex provides YYSTATE as an alias for YY_START (since that
+is what's used by AT&T lex).
+
+
+
+Note that start conditions do not have their own name-space; %s's and %x's
+declare names in the same fashion as #define's.
+
+
+
+Finally, here's an example of how to match C-style quoted strings using
+exclusive start conditions, including expanded escape sequences (but
+not including checking for a string that's too long):
+
+
+
+
+Often, such as in some of the examples above, you wind up writing a
+whole bunch of rules all preceded by the same start condition(s). Flex
+makes this a little easier and cleaner by introducing a notion of start
+condition scope. A start condition scope is begun with:
+
+
+
+
+@verbatim
+ <SCs>{
+
+
+
+where SCs is a list of one or more start conditions. Inside the
+start condition scope, every rule automatically has the prefix
+SCs> applied to it, until a `}' which matches the initial
+`{'. So, for example,
+
+
+
+The following routines are available for manipulating stacks of start conditions:
+
+
+
+
+
Function: void yy_push_state( int new_state )
+
+pushes the current start condition onto the top of the start condition
+stack and switches to
+new_state
+as though you had used
+BEGIN new_state
+(recall that start condition names are also integers).
+
+
+
+
+
+
Function: void yy_pop_state()
+
+pops the top of the stack and switches to it via
+BEGIN.
+
+
+
+
+
+
Function: int yy_top_state()
+
+returns the top of the stack without altering the stack's contents.
+
+
+
+
+
+The start condition stack grows dynamically and so has no built-in size
+limitation. If memory is exhausted, program execution aborts.
+
+
+
+To use start condition stacks, your scanner must include a %option
+stack directive (see section Invoking Flex).
+
+
+
+
+
+
+Some scanners (such as those which support "include" files) require
+reading from several input streams. As flex scanners do a large
+amount of buffering, one cannot control where the next input will be
+read from by simply writing a YY_INPUT() which is sensitive to
+the scanning context. YY_INPUT() is only called when the scanner
+reaches the end of its buffer, which may be a long time after scanning a
+statement such as an include statement which requires switching
+the input source.
+
+
+
+To negotiate these sorts of problems, flex provides a mechanism
+for creating and switching between multiple input buffers. An input
+buffer is created by using:
+
+
+
+
+
+
Function: YY_BUFFER_STATE yy_create_buffer( FILE *file, int size )
+
+
+
+
+
+which takes a FILE pointer and a size and creates a buffer
+associated with the given file and large enough to hold size
+characters (when in doubt, use YY_BUF_SIZE for the size). It
+returns a YY_BUFFER_STATE handle, which may then be passed to
+other routines (see below).
+
+The YY_BUFFER_STATE type is a
+pointer to an opaque struct yy_buffer_state structure, so you may
+safely initialize YY_BUFFER_STATE variables to ((YY_BUFFER_STATE)
+0) if you wish, and also refer to the opaque structure in order to
+correctly declare input buffers in source files other than that of your
+scanner. Note that the FILE pointer in the call to
+yy_create_buffer is only used as the value of `yyin' seen by
+YY_INPUT. If you redefine YY_INPUT() so it no longer uses
+`yyin', then you can safely pass a nil FILE pointer to
+yy_create_buffer. You select a particular buffer to scan from
+using:
+
+
+
+The above switches the scanner's input buffer so subsequent tokens will
+come from new_buffer. Note that yy_switch_to_buffer() may
+be used by yywrap() to set things up for continued scanning,
+instead of opening a new file and pointing `yyin' at it. Note also
+that switching input sources via either yy_switch_to_buffer() or
+yywrap() does not change the start condition.
+
+
+
+is used to reclaim the storage associated with a buffer. (buffer
+can be nil, in which case the routine does nothing.) You can also clear
+the current contents of a buffer using:
+
+
+
+This function discards the buffer's contents,
+so the next time the scanner attempts to match a token from the
+buffer, it will first fill the buffer anew using
+YY_INPUT().
+
+
+
+
+
Function: YY_BUFFER_STATE yy_new_buffer( FILE *file, int size )
+
+
+
+
+
+is an alias for yy_create_buffer(),
+provided for compatibility with the C++ use of new and
+delete for creating and destroying dynamic objects.
+
+
+
+
+Finally, the macro YY_CURRENT_BUFFER macro returns a
+YY_BUFFER_STATE handle to the current buffer.
+
+
+
+
+Here is an example of using these features for writing a scanner
+which expands include files (the
+<<EOF>>
+feature is discussed below):
+
+
+
+
+
+
+@verbatim
+ /* the "incl" state is used for picking up the name
+ * of an include file
+ */
+ %x incl
+
+ %{
+ #define MAX_INCLUDE_DEPTH 10
+ YY_BUFFER_STATE include_stack[MAX_INCLUDE_DEPTH];
+ int include_stack_ptr = 0;
+ %}
+
+ %%
+ include BEGIN(incl);
+
+ [a-z]+ ECHO;
+ [^a-z\n]*\n? ECHO;
+
+ <incl>[ \t]* /* eat the whitespace */
+ <incl>[^ \t\n]+ { /* got the include file name */
+ if ( include_stack_ptr >= MAX_INCLUDE_DEPTH )
+ {
+ fprintf( stderr, "Includes nested too deeply" );
+ exit( 1 );
+ }
+
+ include_stack[include_stack_ptr++] =
+ YY_CURRENT_BUFFER;
+
+ yyin = fopen( yytext, "r" );
+
+ if ( ! yyin )
+ error( ... );
+
+ yy_switch_to_buffer(
+ yy_create_buffer( yyin, YY_BUF_SIZE ) );
+
+ BEGIN(INITIAL);
+ }
+
+ <<EOF>> {
+ if ( --include_stack_ptr 0 )
+ {
+ yyterminate();
+ }
+
+ else
+ {
+ yy_delete_buffer( YY_CURRENT_BUFFER );
+ yy_switch_to_buffer(
+ include_stack[include_stack_ptr] );
+ }
+ }
+
+
+
+@anchor{Scanning Strings}
+
+The following routines are available for setting up input buffers for
+scanning in-memory strings instead of files. All of them create a new
+input buffer for scanning the string, and return a corresponding
+YY_BUFFER_STATE handle (which you should delete with
+yy_delete_buffer() when done with it). They also switch to the
+new buffer using yy_switch_to_buffer(), so the next call to
+yylex() will start scanning the string.
+
+
+
Function: YY_BUFFER_STATE yy_scan_bytes( const char *bytes, int len )
+
+scans len bytes (including possibly NULs) starting at location
+bytes.
+
+
+
+
+Note that both of these functions create and scan a copy of the
+string or bytes. (This may be desirable, since yylex() modifies
+the contents of the buffer it is scanning.) You can avoid the copy by
+using:
+
+
+
+which scans in place the buffer starting at base, consisting of
+size bytes, the last two bytes of which must be
+YY_END_OF_BUFFER_CHAR (ASCII NUL). These last two bytes are not
+scanned; thus, scanning consists of base[0] through
+base[size-2], inclusive.
+
+
+
+
+If you fail to set up base in this manner (i.e., forget the final
+two YY_END_OF_BUFFER_CHAR bytes), then yy_scan_buffer()
+returns a nil pointer instead of creating a new input buffer.
+
+
+
+
+
Data type:yy_size_t
+
+is an integral type to which you can cast an integer expression
+reflecting the size of the buffer.
+
+
+The special rule <<EOF>> indicates
+actions which are to be taken when an end-of-file is
+encountered and yywrap() returns non-zero (i.e., indicates
+no further files to process). The action must finish
+by doing one of the following things:
+
+
+
+
+
+
+
+assigning `yyin' to a new input file (in previous versions of
+flex, after doing the assignment you had to call the special
+action YY_NEW_FILE. This is no longer necessary.)
+
+
+
+executing a return statement;
+
+
+
+executing the special yyterminate() action.
+
+
+
+or, switching to a new buffer using yy_switch_to_buffer() as
+shown in the example above.
+
+
+
+<<EOF>> rules may not be used with other patterns; they may only be
+qualified with a list of start conditions. If an unqualified <<EOF>>
+rule is given, it applies to all start conditions which do not
+already have <<EOF>> actions. To specify an <<EOF>> rule for only the
+initial start condition, use:
+
+
+
+
+@verbatim
+ <INITIAL><<EOF>>
+
+
+
+These rules are useful for catching things like unclosed comments. An
+example:
+
+
+
+
+The macro YY_USER_ACTION can be defined to provide an action
+which is always executed prior to the matched rule's action. For
+example, it could be #define'd to call a routine to convert yytext to
+lower-case. When YY_USER_ACTION is invoked, the variable
+yy_act gives the number of the matched rule (rules are numbered
+starting with 1). Suppose you want to profile how often each of your
+rules is matched. The following would do the trick:
+
+
+
+
+where ctr is an array to hold the counts for the different rules.
+Note that the macro YY_NUM_RULES gives the total number of rules
+(including the default rule), even if you use `-s)', so a correct
+declaration for ctr is:
+
+
+
+
+@verbatim
+ int ctr[YY_NUM_RULES];
+
+
+
+
+The macro YY_USER_INIT may be defined to provide an action which
+is always executed before the first scan (and before the scanner's
+internal initializations are done). For example, it could be used to
+call a routine to read in a data table or open a logging file.
+
+
+
+
+The macro yy_set_interactive(is_interactive) can be used to
+control whether the current buffer is considered interactive. An
+interactive buffer is processed more slowly, but must be used when the
+scanner's input source is indeed interactive to avoid problems due to
+waiting to fill buffers (see the discussion of the `-I' flag in
+section Invoking Flex). A non-zero value in the macro invocation marks
+the buffer as interactive, a zero value as non-interactive. Note that
+use of this macro overrides %option always-interactive or
+%option never-interactive (see section Invoking Flex).
+yy_set_interactive() must be invoked prior to beginning to scan
+the buffer that is (or is not) to be considered interactive.
+
+
+
+
+
+The macro yy_set_bol(at_bol) can be used to control whether the
+current buffer's scanning context for the next token match is done as
+though at the beginning of a line. A non-zero macro argument makes
+rules anchored with `^' active, while a zero argument makes
+`^' rules inactive.
+
+
+
+
+
+The macro YY_AT_BOL() returns true if the next token scanned from
+the current buffer will have `^' rules active, false otherwise.
+
+
+
+
+
+In the generated scanner, the actions are all gathered in one large
+switch statement and separated using YY_BREAK, which may be
+redefined. By default, it is simply a break, to separate each
+rule's action from the following rule's. Redefining YY_BREAK
+allows, for example, C++ users to #define YY_BREAK to do nothing (while
+being very careful that every rule ends with a break" or a
+return!) to avoid suffering from unreachable statement warnings
+where because a rule's action ends with return, the
+YY_BREAK is inaccessible.
+
+
+
+
+
+This chapter summarizes the various values available to the user in the
+rule actions.
+
+
+
+
+
char *yytext
+
+
+
+holds the text of the current token. It may be modified but not
+lengthened (you cannot append characters to the end).
+
+
+
+
+If the special directive %array appears in the first section of
+the scanner description, then yytext is instead declared
+char yytext[YYLMAX], where YYLMAX is a macro definition
+that you can redefine in the first section if you don't like the default
+value (generally 8KB). Using %array results in somewhat slower
+scanners, but the value of yytext becomes immune to calls to
+unput(), which potentially destroy its value when yytext is
+a character pointer. The opposite of %array is %pointer,
+which is the default.
+
+
+You cannot use %array when generating C++ scanner classes (the
+`-+' flag).
+
+
+
int yyleng
+
+holds the length of the current token.
+
+
+
FILE *yyin
+
+is the file which by default flex reads from. It may be
+redefined but doing so only makes sense before scanning begins or after
+an EOF has been encountered. Changing it in the midst of scanning will
+have unexpected results since flex buffers its input; use
+yyrestart() instead. Once scanning terminates because an
+end-of-file has been seen, you can assign `yyin' at the new input
+file and then call the scanner again to continue scanning.
+
+
+
void yyrestart( FILE *new_file )
+
+may be called to point `yyin' at the new input file. The
+switch-over to the new file is immediate (any previously buffered-up
+input is lost). Note that calling yyrestart() with `yyin'
+as an argument thus throws away the current input buffer and continues
+scanning the same input file.
+
+
+
FILE *yyout
+
+is the file to which ECHO actions are done. It can be reassigned
+by the user.
+
+
+
YY_CURRENT_BUFFER
+
+returns a YY_BUFFER_STATE handle to the current buffer.
+
+
+
YY_START
+
+returns an integer value corresponding to the current start condition.
+You can subsequently use this value with BEGIN to return to that
+start condition.
+
+
+One of the main uses of flex is as a companion to the yacc
+parser-generator. yacc parsers expect to call a routine named
+yylex() to find the next input token. The routine is supposed to
+return the type of the next token as well as putting any associated
+value in the global yylval. To use flex with yacc,
+one specifies the `-d' option to yacc to instruct it to
+generate the file `y.tab.h' containing definitions of all the
+%tokens appearing in the yacc input. This file is then
+included in the flex scanner. For example, if one of the tokens
+is TOK_NUMBER, part of the scanner might look like:
+
+
+
+Generate backing-up information to `lex.backup'. This is a list of
+scanner states which require backing up and the input characters on
+which they do so. By adding rules one can remove backing-up states. If
+all backing-up states are eliminated and `-Cf' or -CF
+is used, the generated scanner will run faster (see the `--perf-report' flag).
+Only users who wish to squeeze every last cycle out of their scanners
+need worry about this option. (see section Performance Considerations).
+
+
`-c'
+
+is a do-nothing option included for POSIX compliance.
+
+
`-d, --debug'
+
+makes the generated scanner run in debug mode. Whenever a pattern
+is recognized and the global variable yy_flex_debug is non-zero
+(which is the default), the scanner will write to `stderr' a line
+of the form:
+
+
+
+@verbatim
+ -accepting rule at line 53 ("the matched text")
+
+
+The line number refers to the location of the rule in the file defining
+the scanner (i.e., the file that was fed to flex). Messages are also
+generated when the scanner backs up, accepts the default rule, reaches
+the end of its input buffer (or encounters a NUL; at this point, the two
+look the same as far as the scanner's concerned), or reaches an
+end-of-file.
+
+
`-f, --full'
+
+specifies
+fast scanner.
+No table compression is done and stdio is bypassed.
+The result is large but fast. This option is equivalent to
+`--Cfr'
+
+
`-h, -?, --help'
+
+generates a "help" summary of flex's options to `stdout'
+and then exits.
+
+
`--header=FILE'
+
+instructs flex to write a C header to `FILE'. This file contains
+function prototypes, extern variables, and macros used by the scanner.
+It is meant to be included in other C files to avoid compiler warnings.
+The `--header' option is not compatible with the `--c++' option,
+since the C++ scanner provides its own header in `yyFlexLexer.h'.
+
+
`-i, --case-insensitive'
+
+instructs flex to generate a case-insensitive scanner. The
+case of letters given in the flex input patterns will be ignored,
+and tokens in the input will be matched regardless of case. The matched
+text given in yytext will have the preserved case (i.e., it will
+not be folded).
+
+
`-l, --lex-compat'
+
+turns on maximum compatibility with the original AT&T lex
+implementation. Note that this does not mean full compatibility.
+Use of this option costs a considerable amount of performance, and it
+cannot be used with the `--c++', `--full', `--fast', `-Cf', or
+`-CF' options. For details on the compatibilities it provides, see
+section Incompatibilities with Lex and Posix. This option also results in the name
+YY_FLEX_LEX_COMPAT being #define'd in the generated scanner.
+
+
`-n'
+
+is another do-nothing option included only for
+POSIX compliance.
+
+
`-p, --perf-report'
+
+generates a performance report to `stderr'. The report consists of
+comments regarding features of the flex input file which will
+cause a serious loss of performance in the resulting scanner. If you
+give the flag twice, you will also get comments regarding features that
+lead to minor performance losses.
+
+Note that the use of REJECT, %option yylineno, and
+variable trailing context (see section Limitations) entails a substantial
+performance penalty; use of yymore(), the `^' operator, and
+the `--interactive' flag entail minor performance penalties.
+
+
`-s, --nodefault'
+
+causes the default rule (that unmatched scanner input is echoed
+to `stdout)' to be suppressed. If the scanner encounters input
+that does not match any of its rules, it aborts with an error. This
+option is useful for finding holes in a scanner's rule set.
+
+
`-t, --stdout'
+
+instructs flex to write the scanner it generates to standard
+output instead of `lex.yy.c'.
+
+
`-v, --verbose'
+
+specifies that flex should write to `stderr' a summary of
+statistics regarding the scanner it generates. Most of the statistics
+are meaningless to the casual flex user, but the first line
+identifies the version of flex (same as reported by `--version'),
+and the next line the flags used when generating the scanner, including
+those that are on by default.
+
+
`-w, --nowarn'
+
+suppresses warning messages.
+
+
`-B, --batch'
+
+instructs flex to generate a batch scanner, the opposite of
+interactive scanners generated by `--interactive' (see below). In
+general, you use `-B' when you are certain that your scanner
+will never be used interactively, and you want to squeeze a
+little more performance out of it. If your goal is instead to
+squeeze out a lot more performance, you should be using the
+`-Cf' or `-CF' options, which turn on `--batch' automatically
+anyway.
+
+
`-F, --fast'
+
+specifies that the fast scanner table representation should be
+used (and stdio bypassed). This representation is about as fast
+as the full table representation `--full', and for some sets of
+patterns will be considerably smaller (and for others, larger). In
+general, if the pattern set contains both keywords and a
+catch-all, identifier rule, such as in the set:
+
+
+
+
+then you're better off using the full table representation. If only
+the identifier rule is present and you then use a hash table or some such
+to detect the keywords, you're better off using
+`--fast'.
+
+This option is equivalent to `-CFr' (see below). It cannot be used
+with `--c++'.
+
+
`-I, --interactive'
+
+instructs flex to generate an interactive scanner. An
+interactive scanner is one that only looks ahead to decide what token
+has been matched if it absolutely must. It turns out that always
+looking one extra character ahead, even if the scanner has already seen
+enough text to disambiguate the current token, is a bit faster than only
+looking ahead when necessary. But scanners that always look ahead give
+dreadful interactive performance; for example, when a user types a
+newline, it is not recognized as a newline token until they enter
+another token, which often means typing in another whole line.
+
+flex scanners default to interactive unless you use the
+`-Cf' or `-CF' table-compression options
+(see section Performance Considerations). That's because if you're looking for
+high-performance you should be using one of these options, so if you
+didn't, flex assumes you'd rather trade off a bit of run-time
+performance for intuitive interactive behavior. Note also that you
+cannot use `--interactive' in conjunction with `-Cf' or
+`-CF'. Thus, this option is not really needed; it is on by default
+for all those cases in which it is allowed.
+
+You can force a scanner to
+not
+be interactive by using
+`--batch'
+
+
`-L, --noline'
+
+instructs
+flex
+not to generate
+#line
+directives. Without this option,
+flex
+peppers the generated scanner
+with #line directives so error messages in the actions will be correctly
+located with respect to either the original
+flex
+input file (if the errors are due to code in the input file), or
+`lex.yy.c'
+(if the errors are
+flex's
+fault -- you should report these sorts of errors to the email address
+given in section Reporting Bugs).
+
+
`-R, --reentrant'
+
+instructs flex to generate a reentrant C scanner. The generated scanner
+may safely be used in a multi-threaded environment. The API for a
+reentrant scanner is different than for a non-reentrant scanner
+see section Reentrant C Scanners). Because of the API difference between
+reentrant and non-reentrant flex scanners, non-reentrant flex
+code must be modified before it is suitable for use with this option.
+This option is not compatible with the `--c++' option.
+
+
`-Rb, --reentrant-bison'
+
+instructs flex to generate a reentrant C scanner that is
+meant to be called by a
+GNU bison
+pure parser. The scanner is the same as the scanner generated by the
+`--reentrant'
+option, but with minor API changes for
+bison
+compatibility. In particular, the declaration of
+yylex
+is modified, and support for
+yylval
+and
+yylloc
+is incorporated. See section Reentrant C Scanners with Bison Pure Parsers.
+
+The options `--reentrant' and `--reentrant-bison' do not affect the performance of
+the scanner.
+
+
`-T, --trace'
+
+makes flex run in trace mode. It will generate a lot of
+messages to `stderr' concerning the form of the input and the
+resultant non-deterministic and deterministic finite automata. This
+option is mostly for use in maintaining flex.
+
+
`-V, --version'
+
+prints the version number to `stdout' and exits.
+
+
`-X, --posix'
+
+turns on maximum compatibility with the POSIX 1003.2-1992 definition of
+lex. Since flex was originally designed to implement the
+POSIX definition of lex this generally involves very few changes
+in behavior. At the current writing the known differences between
+flex and the POSIX standard are:
+
+
+
+
+
+In POSIX and AT&T lex, the repeat operator, `{}', has lower
+precedence than concatenation (thus `ab{3}' yields `ababab').
+Most POSIX utilities use an Extended Regular Expression (ERE) precedence
+that has the precedence of the repeat operator higher than concatenation
+(which causes `ab{3}' to yield `abbb'). By default, flex
+places the precedence of the repeat operator higher than concatenation
+which matches the ERE processing of other POSIX utilities. When either
+`--posix' or `-l' are specified, flex will use the
+traditional AT&T and POSIX-compliant precedence for the repeat operator
+where concatenation has higher precedence than the repeat operator.
+
+
+
`-7, --7bit'
+
+instructs flex to generate a 7-bit scanner, i.e., one which can
+only recognize 7-bit characters in its input. The advantage of using
+`--7bit' is that the scanner's tables can be up to half the size of
+those generated using the `--8bit'. The disadvantage is that such
+scanners often hang or crash if their input contains an 8-bit character.
+
+Note, however, that unless you generate your scanner using the
+`-Cf' or `-CF' table compression options, use of `--7bit'
+will save only a small amount of table space, and make your scanner
+considerably less portable. Flex's default behavior is to
+generate an 8-bit scanner unless you use the `-Cf' or `-CF',
+in which case flex defaults to generating 7-bit scanners unless
+your site was always configured to generate 8-bit scanners (as will
+often be the case with non-USA sites). You can tell whether flex
+generated a 7-bit or an 8-bit scanner by inspecting the flag summary in
+the `--verbose' output as described above.
+
+Note that if you use `-Cfe' or `-CFe'flex still
+defaults to generating an 8-bit scanner, since usually with these
+compression options full 8-bit tables are not much more expensive than
+7-bit tables.
+
+
`-8, --8bit'
+
+instructs flex to generate an 8-bit scanner, i.e., one which can
+recognize 8-bit characters. This flag is only needed for scanners
+generated using `-Cf' or `-CF', as otherwise flex defaults to
+generating an 8-bit scanner anyway.
+
+See the discussion of
+`--7bit'
+above for flex's default behavior and the tradeoffs between 7-bit
+and 8-bit scanners.
+
+
`-+, --c++'
+
+specifies that you want flex to generate a C++
+scanner class. See section Generating C++ Scanners, for
+details.
+
+
`-C[aefFmr]'
+
+controls the degree of table compression and, more generally, trade-offs
+between small scanners and fast scanners.
+
+
`-Ca, --align'
+
+("align") instructs flex to trade off larger tables in the
+generated scanner for faster performance because the elements of
+the tables are better aligned for memory access and computation. On some
+RISC architectures, fetching and manipulating longwords is more efficient
+than with smaller-sized units such as shortwords. This option can
+quadruple the size of the tables used by your scanner.
+
+
`-Ce, --ecs'
+
+directs flex to construct equivalence classes, i.e., sets
+of characters which have identical lexical properties (for example, if
+the only appearance of digits in the flex input is in the
+character class "[0-9]" then the digits '0', '1', ..., '9' will all be
+put in the same equivalence class). Equivalence classes usually give
+dramatic reductions in the final table/object file sizes (typically a
+factor of 2-5) and are pretty cheap performance-wise (one array look-up
+per character scanned).
+
+
`-Cf'
+
+specifies that the full scanner tables should be generated -
+flex should not compress the tables by taking advantages of
+similar transition functions for different states.
+
+
`-CF'
+
+specifies that the alternate fast scanner representation (described
+above under the `--fast' flag) should be used. This option cannot be
+used with `--c++'.
+
+
`-Cm, --meta-ecs'
+
+directs
+flex
+to construct
+meta-equivalence classes,
+which are sets of equivalence classes (or characters, if equivalence
+classes are not being used) that are commonly used together. Meta-equivalence
+classes are often a big win when using compressed tables, but they
+have a moderate performance impact (one or two if tests and one
+array look-up per character scanned).
+
+@anchor{Option-Read}
+
`-Cr, --read'
+
+causes the generated scanner to bypass use of the standard I/O
+library (stdio) for input. Instead of calling fread() or
+getc(), the scanner will use the read() system call,
+resulting in a performance gain which varies from system to system, but
+in general is probably negligible unless you are also using `-Cf'
+or `-CF'. Using `-Cr' can cause strange behavior if, for
+example, you read from `yyin' using stdio prior to calling
+the scanner (because the scanner will miss whatever text your previous
+reads left in the stdio input buffer). `-Cr' has no effect
+if you define YY_INPUT() (see section The Generated Scanner).
+
+
`-C'
+
+A lone `-C' specifies that the scanner tables should be compressed
+but neither equivalence classes nor meta-equivalence classes should be
+used.
+
+The options `-Cf' or `-CF' and `-Cm' do not make sense
+together - there is no opportunity for meta-equivalence classes if the
+table is not being compressed. Otherwise the options may be freely
+mixed, and are cumulative.
+
+The default setting is `-Cem', which specifies that flex
+should generate equivalence classes and meta-equivalence classes. This
+setting provides the highest degree of table compression. You can trade
+off faster-executing scanners at the cost of larger tables with the
+following generally being true:
+
+
+
+
+Note that scanners with the smallest tables are usually generated and
+compiled the quickest, so during development you will usually want to
+use the default, maximal compression.
+
+`-Cfe' is often a good compromise between speed and size for
+production scanners.
+
+
`-oFILE, --outfile=FILE'
+
+directs flex to write the scanner to the file `FILE' instead of
+`lex.yy.c'. If you combine `--outfile' with the `--stdout' option,
+then the scanner is written to `stdout' but its #line
+directives (see the `-l' option above) refer to the file
+`FILE'.
+
+
`-PPREFIX, --prefix=PREFIX'
+
+changes the default `yy' prefix used by flex for all
+globally-visible variable and function names to instead be
+`PREFIX'. For example, `--prefix=foo' changes the name of
+yytext to footext. It also changes the name of the default
+output file from `lex.yy.c' to `lex.foo.c'. Here are all of
+the names affected:
+
+
+
+
+(If you are using a C++ scanner, then only yywrap and
+yyFlexLexer are affected.) Within your scanner itself, you can
+still refer to the global variables and functions using either version
+of their name; but externally, they have the modified name.
+
+This option lets you easily link together multiple
+flex
+programs into the same executable. Note, though, that using this
+option also renames
+yywrap(),
+so you now
+must
+either
+provide your own (appropriately-named) version of the routine for your
+scanner, or use
+%option noyywrap,
+as linking with
+`-lfl'
+no longer provides one for you by default.
+
+
`-SFILE, --skel=FILE'
+
+overrides the default skeleton file from which
+flex
+constructs its scanners. You'll never need this option unless you are doing
+flex
+maintenance or development.
+
+@anchor{Option-Always-Interactive}
+
`--always-interactive'
+
+instructs flex to generate a scanner which always considers its input
+interactive. Normally, on each new input file the scanner calls
+isatty() in an attempt to determine whether the scanner's input
+source is interactive and thus should be read a character at a time.
+When this option is used, however, then no such call is made.
+
+
`--main'
+
+ directs flex to provide a default main() program for the
+scanner, which simply calls yylex(). This option implies
+noyywrap (see below).
+
+
`--never-interactive'
+
+instructs flex to generate a scanner which never considers its input
+interactive. This is the opposite of always-interactive.
+
+
`--nounistd'
+
+suppresses inclusion of the non-ANSI header file `unistd.h'. This option
+is meant to target environments in which `unistd.h' does not exist. Be aware
+that certain options may cause flex to generate code that relies on functions
+normally found in `unistd.h', (e.g. isatty(), read().)
+If you wish to use these functions, you will have to inform your compiler where
+to find them.
+@xref{Option-Always-Interactive}. @xref{Option-Read}.
+
+
`--stack'
+
+enables the use of
+start condition stacks (see section Start Conditions).
+
+
`--stdinit'
+
+if set (i.e., %option stdinit) initializes yyin and
+yyout to `stdin' and `stdout', instead of the default of
+`nil'. Some existing lex programs depend on this behavior,
+even though it is not compliant with ANSI C, which does not require
+`stdin' and `stdout' to be compile-time constant. In a
+reentrant scanner, however, this is not a problem since initialization
+is performed in yylex_init at runtime.
+
+
`--yylineno'
+
+directs flex to generate a scanner
+that maintains the number of the current line read from its input in the
+global variable yylineno. This option is implied by %option
+lex-compat. In a reentrant C scanner, the macro yylineno is
+accessible regardless of the value of %option yylineno, however, its
+value is not modified by flex unless %option yylineno is enabled.
+
+
`--yywrap'
+
+if unset (i.e., --noyywrap), makes the scanner not call
+yywrap() upon an end-of-file, but simply assume that there are no
+more files to scan (until the user points `yyin' at a new file and
+calls yylex() again).
+
+flex also provides a mechanism for controlling options within the
+scanner specification itself, rather than from the flex command-line.
+This is done by including %option directives in the first section
+of the scanner specification. You can specify multiple options with a
+single %option directive, and multiple directives in the first
+section of your flex input file.
+
+
+
+Most options are given simply as names, optionally preceded by the
+word `no' (with no intervening whitespace) to negate their meaning.
+The names are the same as their long-option equivalents (but without the
+leading `--' ).
+
+
+
+
+flex scans your rule actions to determine whether you use the
+REJECT or yymore() features. The REJECT and
+yymore options are available to override its decision as to
+whether you use the options, either by setting them (e.g., %option
+reject) to indicate the feature is indeed used, or unsetting them to
+indicate it actually is not used (e.g., %option noyymore).
+
+
+
+%option yyclass
+only applies when generating a C++ scanner (the `--c++' option). It
+informs flex that you have derived foo as a subclass of
+yyFlexLexer, so flex will place your actions in the member
+function foo::yylex() instead of yyFlexLexer::yylex(). It
+also generates a yyFlexLexer::yylex() member function that emits
+a run-time error (by invoking yyFlexLexer::LexerError()) if
+called. See section Generating C++ Scanners.
+
+
+
+A number of options are available for lint purists who want to suppress
+the appearance of unneeded routines in the generated scanner. Each of
+the following, if unset (e.g., %option nounput), results in the
+corresponding routine not appearing in the generated scanner:
+
+
+
+
+
+The main design goal of flex is that it generate high-performance
+scanners. It has been optimized for dealing well with large sets of
+rules. Aside from the effects on scanner speed of the table compression
+`-C' options outlined above, there are a number of options/actions
+which degrade performance. These are, from most expensive to least:
+
+
+
+with the first three all being quite expensive and the last two being
+quite cheap. Note also that unput() is implemented as a routine
+call that potentially does quite a bit of work, while yyless() is
+a quite-cheap macro. So if you are just putting back some excess text
+you scanned, use ss().
+
+
+
+REJECT should be avoided at all costs when performance is
+important. It is a particularly expensive option.
+
+
+
+
+
+
+Getting rid of backing up is messy and often may be an enormous amount
+of work for a complicated scanner. In principal, one begins by using
+the `-b' flag to generate a `lex.backup' file. For example,
+on the input:
+
+
+
+@verbatim
+ State #6 is non-accepting -
+ associated rule line numbers:
+ 2 3
+ out-transitions: [ o ]
+ jam-transitions: EOF [ \001-n p-\177 ]
+
+ State #8 is non-accepting -
+ associated rule line numbers:
+ 3
+ out-transitions: [ a ]
+ jam-transitions: EOF [ \001-` b-\177 ]
+
+ State #9 is non-accepting -
+ associated rule line numbers:
+ 3
+ out-transitions: [ r ]
+ jam-transitions: EOF [ \001-q s-\177 ]
+
+ Compressed tables always back up.
+
+
+
+The first few lines tell us that there's a scanner state in which it can
+make a transition on an 'o' but not on any other character, and that in
+that state the currently scanned text does not match any rule. The
+state occurs when trying to match the rules found at lines 2 and 3 in
+the input file. If the scanner is in that state and then reads
+something other than an 'o', it will have to back up to find a rule
+which is matched. With a bit of headscratching one can see that this
+must be the state it's in when it has seen `fo'. When this has
+happened, if anything other than another `o' is seen, the scanner
+will have to back up to simply match the `f' (by the default rule).
+
+
+
+The comment regarding State #8 indicates there's a problem when
+`foob' has been scanned. Indeed, on any character other than an
+`a', the scanner will have to back up to accept "foo". Similarly,
+the comment for State #9 concerns when `fooba' has been scanned and
+an `r' does not follow.
+
+
+
+The final comment reminds us that there's no point going to all the
+trouble of removing backing up from the rules unless we're using
+`-Cf' or `-CF', since there's no performance gain doing so
+with compressed scanners.
+
+
+
+
+The way to remove the backing up is to add "error" rules:
+
+
+
+This is usually the best solution when appropriate.
+
+
+
+Backing up messages tend to cascade. With a complicated set of rules
+it's not uncommon to get hundreds of messages. If one can decipher
+them, though, it often only takes a dozen or so rules to eliminate the
+backing up (though it's easy to make a mistake and have an error rule
+accidentally match a valid token. A possible future flex feature
+will be to automatically add rules to eliminate backing up).
+
+
+
+It's important to keep in mind that you gain the benefits of eliminating
+backing up only if you eliminate every instance of backing up.
+Leaving just one means you gain nothing.
+
+
+
+Variable trailing context (where both the leading and trailing
+parts do not have a fixed length) entails almost the same performance
+loss as REJECT (i.e., substantial). So when possible a rule
+like:
+
+
+
+Note that here the special '|' action does not provide any
+savings, and can even make things worse (see section Limitations).
+
+
+
+Another area where the user can increase a scanner's performance (and
+one that's easier to implement) arises from the fact that the longer the
+tokens matched, the faster the scanner will run. This is because with
+long tokens the processing of most input characters takes place in the
+(short) inner scanning loop, and does not often have to go through the
+additional work of setting up the scanning environment (e.g.,
+yytext) for the action. Recall the scanner for C comments:
+
+
+
+Now instead of each newline requiring the processing of another action,
+recognizing the newlines is distributed over the other rules to keep the
+matched text as long as possible. Note that adding rules does
+not slow down the scanner! The speed of the scanner is
+independent of the number of rules or (modulo the considerations given
+at the beginning of this section) how complicated the rules are with
+regard to operators such as `*' and `|'.
+
+
+
+
+
+A final example in speeding up a scanner: suppose you want to scan
+through a file containing identifiers and keywords, one per line
+and with no other extraneous characters, and recognize all the
+keywords. A natural first approach is:
+
+
+
+
+
+
+@verbatim
+ %%
+ asm |
+ auto |
+ break |
+ ... etc ...
+ volatile |
+ while /* it's a keyword */
+
+ .|\n /* it's not a keyword */
+
+
+
+To eliminate the back-tracking, introduce a catch-all rule:
+
+
+
+
+@verbatim
+ %%
+ asm |
+ auto |
+ break |
+ ... etc ...
+ volatile |
+ while /* it's a keyword */
+
+ [a-z]+ |
+ .|\n /* it's not a keyword */
+
+
+
+Now, if it's guaranteed that there's exactly one word per line, then we
+can reduce the total number of matches by a half by merging in the
+recognition of newlines with that of the other tokens:
+
+
+
+
+One has to be careful here, as we have now reintroduced backing up
+into the scanner. In particular, while
+we
+know that there will never be any characters in the input stream
+other than letters or newlines,
+flex
+can't figure this out, and it will plan for possibly needing to back up
+when it has scanned a token like `auto' and then the next character
+is something other than a newline or a letter. Previously it would
+then just match the `auto' rule and be done, but now it has no `auto'
+rule, only a `auto\n' rule. To eliminate the possibility of backing up,
+we could either duplicate all rules but without final newlines, or,
+since we never expect to encounter such an input and therefore don't
+how it's classified, we can introduce one more catch-all rule, this
+one which doesn't include a newline:
+
+
+
+
+Compiled with `-Cf', this is about as fast as one can get a
+flex scanner to go for this particular problem.
+
+
+
+A final note: flex is slow when matching NULs,
+particularly when a token contains multiple NULs. It's best to
+write rules which match short amounts of text if it's anticipated
+that the text will often include NULs.
+
+
+
+Another final note regarding performance: as mentioned in
+section How the Input Is Matched, dynamically resizing yytext to accommodate huge
+tokens is a slow process because it presently requires that the (huge)
+token be rescanned from the beginning. Thus if performance is vital,
+you should attempt to match "large" quantities of text but not
+"huge" quantities, where the cutoff between the two is at about 8K
+characters per token.
+
+
+
+
+
+
+
+
+flex provides two different ways to generate scanners for use
+with C++. The first way is to simply compile a scanner generated by
+flex using a C++ compiler instead of a C compiler. You should
+not encounter any compilation errors (see section Reporting Bugs). You can
+then use C++ code in your rule actions instead of C code. Note that the
+default input source for your scanner remains `yyin', and default
+echoing is still done to `yyout'. Both of these remain FILE
+* variables and not C++ streams.
+
+
+
+You can also use flex to generate a C++ scanner class, using the
+`-+' option (or, equivalently, %option c++), which is
+automatically specified if the name of the flex executable ends
+in a '+', such as flex++. When using this option, flex
+defaults to generating the scanner to the file `lex.yy.cc' instead
+of `lex.yy.c'. The generated scanner includes the header file
+`FlexLexer.h', which defines the interface to two C++ classes.
+
+
+
+The first class,
+FlexLexer,
+provides an abstract base class defining the general scanner class
+interface. It provides the following member functions:
+
+
+
+
+
const char* YYText()
+
+
+
+returns the text of the most recently matched token, the equivalent of
+yytext.
+
+
+
int YYLeng()
+
+returns the length of the most recently matched token, the equivalent of
+yyleng.
+
+
+
int lineno() const
+
+returns the current input line number (see %option yylineno), or
+1 if %option yylineno was not used.
+
+
+
void set_debug( int flag )
+
+sets the debugging flag for the scanner, equivalent to assigning to
+yy_flex_debug (see section Invoking Flex). Note that you must build
+the scannerusing %option debug to include debugging information
+in it.
+
+
+
int debug() const
+
+returns the current setting of the debugging flag.
+
+
+
+Also provided are member functions equivalent to
+yy_switch_to_buffer(), yy_create_buffer() (though the
+first argument is an istream* object pointer and not a
+FILE*), yy_flush_buffer(), yy_delete_buffer(), and
+yyrestart() (again, the first argument is a istream*
+object pointer).
+
+
+
+
+
+The second class defined in `FlexLexer.h' is yyFlexLexer,
+which is derived from FlexLexer. It defines the following
+additional member functions:
+
+
+
+
+
+constructs a yyFlexLexer object using the given streams for input
+and output. If not specified, the streams default to cin and
+cout, respectively.
+
+
+
virtual int yylex()
+
+performs the same role is yylex() does for ordinary flex
+scanners: it scans the input stream, consuming tokens, until a rule's
+action returns a value. If you derive a subclass S from
+yyFlexLexer and want to access the member functions and variables
+of S inside yylex(), then you need to use %option
+yyclass="S" to inform flex that you will be using that subclass
+instead of yyFlexLexer. In this case, rather than generating
+yyFlexLexer::yylex(), flex generates S::yylex()
+(and also generates a dummy yyFlexLexer::yylex() that calls
+yyFlexLexer::LexerError() if called).
+
+
+
+reassigns yyin to new_in (if non-nil) and yyout to
+new_out (if non-nil), deleting the previous input buffer if
+yyin is reassigned.
+
+
int yylex( istream* new_in, ostream* new_out = 0 )
+
+first switches the input streams via switch_streams( new_in,
+new_out ) and then returns the value of yylex().
+
+
+
+In addition, yyFlexLexer defines the following protected virtual
+functions which you can redefine in derived classes to tailor the
+scanner:
+
+
+
+
+
virtual int LexerInput( char* buf, int max_size )
+
+
+
+reads up to max_size characters into buf and returns the
+number of characters read. To indicate end-of-input, return 0
+characters. Note that interactive scanners (see the `-B'
+and `-I' flags in section Invoking Flex) define the macro
+YY_INTERACTIVE. If you redefine LexerInput() and need to
+take different actions depending on whether or not the scanner might be
+scanning an interactive input source, you can test for the presence of
+this name via #ifdef statements.
+
+
+
virtual void LexerOutput( const char* buf, int size )
+
+writes out size characters from the buffer buf, which, while
+NUL-terminated, may also contain internal NULs if the
+scanner's rules can match text with NULs in them.
+
+
+
+
virtual void LexerError( const char* msg )
+
+reports a fatal error message. The default version of this function
+writes the message to the stream cerr and exits.
+
+
+
+Note that a yyFlexLexer object contains its entire
+scanning state. Thus you can use such objects to create reentrant
+scanners. You can instantiate multiple instances of the same
+yyFlexLexer class, and you can also combine multiple C++ scanner
+classes together in the same program using the `-P' option
+discussed above.
+
+
+
+Finally, note that the %array feature is not available to C++
+scanner classes; you must use %pointer (the default).
+
+
+
+Here is an example of a simple C++ scanner:
+
+
+
+
+If you want to create multiple (different) lexer classes, you use the
+`-P' flag (or the prefix= option) to rename each
+yyFlexLexer to some other `xxFlexLexer'. You then can
+include `FlexLexer.h>' in your other sources once per lexer class,
+first renaming yyFlexLexer as follows:
+
+
+
+
+flex has the ability to generate a reentrant C scanner. This is
+accomplished by specifying %option reentrant (`-R') or
+%option reentrant-bison (`-Rb'). The generated scanner is
+both portable, and safe to use in one or more separate threads of
+control. The most common use for reentrant scanners is from within
+multi-threaded applications. Any thread may create and execute a
+reentrant flex scanner without the need for synchronization with
+other threads.
+
+
+
+
+
+However, there are other uses for a reentrant scanner. For example, you
+could scan two or more files simultaneously to implement a diff at
+the token level (i.e., instead of at the character level):
+
+
+
+
+
+
+@verbatim
+ /* Example of maintaining more than one active scanner. */
+
+ do {
+ int tok1, tok2;
+
+ tok1 = yylex( scanner_1 );
+ tok2 = yylex( scanner_2 );
+
+ if( tok1 != tok2 )
+ printf("Files are different.");
+
+ } while ( tok1 && tok2 );
+
+
+
+Another use for a reentrant scanner is recursion.
+(Note that a recursive scanner can also be created using a non-reentrant scanner and
+buffer states. See section Multiple Input Buffers.)
+
+
+
+The following crude scanner supports the `eval' command by invoking
+another instance of itself.
+
+
+
+ %option reentrant (--reentrant) must be specified.
+
+
+
+Notice that %option reentrant is specified in the above example
+(see section Reentrant Example. Had this option not been specified,
+flex would have happily generated a non-reentrant scanner without
+complaining. You may explicitly specify %option noreentrant, if
+you do not want a reentrant scanner, although it is not
+necessary. The default is to generate a non-reentrant scanner.
+
+
+
+
+
+
+
+All functions take one additional argument: yy_globals.
+
+
+
+Notice that the calls to yy_push_state and yy_pop_state
+both have an argument, yy_globals , that is not present in a
+non-reentrant scanner. Here are the declarations of
+yy_push_state and yy_pop_state in the generated scanner:
+
+
+
+
+Notice that the argument yy_globals appears in the declaration of
+both functions. In fact, all flex functions in a reentrant
+scanner have this additional argument. It is always the last argument
+in the argument list, it is always of type yyscan_t (which is
+typedef'd to void *) and it is
+always named yy_globals. As you may have guessed,
+yy_globals is a pointer to an opaque data structure encapsulating
+the current state of the scanner. For a list of function declarations,
+see section Functions and Macros Available in Reentrant C Scanners. Note that preprocessor macros, such as
+BEGIN, ECHO, and REJECT, do not take this
+additional argument.
+
+
+
+
+
+
+All global variables in traditional flex have been replaced by macro equivalents.
+
+
+
+Note that in the above example, yyout and yytext are
+not plain variables. These are macros that will expand to their equivalent lvalue.
+All of the familiar flex globals have been replaced by their macro
+equivalents. In particular, yytext, yyleng, yylineno,
+yyin, yyout, yyextra, yylval, and yylloc
+are macros. You may safely use these macros in actions as if they were plain
+variables. We only tell you this so you don't expect to link to these variables
+externally. Currently, each macro expands to a member of an internal struct, e.g.,
+
+
+
+
+One important thing to remember about
+yytext
+and friends is that
+yytext
+is not a global variable in a reentrant
+scanner, you can not access it directly from outside an action or from
+other functions. You must use an accessor method, e.g.,
+yyget_text,
+to accomplish this. (See below).
+
+
+
+
+
+yylex_init and yylex_destroy must be called before and
+after yylex, respectively.
+
+
+
+
+@verbatim
+ int yylex_init ( yyscan_t * ptr_yy_globals ) ;
+ int yylex ( yyscan_t yy_globals ) ;
+ int yylex_destroy ( yyscan_t yy_globals ) ;
+
+
+
+The function yylex_init must be called before calling any other
+function. The argument to yylex_init is the address of an
+uninitialized pointer to be filled in by flex. The contents of
+ptr_yy_globals need not be initialized, since flex will
+overwrite it anyway. The value stored in ptr_yy_globals should
+thereafter be passed to yylex() and yylex_destroy(). Flex
+does not save the argument passed to yylex_init, so it is safe to
+pass the address of a local pointer to yylex_init. The function
+yylex should be familiar to you by now. The reentrant version
+takes one argument, which is the value returned (via an argument) by
+yylex_init. Otherwise, it behaves the same as the non-reentrant
+version of yylex.
+
+
+
+The function yylex_destroy should be
+called to free resources used by the scanner. After yylex_destroy
+is called, the contents of yy_globals should not be used. Of
+course, there is no need to destroy a scanner if you plan to reuse it.
+A flex scanner (both reentrant and non-reentrant) may be
+restarted by calling yyrestart.
+
+
+
+Below is an example of a program that creates a scanner, uses it, then destroys
+it when done:
+
+
+
+
+@verbatim
+ int main ()
+ {
+ yyscan_t scanner;
+ int tok;
+
+ yylex_init(&scanner);
+
+ while ((tok=yylex()) > 0)
+ printf("tok=%d yytext=%s\n", tok, yyget_text(scanner));
+
+ yylex_destroy(scanner);
+ return 0;
+ }
+
+
+Accessor methods (get/set functions) provide access to common
+flex variables.
+
+
+
+Many scanners that you build will be part of a larger project. Portions
+of your project will need access to flex values, such as
+yytext. In a non-reentrant scanner, these values are global, so
+there is no problem accessing them. However, in a reentrant scanner, there are no
+global flex values. You can not access them directly. Instead,
+you must access flex values using accessor methods (get/set
+functions). Each accessor method is named yyget_NAME or
+yyset_NAME, where NAME is the name of the flex
+variable you want. For example:
+
+
+
+
+
+
+@verbatim
+ /* Set the last character of yytext to NULL. */
+ void chop ( yyscan_t scanner )
+ {
+ int len = yyget_leng( scanner );
+ yyget_text( scanner )[len - 1] = '\0';
+ }
+
+
+
+The above code may be called from within an action like this:
+
+
+
+
+
+
+User-specific data can be stored in yyextra.
+
+
+
+In a reentrant scanner, it is unwise to use global variables to
+communicate with or maintain state between different pieces of your program.
+However, you may need access to external data or invoke external functions
+from within the scanner actions.
+Likewise, you may need to pass information to your scanner
+(e.g., open file descriptors, or database connections).
+In a non-reentrant scanner, the only way to do this would be through the
+use of global variables.
+Flex allows you to store arbitrary, "extra" data in a scanner.
+This data is accessible through the accessor methods
+yyget_extra
+and
+yyset_extra
+from outside the scanner, and through the shortcut macro
+yyextra
+from within the scanner itself. They are defined as follows:
+
+
+
+By default, YY_EXTRA_TYPE is defined as type void *. You
+will have to cast yyextra and the return value from
+yyget_extra to the appropriate value each time you access the
+extra data. To avoid casting, you may override the default type by
+defining YY_EXTRA_TYPE in section 1 of your scanner:
+
+
+
+It is initialized by yylex_init() to point to
+an internal structure. You should never access this value
+directly. In particular, you should never attempt to free it
+(use yylex_destroy() instead.)
+
+
+
+
+
+This section describes the flex features useful when integrating
+flex with GNU bison(1).
+Skip this section if you are not using
+bison with your scanner. Here we discuss only the flex
+half of the flex and bison pair. We do not discuss
+bison in any detail. For more information about generating pure
+bison parsers, see section `Top' in the GNU Bison Manual.
+
+
+
+A bison-compatible scanner is generated by declaring `%option
+reentrant-bison' or by supplying `--reentrant-bison' when invoking flex
+from the command line. This instructs flex that the macros
+yylval and yylloc may be used. The data types for
+yylval and yylloc, (YYSTYPE and YYLTYPE,
+are typically defined in a header file, included in section 1 of the
+flex input file. %option reentrant-bison implies
+%option reentrant. If %option reentrant-bison is
+specified, flex provides support for the functions
+yyget_lval, yyset_lval, yyget_lloc, and
+yyset_lloc, defined below, and the corresponding macros
+yylval and yylloc, for use within actions.
+
+
+
+Note that the macros yylval and yylloc evaluate to
+pointers. Support for yylloc is optional in bison, so it
+is optional in flex as well. This support is automatically
+handled by flex. Specifically, support for yyloc is only
+present in a flex scanner if the preprocessor symbol
+YYLTYPE is defined. The following is an example of a flex
+scanner that is bison-compatible.
+
+
+
+As you can see, there really is no magic here. We just use
+yylval as we would any other variable. The data type of
+yylval is generated by bison, and included in the file
+`y.tab.h'. Here is the corresponding bison parser:
+
+
+
+
+
+
+@verbatim
+ /* Parser to convert "C" assignments to lisp. */
+ %{
+ /* Pass the argument to yyparse through to yylex. */
+ #define YYPARSE_PARAM scanner
+ #define YYLEX_PARAM scanner
+ %}
+ %pure_parser
+ %union {
+ int num;
+ char* str;
+ }
+ %token <str> STRING
+ %token <num> NUMBER
+ %%
+ assignment:
+ STRING '=' NUMBER ';' {
+ printf( "(setf %s %d)", $1, $3 );
+ }
+ ;
+
+
+In a reentrant C scanner, support for yylineno is always present
+(i.e., you may access yylineno), but the value is never modified by
+flex unless %option yylineno is enabled. This is to allow
+the user to maintain the line count independently of flex.
+
+
+
+The following functions and macros are made available when %option
+reentrant-bison (`--reentrant-bison') is specified:
+
+
+
+
+Support for yylloc is dependent upon the presence of the preprocessor
+symbol YYLTYPE. Support for yylval relies on the type
+YYSTYPE to be defined. Typically, these definitions are generated
+by bison, in a .h file, and are included in section 1 of the
+flex input.
+
+
+
+
+
+flex is a rewrite of the AT&T Unix lex tool (the two
+implementations do not share any code, though), with some extensions and
+incompatibilities, both of which are of concern to those who wish to
+write scanners acceptable to both implementations. flex is fully
+compliant with the POSIX lex specification, except that when
+using %pointer (the default), a call to unput() destroys
+the contents of yytext, which is counter to the POSIX
+specification. In this section we discuss all of the known areas of
+incompatibility between flex, AT&T lex, and the POSIX
+specification. flex's `-l' option turns on maximum
+compatibility with the original AT&T lex implementation, at the
+cost of a major loss in the generated scanner's performance. We note
+below which incompatibilities can be overcome using the `-l'
+option. flex is fully compatible with lex with the
+following exceptions:
+
+
+
+
+
+
+The undocumented lex scanner internal variable yylineno is
+not supported unless `-l' or %option yylineno is used.
+
+
+
+yylineno should be maintained on a per-buffer basis, rather than
+a per-scanner (single global variable) basis.
+
+
+
+yylineno is not part of the POSIX specification.
+
+
+
+The input() routine is not redefinable, though it may be called
+to read characters following whatever has been matched by a rule. If
+input() encounters an end-of-file the normal yywrap()
+processing is done. A "real" end-of-file is returned by
+input() as EOF.
+
+
+
+Input is instead controlled by defining the YY_INPUT() macro.
+
+
+
+The flex restriction that input() cannot be redefined is
+in accordance with the POSIX specification, which simply does not
+specify any way of controlling the scanner's input other than by making
+an initial assignment to `yyin'.
+
+
+
+The unput() routine is not redefinable. This restriction is in
+accordance with POSIX.
+
+
+
+flex scanners are not as reentrant as lex scanners. In
+particular, if you have an interactive scanner and an interrupt handler
+which long-jumps out of the scanner, and the scanner is subsequently
+called again, you may get the following message:
+
+
+
+
+
+Note that this call will throw away any buffered input; usually this
+isn't a problem with an interactive scanner. See section Reentrant C Scanners, for
+flex's reentrant API.
+
+
+
+Also note that flex C++ scanner classes
+are
+reentrant, so if using C++ is an option for you, you should use
+them instead. See section Generating C++ Scanners, and section Reentrant C Scanners for details.
+
+
+
+output() is not supported. Output from the ECHO macro is
+done to the file-pointer yyout (default `stdout)'.
+
+
+
+output() is not part of the POSIX specification.
+
+
+
+lex does not support exclusive start conditions (%x), though they
+are in the POSIX specification.
+
+
+
+When definitions are expanded, flex encloses them in parentheses.
+With lex, the following:
+
+
+
+
+
+will not match the string `foo' because when the macro is expanded
+the rule is equivalent to `foo[A-Z][A-Z0-9]*?' and the precedence
+is such that the `?' is associated with `[A-Z0-9]*'. With
+flex, the rule will be expanded to `foo([A-Z][A-Z0-9]*)?'
+and so the string `foo' will match.
+
+
+
+Note that if the definition begins with `^' or ends with `$'
+then it is not expanded with parentheses, to allow these
+operators to appear in definitions without losing their special
+meanings. But the `<s>', `/', and <<EOF>> operators
+cannot be used in a flex definition.
+
+
+
+Using `-l' results in the lex behavior of no parentheses
+around the definition.
+
+
+
+The POSIX specification is that the definition be enclosed in parentheses.
+
+
+
+Some implementations of lex allow a rule's action to begin on a
+separate line, if the rule's pattern has trailing whitespace:
+
+
+
+
+
+The lex%r (generate a Ratfor scanner) option is not
+supported. It is not part of the POSIX specification.
+
+
+
+After a call to unput(), yytext is undefined until the
+next token is matched, unless the scanner was built using %array.
+This is not the case with lex or the POSIX specification. The
+`-l' option does away with this incompatibility.
+
+
+
+The precedence of the `{,}' (numeric range) operator is
+different. The AT&T and POSIX specifications of lex
+interpret `abc{1,3}' as match one, two,
+or three occurrences of `abc'", whereas flex interprets it
+as "match `ab' followed by one, two, or three occurrences of
+`c'". The `-l' and `--posix' options do away with this
+incompatibility.
+
+
+
+The precedence of the `^' operator is different. lex
+interprets `^foo|bar' as "match either 'foo' at the beginning of a
+line, or 'bar' anywhere", whereas flex interprets it as "match
+either `foo' or `bar' if they come at the beginning of a
+line". The latter is in agreement with the POSIX specification.
+
+
+
+The special table-size declarations such as %a supported by
+lex are not required by flex scanners.. flex
+ignores them.
+
+
+The name FLEX_SCANNER is #define'd so scanners may be
+written for use with either flex or lex. Scanners also
+include YY_FLEX_MAJOR_VERSION and YY_FLEX_MINOR_VERSION
+indicating which version of flex generated the scanner (for
+example, for the 2.5 release, these defines would be 2 and 5
+respectively).
+
+
+
+
+
+
+
+The following flex features are not included in lex or the
+POSIX specification:
+
+
+
+
+@verbatim
+ C++ scanners
+ %option
+ start condition scopes
+ start condition stacks
+ interactive/non-interactive scanners
+ yy_scan_string() and friends
+ yyterminate()
+ yy_set_interactive()
+ yy_set_bol()
+ YY_AT_BOL()
+ <<EOF>>
+ <*>
+ YY_DECL
+ YY_START
+ YY_USER_ACTION
+ YY_USER_INIT
+ #line directives
+ %{}'s around actions
+ reentrant C API
+ multiple actions on a line
+
+
+
+plus almost all of the flex flags. The last feature in the list
+refers to the fact that with flex you can put multiple actions on
+the same line, separated with semi-colons, while with lex, the
+following:
+
+
+
+
+@verbatim
+ foo handle_foo(); ++num_foos_seen;
+
+
+
+is (rather surprisingly) truncated to
+
+
+
+
+@verbatim
+ foo handle_foo();
+
+
+
+flex does not truncate the action. Actions that are not enclosed
+in braces are simply terminated at the end of the line.
+
+
+
+
+
+The following is a list of flex diagnostic messages:
+
+
+
+
+
+
+`warning, rule cannot be matched' indicates that the given rule
+cannot be matched because it follows other rules that will always match
+the same text as it. For example, in the following `foo' cannot be
+matched because it comes after an identifier "catch-all" rule:
+
+
+
+
+
+Using REJECT in a scanner suppresses this warning.
+
+
+
+`warning, -s option given but default rule can be matched' means
+that it is possible (perhaps only in a particular start condition) that
+the default rule (match any single character) is the only one that will
+match a particular input. Since `-s' was given, presumably this is
+not intended.
+
+
+
+reject_used_but_not_detected undefined or
+yymore_used_but_not_detected undefined. These errors can occur
+at compile time. They indicate that the scanner uses REJECT or
+yymore() but that flex failed to notice the fact, meaning
+that flex scanned the first two sections looking for occurrences
+of these actions and failed to find any, but somehow you snuck some in
+(via a #include file, for example). Use %option reject or
+%option yymore to indicate to flex that you really do use
+these features.
+
+
+
+`flex scanner jammed'. a scanner compiled with
+`-s' has encountered an input string which wasn't matched by any of
+its rules. This error can also occur due to internal problems.
+
+
+
+`token too large, exceeds YYLMAX'. your scanner uses %array
+and one of its rules matched a string longer than the YYLMAX
+constant (8K bytes by default). You can increase the value by
+#define'ing YYLMAX in the definitions section of your flex
+input.
+
+
+
+`scanner requires -8 flag to use the character 'x''. Your scanner
+specification includes recognizing the 8-bit character `'x'' and
+you did not specify the -8 flag, and your scanner defaulted to 7-bit
+because you used the `-Cf' or `-CF' table compression options.
+See the discussion of the `-7' flag, section Invoking Flex, for
+details.
+
+
+
+`flex scanner push-back overflow'. you used unput() to push
+back so much text that the scanner's buffer could not hold both the
+pushed-back text and the current token in yytext. Ideally the
+scanner should dynamically resize the buffer in this case, but at
+present it does not.
+
+
+
+`input buffer overflow, can't enlarge buffer because scanner uses
+REJECT'. the scanner was working on matching an extremely large token
+and needed to expand the input buffer. This doesn't work with scanners
+that use REJECT.
+
+
+
+`fatal flex scanner internal error--end of buffer missed'. This can
+occur in a scanner which is reentered after a long-jump has jumped out
+(or over) the scanner's activation frame. Before reentering the
+scanner, use:
+
+
+@verbatim
+ yyrestart( yyin );
+
+
+or, as noted above, switch to using the C++ scanner class.
+
+
+
+`too many start conditions in <> construct!' you listed more start
+conditions in a <> construct than exist (so you must have listed at
+least one of them twice).
+
+Some trailing context patterns cannot be properly matched and generate
+warning messages (`dangerous trailing context'). These are
+patterns where the ending of the first part of the rule matches the
+beginning of the second part, such as `zx*/xy*', where the 'x*'
+matches the 'x' at the beginning of the trailing context. (Note that
+the POSIX draft states that the text matched by such patterns is
+undefined.) For some trailing context rules, parts which are actually
+fixed-length are not recognized as such, leading to the abovementioned
+performance loss. In particular, parts using `|' or `{n}'
+(such as `foo{3}') are always considered variable-length.
+Combining trailing context with the special `|' action can result
+in fixed trailing context being turned into the more expensive
+variable trailing context. For example, in the following:
+
+
+
+
+
+
+@verbatim
+ %%
+ abc |
+ xyz/def
+
+
+
+Use of unput() invalidates yytext and yyleng, unless the
+%array directive or the `-l' option has been used.
+Pattern-matching of NULs is substantially slower than matching
+other characters. Dynamic resizing of the input buffer is slow, as it
+entails rescanning all the text matched so far by the current (generally
+huge) token. Due to both buffering of input and read-ahead, you cannot
+intermix calls to `<stdio.h>' routines, such as, getchar(),
+with flex rules and expect it to work. Call input()
+instead. The total table entries listed by the `-v' flag excludes
+the number of table entries needed to determine what rule has been
+matched. The number of entries is equal to the number of DFA states if
+the scanner does not use REJECT, and somewhat greater than the
+number of states if it does. REJECT cannot be used with the
+`-f' or `-F' options.
+
+
+
+You may wish to read more about the following programs:
+
+
+
lex
+
+
yacc
+
+
sed
+
+
awk
+
+
+
+
+The following books may contain material of interest:
+
+
+
+John Levine, Tony Mason, and Doug Brown,
+Lex & Yacc,
+O'Reilly and Associates. Be sure to get the 2nd edition.
+
+
+
+M. E. Lesk and E. Schmidt,
+LEX -- Lexical Analyzer Generator
+
+
+
+Alfred Aho, Ravi Sethi and Jeffrey Ullman, Compilers: Principles,
+Techniques and Tools, Addison-Wesley (1986). Describes the
+pattern-matching techniques used by flex (deterministic finite
+automata).
+
+
+
+
+
+The flex manual is placed under the same licensing conditions as the
+rest of flex:
+
+
+
+Copyright (C) 1990, 1997 The Regents of the University of California.
+All rights reserved.
+
+
+
+This code is derived from software contributed to Berkeley by
+Vern Paxson.
+
+
+
+The United States Government has rights in this work pursuant
+to contract no. DE-AC03-76SF00098 between the United States
+Department of Energy and the University of California.
+
+
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+
+
+
+
+
+Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+
+
+
+Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+
+
+Neither the name of the University nor the names of its contributors
+may be used to endorse or promote products derived from this software
+without specific prior written permission.
+
+
+
+THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.
+
+
+
+
+
+If you have problems with flex or think you have found a bug,
+please send mail detailing your problem to
+help-flex@gnu.org. Patches are always welcome.
+
+
+
+
+
+Vern Paxson took over
+the Software Tools lex project from Jef Poskanzer in 1982. At that point it
+was written in Ratfor. Around 1987 or so, Paxson translated it into C, and
+a legend was born :-).
+
+
+
+
+
+How do I expand \ escape sequences in C-style quoted strings?
+
+
+
+A key point when scanning quoted strings is that you cannot (easily) write
+a single rule that will precisely match the string if you allow things
+like embedded escape sequences and newlines. If you try to match strings
+with a single rule then you'll wind up having to rescan the string anyway
+to find any escape sequences.
+
+
+
+Instead you use exclusive start conditions and a set of rules, one for
+matching non-escaped text, one for matching a single escape, one for
+matching an embedded newline, and one for recognizing the end of the
+string. Each of these rules is then faced with the question of where to
+put its intermediary results. The best solution is for the rules to
+append their local value of yytext to the end of a "string literal"
+buffer. A rule like the escape-matcher will append to the buffer the
+meaning of the escape sequence rather than the literal text in yytext.
+In this way, yytext does not need to be modified at all.
+
+
+
+
+
+Why do flex scanners call fileno if it is not ANSI compatible?
+
+
+
+Flex scanners call fileno() in order to get the file descriptor
+corresponding to yyin. The file descriptor may be passed to
+isatty() or read(), depending upon which %options you specified.
+If your system does not have fileno() support. To get rid of the
+read() call, do not specify %option read. To get rid of the isatty()
+call, you must specify one of %option always-interactive or
+%option never-interactive.
+
+
+
+
+
+No. You cannot have recursive definitions. The pattern-matching power of
+regular expressions in general (and therefore flex scanners, too) is
+limited. In particular, regular expressions cannot "balance" parentheses
+to an arbitrary degree. For example, it's impossible to write a regular
+expression that matches all strings containing the same number of '{'s
+as '}'s. For more powerful pattern matching, you need a parser, such
+as GNU bison.
+
+
+
+
+
+Flex is not matching my patterns in the same order that I defined them.
+
+
+
+This is indeed the natural way to expect it to work, however, flex picks the
+rule that matches the most text (i.e., the longest possible input string).
+This is because flex uses an entirely different matching technique
+("deterministic finite automata") that actually does all of the matching
+simultaneously, in parallel. (Seems impossible, but it's actually a fairly
+simple technique once you understand the principles.)
+
+
+
+A side-effect of this parallel matching is that when the input matches more
+than one rule, flex scanners pick the rule that matched the *most* text. This
+is explained further in the manual, in the section "How the input
+is Matched".
+
+
+
+If you want flex to choose a shorter match, then you can work around this
+behavior by expanding your short
+rule to match more text, then put back the extra:
+
+
+
+
+@verbatim
+data_.* yyless( 5 ); BEGIN BLOCKIDSTATE;
+
+
+
+Another fix would be to make the second rule active only during the
+<BLOCKIDSTATE> start condition, and make that start condition exclusive
+by declaring it with %x instead of %s.
+
+
+
+A final fix is to change the input language so that the ambiguity for
+data_ is removed, by adding characters to it that don't match the
+identifier rule, or by removing characters (such as '_') from the
+identifier rule so it no longer matches "data_". (Of course, you might
+also not have the option of changing the input language ...)
+
+
+
+
+
+My actions are executing out of order or sometimes not at all. What's
+happening?
+
+
+
+Most likely, you have (in error) placed the opening `{' of the action
+block on a different line than the rule, e.g.,
+
+
+
+
+@verbatim
+^(foo|bar)
+ { <<<--- WRONG!
+
+ }
+
+
+
+flex requires that the opening `{' of an action associated with a rule
+begin on the same line as does the rule. You need instead to write your rules
+as follows:
+
+
+
+
+How can I have multiple input sources feed into the same scanner at
+the same time?
+
+
+
+If...
+
+
+
+
+your scanner is free of backtracking (verified using flex's -b flag),
+
+
+AND you run it interactively (-I option; default unless using special table
+compression options),
+
+
+AND you feed it one character at a time by redefining YY_INPUT to do so,
+
+
+
+then every time it matches a token, it will have exhausted its input
+buffer (because the scanner is free of backtracking). This means you
+can safely use select() at the point and only call yylex() for another
+token if select() indicates there's data available.
+
+
+
+That is, move the select() out from the input function to a point where
+it determines whether yylex() gets called for the next token.
+
+
+
+With this approach, you will still have problems if your input can arrive
+piecemeal; select() could inform you that the beginning of a token is
+available, you call yylex() to get it, but it winds up blocking waiting
+for the later characters in the token.
+
+
+
+Here's another way: Move your input multiplexing inside of YY_INPUT. That
+is, whenever YY_INPUT is called, it select()'s to see where input is
+available. If input is available for the scanner, it reads and returns the
+next byte. If input is available from another source, it calls whatever
+function is responsible for reading from that source. (If no input is
+available, it blocks until some is.) I've used this technique in an
+interpreter I wrote that both reads keyboard input using a flex scanner and
+IPC traffic from sockets, and it works fine.
+
+
+
+
+
+Can I build nested parsers that work with the same input file?
+
+
+
+This is not going to work without some additional effort. The reason is
+that flex block-buffers the input it reads from yyin. This means that the
+"outermost" yylex(), when called, will automatically slurp up the first 8K
+of input available on yyin, and subsequent calls to other yylex()'s won't
+see that input. You might be tempted to work around this problem by
+redefining YY_INPUT to only return a small amount of text, but it turns out
+that that approach is quite difficult. Instead, the best solution is to
+combine all of your scanners into one large scanner, using a different
+exclusive start condition for each.
+
+
+
+
+
+How can I match text only at the end of a file?
+
+
+
+There is no way to write a rule which is "match this text, but only if
+it comes at the end of the file". You can fake it, though, if you happen
+to have a character lying around that you don't allow in your input.
+Then you redefine YY_INPUT to call your own routine which, if it sees
+an EOF, returns the magic character first (and remembers to return a
+real EOF next time it's called). Then you could write:
+
+
+
+
+@verbatim
+<COMMENT>(.|\n)*{EOF_CHAR} /* saw comment at EOF */
+
+How can I make REJECT cascade across start condition boundaries?
+
+
+
+You can do this as follows. Suppose you have a start condition A, and
+after exhausting all of the possible matches in <A>, you want to try
+matches in <INITIAL>. Then you could use the following:
+
+
+
+
+@verbatim
+%x A
+%%
+<A>rule_that_is_long ...; REJECT;
+<A>rule ...; REJECT; /* shorter rule */
+<A>etc.
+...
+<A>.|\n {
+ /* Shortest and last rule in <A>, so
+ * cascaded REJECT's will eventually
+ * wind up matching this rule. We want
+ * to now switch to the initial state
+ * and try matching from there instead.
+ */
+ yyless(0); /* put back matched text */
+ BEGIN(INITIAL);
+ }
+
+Why can't I use fast or full tables with interactive mode?
+
+
+
+One of the assumptions
+flex makes is that interactive applications are inherently slow (for just
+that reason, they're waiting on a human).
+It has to do with how the scanner detects that it must be finished scanning
+a token. For interactive scanners, after scanning each character the current
+state is looked up in a table (essentially) to see whether there's a chance
+of another input character possibly extending the length of the match. If
+not, the scanner halts. For non-interactive scanners, the end-of-token test
+is much simpler, basically a compare with 0, so no memory bus cycles. Since
+the test occurs in the innermost scanning loop, one would like to make it go
+as fast as possible.
+
+
+
+Still, it seems reasonable to allow the user to choose to trade off a bit
+of performance in this area to gain the corresponding flexibility. There
+might be another reason, though, why fast scanners don't support the
+interactive option
+
+
+
+
+
+If I have a simple grammar, can't I just parse it with flex?
+
+
+
+Is your grammar recursive? That's almost always a sign that you're
+better off using a parser/scanner rather than just trying to use a scanner
+alone.
+
+
+
+Why doesn't yyrestart() set the start state back to INITIAL?
+
+
+
+There are two reasons. The first is that there might
+be programs that rely on the start state not changing across file changes.
+The second is that with flex 2.4, use of yyrestart() is no longer required,
+so fixing the problem there doesn't solve the more general problem.
+
+
+
+
+
+The '.' (dot) isn't working the way I expected.
+
+
+
+Here are some tips for using `.':
+
+
+
+
+
+
+A common mistake is to place the grouping parenthesis AFTER an operator, when
+you really meant to place the parenthesis BEFORE the operator, e.g., you
+probably want this (foo|bar)+ and NOT this (foo|bar+).
+
+The first pattern matches the words foo or bar any number of
+times, e.g., it matches the text barfoofoobarfoo. The
+second pattern matches a single instance of foo or a single instance of
+ba followed by one or more `r's, e.g., it matches the text barrrr .
+
+
+A `.' inside []'s just means a literal`.' (period),
+and NOT "any character except newline".
+
+
+Remember that `.' matches any character EXCEPT `\n' (and EOF).
+If you really want to match ANY character, including newlines, then use (.|\n)
+--- Beware that the regex (.|\n)+ will match your entire input!
+
+
+Finally, if you want to match a literal `.' (a period), then use [.] or "."
+
+Can I get the flex manual in another format?
+
+
+
+As of flex 2.5, the manual is distributed in texinfo format.
+You can use the "texi2*" tools to convert the manual to any format
+you desire (e.g., `texi2html').
+
+
+
+
+
+Does there exist a "faster" NDFA->DFA algorithm? Most standard texts (e.g.,
+Aho), imply that NDFA->DFA can take exponential time, since there are
+exponential number of potential states in NDFA.
+
+
+
+There's no way around the potential exponential running time - it
+can take you exponential time just to enumerate all of the DFA states.
+In practice, though, the running time is closer to linear, or sometimes
+quadratic.
+
+
+
+
+
+There are two big speed wins that flex uses:
+
+
+
+
+
+
+It analyzes the input rules to construct equivalence classes for those
+characters that always make the same transitions. It then rewrites the NFA
+using equivalence classes for transitions instead of characters. This cuts
+down the NFA->DFA computation time dramatically, to the point where, for
+uncompressed DFA tables, the DFA generation is often I/O bound in writing out
+the tables.
+
+
+It maintains hash values for previously computed DFA states, so testing
+whether a newly constructed DFA state is equivalent to a previously constructed
+state can be done very quickly, by first comparing hash values.
+
+Flex is compiled with an upper limit of 8192 rules per scanner.
+If you need more than 8192 rules in your scanner, you'll have to recompile flex
+with the following changes in flexdef.h:
+
+
+
+
+This should work okay as long as your C compiler uses 32 bit integers.
+But you might want to think about whether using such a huge number of rules
+is the best way to solve your problem.
+
+
+
+
+
+How do I abandon a file in the middle of a scan and switch to a new file?
+
+
+
+Just all yyrestart(newfile). Be sure to reset the start state if you want a
+"fresh" start, since yyrestart does NOT reset the start state back to INITIAL.
+
+
+
+
+
+How do I execute code only during initialization (only before the first scan)?
+
+
+
+You can specify an initial action by defining the macro YY_USER_INIT (though
+note that yyout may not be available at the time this macro is executed). Or you
+can add to the beginning of your rules section:
+
+
+
+
+@verbatim
+%%
+ /* Must be indented! */
+ static int did_init = 0;
+
+ if ( ! did_init ){
+ do_my_init();
+ did_init = 1;
+ }
+
+Is there a way to increase the rules (NFA states to a bigger number?)
+
+
+
+With luck, you should be able to increase the definitions in flexdef.h for:
+
+
+
+
+@verbatim
+#define JAMSTATE -32766 /* marks a reference to the state that always jams */
+#define MAXIMUM_MNS 31999
+#define BAD_SUBSCRIPT -32767
+
+
+
+recompile everything, and it'll all work. Flex only has these 16-bit-like
+values built into it because a long time ago it was developed on a machine
+with 16-bit ints. I've given this advice to others in the past but haven't
+heard back from them whether it worked okay or not...
+
+
+
+
+
+One way to do it is to filter the first pass to a temporary file,
+then process the temporary file on the second pass. You will probably see a
+performance hit, do to all the disk I/O.
+
+
+
+When you need to look ahead far forward like this, it almost always means
+that the right solution is to build a parse tree of the entire input, then
+walk it after the parse in order to generate the output. In a sense, this
+is a two-pass approach, once through the text and once through the parse
+tree, but the performance hit for the latter is usually an order of magnitude
+smaller, since everything is already classified, in binary format, and
+residing in memory.
+
+
+
+
+
+How do I match any string not matched in the preceding rules?
+
+
+
+One way to assign precedence, is to place the more specific rules first. If
+two rules would match the same input (same sequence of characters) then the
+first rule listed in the flex input wins. e.g.,
+
+
+
+
+Note that the rule [a-zA-Z_]+ must come *after* the others. It will match the
+same amount of text as the more specific rules, and in that case the
+flex scanner will pick the first rule listed in your scanner as the
+one to match.
+
+
+
+
+
+I am trying to port code from AT&T lex that uses yysptr and yysbuf.
+
+
+
+Those are internal variables pointing into the AT&T scanner's input buffer. I
+imagine they're being manipulated in user versions of the input() and unput()
+functions. If so, what you need to do is analyze those functions to figure out
+what they're doing, and then replace input() with an appropriate definition of
+YY_INPUT (see the flex man page). You shouldn't need to (and must not) replace
+flex's unput() function.
+
+
+
+
+
+Why doesn't flex have non-greedy operators like perl does?
+
+
+
+A DFA can do a non-greedy match by stopping
+the first time it enters an accepting state, instead of consuming input until
+it determines that no further matching is possible (a "jam" state). This
+is actually easier to implement than longest leftmost match (which flex does).
+
+
+
+But it's also much less useful than longest leftmost match. In general,
+when you find yourself wishing for non-greedy matching, that's usually a
+sign that you're trying to make the scanner do some parsing. That's
+generally the wrong approach, since it lacks the power to do a decent job.
+Better is to either introduce a separate parser, or to split the scanner
+into multiple scanners using (exclusive) start conditions.
+
+
+
+You might have
+a separate start state once you've seen the BEGIN. In that state, you
+might then have a regex that will match END (to kick you out of the
+state), and perhaps (.|\n) to get a single character within the chunk ...
+
+
+
+This approach also has much better error-reporting properties.
+
+
+
+
+
+In this appendix, we provide tips for writing Makefiles to build your scanners.
+
+
+
+In a traditional build environment, we say that the `.c' files are the
+sources, and the `.o' files are the intermediate files. When using
+flex, however, the `.l' files are the sources, and the generated
+`.c' files (along with the `.o' files) are the intermediate files.
+This requires you to carefully plan your Makefile.
+
+
+
+Modern @command{make} programs understand that `foo.l' is intended to
+generate `lex.yy.c' or `foo.c', and will behave
+accordingly(2) and GNU @command{automake} are two such
+programs that provide implicit rules for flex-generated scanners.}. The
+following Makefile does not explicitly instruct @command{make} how to build
+`foo.c' from `foo.l'. Instead, it relies on the implicit rules of the
+@command{make} program to build the intermediate file, `scan.c':
+
+
+
+For simple cases, the above may be sufficient. For other cases,
+you may have to explicitly instruct @command{make} how to build your scanner.
+The following is an example of a Makefile containing explicit rules:
+
+
+
+Notice in the above example that `scan.c' is in the clean target.
+This is because we consider the file `scan.c' to be an intermediate file.
+
+
+
+Finally, we provide a realistic example of a flex scanner used with a
+bison parser(3).
+There is a tricky problem we have to deal with. Since a flex scanner
+will typically include a header file (e.g., `y.tab.h') generated by the
+parser, we need to be sure that the header file is generated BEFORE the scanner
+is compiled. We handle this case in the following example:
+
+
+
+
+, which lists the file `parse.c' (the generated parser) as a dependency of
+`scan.o'. We want to ensure that the parser is created before the scanner
+is compiled, and the above line seems to do the trick. Feel free to experiment
+with your specific implementation of @command{make}.
+
+
+
+For more details on writing Makefiles, see section `Top' in The GNU Make Manual.
+
+
+
+
+
+This is an index of functions and preprocessor macros that look like functions.
+For macros that expand to variables or constants, see section Index of Variables.
+
+
+
+This is an index of "hooks" that the user may define. These hooks typically correspond
+to specific locations in the generated scanner, and may be used to insert arbitrary code.
+
+
+
+Copyright (C) 1996-2000 Free Software Foundation, Inc.
+
+
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation;
+with the no Invariant Sections, with no Front-Cover Texts,
+and with no Back-Cover Texts. A copy of the license is included in
+the section entitled "GNU Free Documentation License".
+
+
+
+
+
+In the past, if a source code package developer wanted to take advantage
+of the power of shared libraries, he needed to write custom support code
+for each platform on which his package ran. He also had to design a
+configuration interface so that the package installer could choose what sort of
+libraries were built.
+
+
+
+GNU Libtool simplifies the developer's job by encapsulating both the
+platform-specific dependencies, and the user interface, in a single
+script. GNU Libtool is designed so that the complete functionality of
+each host type is available via a generic interface, but nasty quirks
+are hidden from the programmer.
+
+
+
+GNU Libtool's consistent interface is reassuring... users don't need
+to read obscure documentation in order to have their favorite source
+package build shared libraries. They just run your package
+configure script (or equivalent), and libtool does all the dirty
+work.
+
+
+
+There are several examples throughout this document. All assume the
+same environment: we want to build a library, `libhello', in a
+generic way.
+
+
+
+`libhello' could be a shared library, a static library, or
+both... whatever is available on the host system, as long as libtool
+has been ported to it.
+
+
+
+This chapter explains the original design philosophy of libtool. Feel
+free to skip to the next chapter, unless you are interested in history,
+or want to write code to extend libtool in a consistent way.
+
+
+
+
+
+
+
+Since early 1995, several different GNU developers have recognized the
+importance of having shared library support for their packages. The
+primary motivation for such a change is to encourage modularity and
+reuse of code (both conceptually and physically) in GNU programs.
+
+
+
+Such a demand means that the way libraries are built in GNU packages
+needs to be general, to allow for any library type the package installer
+might want. The problem is compounded by the absence of a standard
+procedure for creating shared libraries on different platforms.
+
+
+
+The following sections outline the major issues facing shared library
+support in GNU, and how shared library support could be standardized
+with libtool.
+
+
+
+
+
+The following specifications were used in developing and evaluating this
+system:
+
+
+
+
+
+
+The system must be as elegant as possible.
+
+
+
+The system must be fully integrated with the GNU Autoconf and Automake
+utilities, so that it will be easy for GNU maintainers to use. However,
+the system must not require these tools, so that it can be used by
+non-GNU packages.
+
+
+
+Portability to other (non-GNU) architectures and tools is desirable.
+
+
+
+The following issues need to be addressed in any reusable shared library
+system, specifically libtool:
+
+
+
+
+
+
+The package installer should be able to control what sort of libraries
+are built.
+
+
+
+It can be tricky to run dynamically linked programs whose libraries have
+not yet been installed. LD_LIBRARY_PATH must be set properly (if
+it is supported), or programs fail to run.
+
+
+
+The system must operate consistently even on hosts which don't support
+shared libraries.
+
+
+
+The commands required to build shared libraries may differ wildly from
+host to host. These need to be determined at configure time in
+a consistent way.
+
+
+
+It is not always obvious with which suffix a shared library should be
+installed. This makes it difficult for `Makefile' rules, since they
+generally assume that file names are the same from host to host.
+
+
+
+The system needs a simple library version number abstraction, so that
+shared libraries can be upgraded in place. The programmer should be
+informed how to design the interfaces to the library to maximize binary
+compatibility.
+
+
+
+The install `Makefile' target should warn the package installer to set
+the proper environment variables (LD_LIBRARY_PATH or equivalent),
+or run ldconfig.
+
+Even before libtool was developed, many free software packages built and
+installed their own shared libraries. At first, these packages were
+examined to avoid reinventing existing features.
+
+
+
+Now it is clear that none of these packages have documented the details
+of shared library systems that libtool requires. So, other packages
+have been more or less abandoned as influences.
+
+
+
+
+
+
+
+In all fairness, each of the implementations that were examined do the
+job that they were intended to do, for a number of different host
+systems. However, none of these solutions seem to function well as a
+generalized, reusable component.
+
+
+
+
+Most were too complex to use (much less modify) without understanding
+exactly what the implementation does, and they were generally not
+documented.
+
+
+
+The main difficulty is that different vendors have different views of
+what libraries are, and none of the packages which were examined seemed
+to be confident enough to settle on a single paradigm that just
+works.
+
+
+
+Ideally, libtool would be a standard that would be implemented as series
+of extensions and modifications to existing library systems to make them
+work consistently. However, it is not an easy task to convince
+operating system developers to mend their evil ways, and people want to
+build shared libraries right now, even on buggy, broken, confused
+operating systems.
+
+
+
+For this reason, libtool was designed as an independent shell script.
+It isolates the problems and inconsistencies in library building that
+plague `Makefile' writers by wrapping the compiler suite on
+different platforms with a consistent, powerful interface.
+
+
+
+With luck, libtool will be useful to and used by the GNU community, and
+that the lessons that were learned in writing it will be taken up by
+designers of future library systems.
+
+
+
+
+
+At first, libtool was designed to support an arbitrary number of library
+object types. After libtool was ported to more platforms, a new
+paradigm gradually developed for describing the relationship between
+libraries and programs.
+
+
+
+
+
+In summary, "libraries are programs with multiple entry points, and
+more formally defined interfaces."
+
+
+
+Version 0.7 of libtool was a complete redesign and rewrite of libtool to
+reflect this new paradigm. So far, it has proved to be successful:
+libtool is simpler and more useful than before.
+
+
+
+The best way to introduce the libtool paradigm is to contrast it with
+the paradigm of existing library systems, with examples from each. It
+is a new way of thinking, so it may take a little time to absorb, but
+when you understand it, the world becomes simpler.
+
+
+
+
+
+
+
+It makes little sense to talk about using libtool in your own packages
+until you have seen how it makes your life simpler. The examples in
+this chapter introduce the main features of libtool by comparing the
+standard library building procedure to libtool's operation on two
+different platforms:
+
+
+
+
+
`a23'
+
+An Ultrix 4.2 platform with only static libraries.
+
+
`burger'
+
+A NetBSD/i386 1.2 platform with shared libraries.
+
+
+
+You can follow these examples on your own platform, using the
+preconfigured libtool script that was installed with libtool
+(see section Configuring libtool).
+
+
+
+Source files for the following examples are taken from the `demo'
+subdirectory of the libtool distribution. Assume that we are building a
+library, `libhello', out of the files `foo.c' and
+`hello.c'.
+
+
+
+Note that the `foo.c' source file uses the cos math library
+function, which is usually found in the standalone math library, and not
+the C library (see section `Trigonometric Functions' in The GNU C Library Reference Manual). So, we need to add -lm to
+the end of the link line whenever we link `foo.o' or `foo.lo'
+into an executable or a library (see section Inter-library dependencies).
+
+
+
+The same rule applies whenever you use functions that don't appear in
+the standard C library... you need to add the appropriate
+-lname flag to the end of the link line when you link
+against those objects.
+
+
+
+After we have built that library, we want to create a program by linking
+`main.o' against `libhello'.
+
+
+
+
+
+
+
+To create an object file from a source file, the compiler is invoked
+with the `-c' flag (and any other desired flags):
+
+
+
+
+burger$ gcc -g -O -c main.c
+burger$
+
+
+
+The above compiler command produces an object file, `main.o', from
+the source file `main.c'.
+
+
+
+For most library systems, creating object files that become part of a
+static library is as simple as creating object files that are linked to
+form an executable:
+
+
+
+
+
+
+Shared libraries, however, may only be built from
+position-independent code (PIC). So, special flags must be passed
+to the compiler to tell it to generate PIC rather than the standard
+position-dependent code.
+
+
+
+
+
+
+Since this is a library implementation detail, libtool hides the
+complexity of PIC compiler flags by using separate library object files
+(which end in `.lo' instead of `.o'). On systems without shared
+libraries (or without special PIC compiler flags), these library object
+files are identical to "standard" object files.
+
+
+
+To create library object files for `foo.c' and `hello.c',
+simply invoke libtool with the standard compilation command as
+arguments (see section Compile mode):
+
+
+
+
+Note that libtool creates two files for each invocation. The `.lo'
+file is a library object, which may be built into a shared library, and
+the `.o' file is a standard object file. On `a23', the
+library objects are just timestamps, because only static libraries are
+supported.
+
+
+
+On shared library systems, libtool automatically inserts the PIC
+generation flags into the compilation command, so that the library
+object and the standard object differ:
+
+
+
+
+
+Without libtool, the programmer would invoke the ar command to
+create a static library:
+
+
+
+
+burger$ ar cru libhello.a hello.o foo.o
+burger$
+
+
+
+
+But of course, that would be too simple, so many systems require that
+you run the ranlib command on the resulting library (to give it
+better karma, or something):
+
+
+
+
+burger$ ranlib libhello.a
+burger$
+
+
+
+It seems more natural to use the C compiler for this task, given
+libtool's "libraries are programs" approach. So, on platforms without
+shared libraries, libtool simply acts as a wrapper for the system
+ar (and possibly ranlib) commands.
+
+
+
+
+
+Again, the libtool library name differs from the standard name (it has a
+`.la' suffix instead of a `.a' suffix). The arguments to libtool are
+the same ones you would use to produce an executable named
+`libhello.la' with your compiler (see section Link mode):
+
+
+
+
+Aha! Libtool caught a common error... trying to build a library
+from standard objects instead of library objects. This doesn't matter
+for static libraries, but on shared library systems, it is of great
+importance.
+
+
+
+So, let's try again, this time with the library object files. Remember
+also that we need to add -lm to the link command line because
+`foo.c' uses the cos math library function (see section Using libtool).
+
+
+
+Another complication in building shared libraries is that we need to
+specify the path to the directory in which they (eventually) will be
+installed (in this case, `/usr/local/lib')(1):
+
+
+
+
+Now that's significantly cooler... libtool just ran an obscure
+ld command to create a shared library, as well as the static
+library.
+
+
+
+
+Note how libtool creates extra files in the `.libs'
+subdirectory, rather than the current directory. This feature is to
+make it easier to clean up the build directory, and to help ensure that
+other programs fail horribly if you accidentally forget to use libtool
+when you should.
+
+
+
+
+
+
+If you choose at this point to install the library (put it in a
+permanent location) before linking executables against it, then you
+don't need to use libtool to do the linking. Simply use the appropriate
+`-L' and `-l' flags to specify the library's location.
+
+
+
+
+Some system linkers insist on encoding the full directory name of each
+shared library in the resulting executable. Libtool has to work around
+this misfeature by special magic to ensure that only permanent directory
+names are put into installed executables.
+
+
+
+
+
+The importance of this bug must not be overlooked: it won't cause
+programs to crash in obvious ways. It creates a security hole,
+and possibly even worse, if you are modifying the library source code
+after you have installed the package, you will change the behaviour of
+the installed programs!
+
+
+
+So, if you want to link programs against the library before you install
+it, you must use libtool to do the linking.
+
+
+
+
+Here's the old way of linking against an uninstalled library:
+
+
+
+
+That looks too simple to be true. All libtool did was transform
+`libhello.la' to `./.libs/libhello.a', but remember
+that `a23' has no shared libraries.
+
+
+
+Now assume `libhello.la' had already been installed, and you want
+to link a new program with it. You could figure out where it lives by
+yourself, then run:
+
+
+
+
+burger$ gcc -g -O -o test test.o -L/usr/local/lib -lhello
+
+
+
+However, unless `/usr/local/lib' is in the standard library search
+path, you won't be able to run test. However, if you use libtool
+to link the already-installed libtool library, it will do The Right
+Thing (TM) for you:
+
+
+
+
+Note that libtool added the necessary run-time path flag, as well as
+`-lm', the library libhello.la depended upon. Nice, huh?
+
+
+
+Since libtool created a wrapper script, you should use libtool to
+install it and debug it too. However, since the program does not depend
+on any uninstalled libtool library, it is probably usable even without
+the wrapper script. Libtool could probably be made smarter to avoid the
+creation of the wrapper script in this case, but this is left as an
+exercise for the reader.
+
+
+
+
+
+Notice that the executable, hell, was actually created in the
+`.libs' subdirectory. Then, a wrapper script was created
+in the current directory.
+
+
+
+On NetBSD 1.2, libtool encodes the installation directory of
+`libhello', by using the `-R/usr/local/lib' compiler flag.
+Then, the wrapper script guarantees that the executable finds the
+correct shared library (the one in `./.libs') until it is
+properly installed.
+
+
+
+Let's compare the two different programs:
+
+
+
+
+burger$ time ./hell.old
+Welcome to GNU Hell!
+** This is not GNU Hello. There is no built-in mail reader. **
+ 0.21 real 0.02 user 0.08 sys
+burger$ time ./hell
+Welcome to GNU Hell!
+** This is not GNU Hello. There is no built-in mail reader. **
+ 0.63 real 0.09 user 0.59 sys
+burger$
+
+
+
+The wrapper script takes significantly longer to execute, but at least
+the results are correct, even though the shared library hasn't been
+installed yet.
+
+
+
+So, what about all the space savings that shared libraries are supposed
+to yield?
+
+
+
+
+burger$ ls -l hell.old libhello.a
+-rwxr-xr-x 1 gord gord 15481 Nov 14 12:11 hell.old
+-rw-r--r-- 1 gord gord 4274 Nov 13 18:02 libhello.a
+burger$ ls -l .libs/hell .libs/libhello.*
+-rwxr-xr-x 1 gord gord 11647 Nov 14 12:10 .libs/hell
+-rw-r--r-- 1 gord gord 4274 Nov 13 18:44 .libs/libhello.a
+-rwxr-xr-x 1 gord gord 12205 Nov 13 18:44 .libs/libhello.so.0.0
+burger$
+
+
+
+Well, that sucks. Maybe I should just scrap this project and take up
+basket weaving.
+
+
+
+Actually, it just proves an important point: shared libraries incur
+overhead because of their (relative) complexity. In this situation, the
+price of being dynamic is eight kilobytes, and the payoff is about four
+kilobytes. So, having a shared `libhello' won't be an advantage
+until we link it against at least a few more programs.
+
+
+
+
+
+If `hell' was a complicated program, you would certainly want to
+test and debug it before installing it on your system. In the above
+section, you saw how the libtool wrapper script makes it possible to run
+the program directly, but unfortunately, this mechanism interferes with
+the debugger:
+
+
+
+
+burger$ gdb hell
+GDB is free software and you are welcome to distribute copies of it
+ under certain conditions; type "show copying" to see the conditions.
+There is no warranty for GDB; type "show warranty" for details.
+GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc.
+
+"hell": not in executable format: File format not recognized
+
+(gdb) quit
+burger$
+
+
+
+Sad. It doesn't work because GDB doesn't know where the executable
+lives. So, let's try again, by invoking GDB directly on the executable:
+
+
+
+
+burger$ gdb .libs/hell
+trick:/home/src/libtool/demo$ gdb .libs/hell
+GDB is free software and you are welcome to distribute copies of it
+ under certain conditions; type "show copying" to see the conditions.
+There is no warranty for GDB; type "show warranty" for details.
+GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc.
+(gdb) break main
+Breakpoint 1 at 0x8048547: file main.c, line 29.
+(gdb) run
+Starting program: /home/src/libtool/demo/.libs/hell
+/home/src/libtool/demo/.libs/hell: can't load library 'libhello.so.2'
+
+Program exited with code 020.
+(gdb) quit
+burger$
+
+
+
+Argh. Now GDB complains because it cannot find the shared library that
+`hell' is linked against. So, we must use libtool in order to
+properly set the library path and run the debugger. Fortunately, we can
+forget all about the `.libs' directory, and just run it on
+the executable wrapper (see section Execute mode):
+
+
+
+
+burger$ libtool gdb hell
+GDB is free software and you are welcome to distribute copies of it
+ under certain conditions; type "show copying" to see the conditions.
+There is no warranty for GDB; type "show warranty" for details.
+GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc.
+(gdb) break main
+Breakpoint 1 at 0x8048547: file main.c, line 29.
+(gdb) run
+Starting program: /home/src/libtool/demo/.libs/hell
+
+Breakpoint 1, main (argc=1, argv=0xbffffc40) at main.c:29
+29 printf ("Welcome to GNU Hell!\n");
+(gdb) quit
+The program is running. Quit anyway (and kill it)? (y or n) y
+burger$
+
+Note that the libtool library `libhello.la' is also installed, to
+help libtool with uninstallation (see section Uninstall mode) and linking
+(see section Linking executables) and to help programs with dlopening
+(see section Dlopened modules).
+
+
+
+
+
+It is safe to specify the `-s' (strip symbols) flag if you use a
+BSD-compatible install program when installing libraries.
+Libtool will either ignore the `-s' flag, or will run a program
+that will strip only debugging and compiler symbols from the library.
+
+
+
+Once the libraries have been put in place, there may be some additional
+configuration that you need to do before using them. First, you must
+make sure that where the library is installed actually agrees with the
+`-rpath' flag you used to build it.
+
+
+
+
+
+
+Then, running `libtool -n --finish libdir' can give you
+further hints on what to do (see section Finish mode):
+
+
+
+
+burger# libtool -n --finish /usr/local/lib
+PATH="$PATH:/sbin" ldconfig -m /usr/local/lib
+-----------------------------------------------------------------
+Libraries have been installed in:
+ /usr/local/lib
+
+To link against installed libraries in a given directory, LIBDIR,
+you must use the `-LLIBDIR' flag during linking.
+
+ You will also need to do one of the following:
+ - add LIBDIR to the `LD_LIBRARY_PATH' environment variable
+ during execution
+ - add LIBDIR to the `LD_RUN_PATH' environment variable
+ during linking
+ - use the `-RLIBDIR' linker flag
+
+See any operating system documentation about shared libraries for
+more information, such as the ld and ld.so manual pages.
+-----------------------------------------------------------------
+burger#
+
+
+
+After you have completed these steps, you can go on to begin using the
+installed libraries. You may also install any executables that depend
+on libraries you created.
+
+
+
+
+
+If you used libtool to link any executables against uninstalled libtool
+libraries (see section Linking executables), you need to use libtool to
+install the executables after the libraries have been installed
+(see section Installing libraries).
+
+
+
+So, for our Ultrix example, we would run:
+
+
+
+
+
+
+Why return to ar and ranlib silliness when you've had a
+taste of libtool? Well, sometimes it is desirable to create a static
+archive that can never be shared. The most frequent case is when you
+have a set of object files that you use to build several different
+programs. You can create a "convenience library" out of those
+objects, and link programs with the library, instead of listing all
+object files for every program. This technique is often used to
+overcome GNU automake's lack of support for linking object files built
+from sources in other directories, because it supports linking with
+libraries from other directories. This limitation applies to GNU
+automake up to release 1.4; newer releases should support sources in
+other directories.
+
+
+
+If you just want to link this convenience library into programs, then
+you could just ignore libtool entirely, and use the old ar and
+ranlib commands (or the corresponding GNU automake
+`_LIBRARIES' rules). You can even install a convenience library
+(but you probably don't want to) using libtool:
+
+
+
+
+Using libtool for static library installation protects your library from
+being accidentally stripped (if the installer used the `-s' flag),
+as well as automatically running the correct ranlib command.
+
+
+
+But libtool libraries are more than just collections of object files:
+they can also carry library dependency information, which old archives
+do not. If you want to create a libtool static convenience library, you
+can omit the `-rpath' flag and use `-static' to indicate that
+you're only interested in a static library. When you link a program
+with such a library, libtool will actually link all object files and
+dependency libraries into the program.
+
+
+
+If you omit both `-rpath' and `-static', libtool will create a
+convenience library that can be used to create other libtool
+libraries, even shared ones. Just like in the static case, the library
+behaves as an alias to a set of object files and dependency libraries,
+but in this case the object files are suitable for inclusion in shared
+libraries. But be careful not to link a single convenience library,
+directly or indirectly, into a single program or library, otherwise you
+may get errors about symbol redefinitions.
+
+
+
+When GNU automake is used, you should use noinst_LTLIBRARIES
+instead of lib_LTLIBRARIES for convenience libraries, so that
+the `-rpath' option is not passed when they are linked.
+
+
+
+As a rule of thumb, link a libtool convenience library into at most one
+libtool library, and never into a program, and link libtool static
+convenience libraries only into programs, and only if you need to carry
+library dependency information to the user of the static convenience
+library.
+
+
+
+
+Another common situation where static linking is desirable is in
+creating a standalone binary. Use libtool to do the linking and add the
+`-all-static' flag.
+
+
+
+
+
+The libtool program has the following synopsis:
+
+
+
+
+libtool [option]... [mode-arg]...
+
+
+
+and accepts the following options:
+
+
+
+
+
`--config'
+
+Display libtool configuration variables and exit.
+
+
`--debug'
+
+Dump a trace of shell script execution to standard output. This
+produces a lot of output, so you may wish to pipe it to less (or
+more) or redirect to a file.
+
+
`-n'
+
+
`--dry-run'
+
+Don't create, modify, or delete any files, just show what commands would
+be executed by libtool.
+
+
`--features'
+
+Display basic configuration options. This provides a way for packages
+to determine whether shared or static libraries will be built.
+
+
`--finish'
+
+Same as `--mode=finish'.
+
+
`--help'
+
+Display a help message and exit. If `--mode=mode' is
+specified, then detailed help for mode is
+displayed.
+
+
`--mode=mode'
+
+Use mode as the operation mode. By default, the operation mode is
+inferred from the mode-args.
+
+If mode is specified, it must be one of the following:
+
+
+
+
`compile'
+
+Compile a source file into a libtool object.
+
+
`execute'
+
+Automatically set the library path so that another program can use
+uninstalled libtool-generated programs or libraries.
+
+
`finish'
+
+Complete the installation of libtool libraries on the system.
+
+
`install'
+
+Install libraries or executables.
+
+
`link'
+
+Create a library or an executable.
+
+
`uninstall'
+
+Delete installed libraries or executables.
+
+
`clean'
+
+Delete uninstalled libraries or executables.
+
+
+
`--version'
+
+Print libtool version information and exit.
+
+
+
+The mode-args are a variable number of arguments, depending on the
+selected operation mode. In general, each mode-arg is interpreted
+by programs libtool invokes, rather than libtool itself.
+
+
+
+
+
+For compile mode, mode-args is a compiler command to be used
+in creating a `standard' object file. These arguments should begin with
+the name of the C compiler, and contain the `-c' compiler flag so
+that only an object file is created.
+
+
+
+Libtool determines the name of the output file by removing the directory
+component from the source file name, then substituting the source code
+suffix (e.g. `.c' for C source code) with the library object suffix,
+`.lo'.
+
+
+
+If shared libraries are being built, any necessary PIC generation flags
+are substituted into the compilation command.
+You can pass compiler and linker specific flags using `-Wc,flag'
+and `-Xcompiler flag' or `-Wl,flag' and
+`-Xlinker flag', respectively.
+
+
+
+If the `-static' option is given, then a `.o' file is built,
+even if libtool was configured with `--disable-static'.
+
+
+
+Note that the `-o' option is now fully supported. It is emulated
+on the platforms that don't support it (by locking and moving the
+objects), so it is really easy to use libtool, just with minor
+modifications to your Makefiles. Typing for example
+
+
+libtool gcc -c foo/x.c -o foo/x.lo
+
+
+
+will do what you expect.
+
+
+
+Note, however, that, if the compiler does not support `-c' and
+`-o', it is impossible to compile `foo/x.c' without
+overwriting an existing `./x.o'. Therefore, if you do have a
+source file `./x.c', make sure you introduce dependencies in your
+`Makefile' to make sure `./x.o' (or `./x.lo') is
+re-created after any sub-directory's `x.lo':
+
+
+x.o x.lo: foo/x.lo bar/x.lo
+
+
+
+This will also ensure that make won't try to use a temporarily corrupted
+`x.o' to create a program or library. It may cause needless
+recompilation on platforms that support `-c' and `-o'
+together, but it's the only way to make it safe for those that don't.
+
+
+
+
+
+Link mode links together object files (including library
+objects) to form another library or to create an executable program.
+
+
+
+mode-args consist of a command using the C compiler to create an
+output file (with the `-o' flag) from several object files.
+
+
+
+The following components of mode-args are treated specially:
+
+
+
+
+
`-all-static'
+
+
+
+
+If output-file is a program, then do not link it against any
+shared libraries at all. If output-file is a library, then only
+create a static library.
+
+
`-avoid-version'
+
+Tries to avoid versioning (see section Library interface versions) for libraries and modules,
+i.e. no version information is stored and no symbolic links are created.
+If the platform requires versioning, this option has no effect.
+
+
`-dlopen file'
+
+Same as `-dlpreopen file', if native dlopening is not
+supported on the host platform (see section Dlopened modules) or if
+the program is linked with `-static' or `-all-static'.
+Otherwise, no effect. If file is self libtool will make
+sure that the program can dlopen itself, either by enabling
+-export-dynamic or by falling back to `-dlpreopen self'.
+
+
`-dlpreopen file'
+
+Link file into the output program, and add its symbols to
+lt_preloaded_symbols (see section Dlpreopening). If file is
+self, the symbols of the program itself will be added to
+lt_preloaded_symbols.
+If file is force libtool will make sure that
+lt_preloaded_symbols is always defined, regardless of whether
+it's empty or not.
+
+
`-export-dynamic'
+
+Allow symbols from output-file to be resolved with dlsym
+(see section Dlopened modules).
+
+
`-export-symbols symfile'
+
+Tells the linker to export only the symbols listed in symfile.
+The symbol file should end in `.sym' and must contain the name of one
+symbol per line. This option has no effect on some platforms.
+By default all symbols are exported.
+
+
`-export-symbols-regex regex'
+
+Same as `-export-symbols', except that only symbols matching
+the regular expression regex are exported.
+By default all symbols are exported.
+
+
`-Llibdir'
+
+Search libdir for required libraries that have already been
+installed.
+
+
`-lname'
+
+output-file requires the installed library `libname'.
+This option is required even when output-file is not an
+executable.
+
+
`-module'
+
+Creates a library that can be dlopened (see section Dlopened modules).
+This option doesn't work for programs.
+Module names don't need to be prefixed with 'lib'.
+In order to prevent name clashes, however, 'libname' and 'name'
+must not be used at the same time in your package.
+
+
`-no-fast-install'
+
+Disable fast-install mode for the executable output-file. Useful
+if the program won't be necessarily installed.
+
+
`-no-install'
+
+Link an executable output-file that can't be installed and
+therefore doesn't need a wrapper script. Useful if the program is only
+used in the build tree, e.g., for testing or generating other files.
+
+
`-no-undefined'
+
+Declare that output-file does not depend on any other libraries.
+Some platforms cannot create shared libraries that depend on other
+libraries (see section Inter-library dependencies).
+
+
`-o output-file'
+
+Create output-file from the specified objects and libraries.
+
+
`-release release'
+
+Specify that the library was generated by release release of your
+package, so that users can easily tell which versions are newer than
+others. Be warned that no two releases of your package will be binary
+compatible if you use this flag. If you want binary compatibility, use
+the `-version-info' flag instead (see section Library interface versions).
+
+
`-rpath libdir'
+
+If output-file is a library, it will eventually be installed in
+libdir. If output-file is a program, add libdir to
+the run-time path of the program.
+
+
`-R libdir'
+
+If output-file is a program, add libdir to its run-time
+path. If output-file is a library, add -Rlibdir to its
+dependency_libs, so that, whenever the library is linked into a
+program, libdir will be added to its run-time path.
+
+
`-static'
+
+If output-file is a program, then do not link it against any
+uninstalled shared libtool libraries. If output-file is a
+library, then only create a static library.
+
+
`-version-info current[:revision[:age]]'
+
+If output-file is a libtool library, use interface version
+information current, revision, and age to build it
+(see section Library interface versions). Do not use this flag to specify package
+release information, rather see the `-release' flag.
+
+
`-Wl,flag'
+
+
`-Xlinker flag'
+
+Pass a linker specific flag directly to the linker.
+
+
+
+If the output-file ends in `.la', then a libtool library is
+created, which must be built only from library objects (`.lo' files).
+The `-rpath' option is required. In the current implementation,
+libtool libraries may not depend on other uninstalled libtool libraries
+(see section Inter-library dependencies).
+
+
+
+If the output-file ends in `.a', then a standard library is
+created using ar and possibly ranlib.
+
+
+
+
+
+If output-file ends in `.o' or `.lo', then a reloadable object
+file is created from the input files (generally using `ld -r').
+This method is often called partial linking.
+
+
+
+Otherwise, an executable program is created.
+
+
+
+
+
+For execute mode, the library path is automatically set, then a
+program is executed.
+
+
+
+The first of the mode-args is treated as a program name, with the
+rest as arguments to that program.
+
+
+
+The following components of mode-args are treated specially:
+
+
+
+
+
`-dlopen file'
+
+Add the directory containing file to the library path.
+
+
+
+This mode sets the library path environment variable according to any
+`-dlopen' flags.
+
+
+
+If any of the args are libtool executable wrappers, then they are
+translated into the name of their corresponding uninstalled binary, and
+any of their required library directories are added to the library path.
+
+
+
+
+
+Finish mode helps system administrators install libtool libraries
+so that they can be located and linked into user programs.
+
+
+
+Each mode-arg is interpreted as the name of a library directory.
+Running this command may require superuser privileges, so the
+`--dry-run' option may be useful.
+
+
+
+
+
+Libtool is fully integrated with Automake (see section `Introduction' in The Automake Manual), starting with Automake version 1.2.
+
+
+
+If you want to use libtool in a regular `Makefile' (or
+`Makefile.in'), you are on your own. If you're not using Automake
+1.2, and you don't know how to incorporate libtool into your package you
+need to do one of the following:
+
+
+
+
+
+
+Download Automake (version 1.2 or later) from your nearest GNU mirror,
+install it, and start using it.
+
+
+
+Learn how to write `Makefile' rules by hand. They're sometimes complex,
+but if you're clever enough to write rules for compiling your old
+libraries, then you should be able to figure out new rules for libtool
+libraries (hint: examine the `Makefile.in' in the `demo'
+subdirectory of the libtool distribution... note especially that it
+was automatically generated from the `Makefile.am' by Automake).
+
+
+Libtool library support is implemented under the `LTLIBRARIES'
+primary.
+
+
+
+Here are some samples from the Automake `Makefile.am' in the
+libtool distribution's `demo' subdirectory.
+
+
+
+First, to link a program against a libtool library, just use the
+`program_LDADD' variable:
+
+
+
+
+bin_PROGRAMS = hell hell.debug
+
+# Build hell from main.c and libhello.la
+hell_SOURCES = main.c
+hell_LDADD = libhello.la
+
+# Create an easier-to-debug version of hell.
+hell_debug_SOURCES = main.c
+hell_debug_LDADD = libhello.la
+hell_debug_LDFLAGS = -static
+
+
+
+The flags `-dlopen' or `-dlpreopen' (see section Link mode) would
+fit better in the program_LDADD variable. Unfortunately, GNU
+automake, up to release 1.4, doesn't accept these flags in a
+program_LDADD variable, so you have the following alternatives:
+
+
+
+
+
+
+add them to program_LDFLAGS, and list the libraries in
+program_DEPENDENCIES, then wait for a release of GNU automake that
+accepts these flags where they belong;
+
+
+
+surround the flags between quotes, but then you must set
+program_DEPENDENCIES too:
+
+
+
+
+set and `AC_SUBST' variables DLOPEN and DLPREOPEN in
+`configure.in' and use `@DLOPEN@' and `@DLPREOPEN@'
+as replacements for the explicit flags `-dlopen' and
+`-dlpreopen' in `program_LDADD'. Automake will discard
+`AC_SUBST'ed variables from dependencies, so it will behave exactly
+as we expect it to behave when it accepts these flags in
+`program_LDADD'. But hey!, this is ugly!
+
+
+
+You may use the `program_LDFLAGS' variable to stuff in any flags
+you want to pass to libtool while linking `program' (such as
+`-static' to avoid linking uninstalled shared libtool libraries).
+
+
+
+Building a libtool library is almost as trivial... note the use of
+`libhello_la_LDFLAGS' to pass the `-version-info'
+(see section Library interface versions) option to libtool:
+
+
+
+
+# Build a libtool library, libhello.la for installation in libdir.
+lib_LTLIBRARIES = libhello.la
+libhello_la_SOURCES = hello.c foo.c
+libhello_la_LDFLAGS = -version-info 3:12:1
+
+
+
+The `-rpath' option is passed automatically by Automake (except for
+libraries listed as noinst_LTLIBRARIES), so you
+should not specify it.
+
+
+
+See section `The Automake Manual' in The Automake Manual, for more information.
+
+
+
+
+
+Libtool requires intimate knowledge of your compiler suite and operating
+system in order to be able to create shared libraries and link against
+them properly. When you install the libtool distribution, a
+system-specific libtool script is installed into your binary directory.
+
+
+
+However, when you distribute libtool with your own packages
+(see section Including libtool in your package), you do not always know which compiler suite and
+operating system are used to compile your package.
+
+
+
+For this reason, libtool must be configured before it can be
+used. This idea should be familiar to anybody who has used a GNU
+configure script. configure runs a number of tests for
+system features, then generates the `Makefiles' (and possibly a
+`config.h' header file), after which you can run make and
+build the package.
+
+
+
+Libtool adds its own tests to your configure script in order to
+generate a libtool script for the installer's host machine.
+
+
+
+
+
+If you are using GNU Autoconf (or Automake), you should add a call to
+AC_PROG_LIBTOOL to your `configure.in' file. This macro
+adds many new tests to the configure script so that the generated
+libtool script will understand the characteristics of the host:
+
+
+
+
+
Macro:AC_PROG_LIBTOOL
+
+
Macro:AM_PROG_LIBTOOL
+
+Add support for the `--enable-shared' and `--disable-shared'
+configure flags.(4)AM_PROG_LIBTOOL was the
+old name for this macro, and although supported at the moment is
+deprecated.
+
+
+
+By default, this macro turns on shared libraries if they are available,
+and also enables static libraries if they don't conflict with the shared
+libraries. You can modify these defaults by calling either the
+AC_DISABLE_SHARED or AC_DISABLE_STATIC macros:
+
+
+
+
+# Turn off shared libraries during beta-testing, since they
+# make the build process take too long.
+AC_DISABLE_SHARED
+AC_PROG_LIBTOOL
+
+
+
+The user may specify modified forms of the configure flags
+`--enable-shared' and `--enable-static' to choose whether
+shared or static libraries are built based on the name of the package.
+For example, to have shared `bfd' and `gdb' libraries built,
+but not shared `libg++', you can run all three configure
+scripts as follows:
+
+
+
+
+trick$ ./configure --enable-shared=bfd,gdb
+
+
+
+In general, specifying `--enable-shared=pkgs' is the same as
+configuring with `--enable-shared' every package named in the
+comma-separated pkgs list, and every other package with
+`--disable-shared'. The `--enable-static=pkgs' flag
+behaves similarly, but it uses `--enable-static' and
+`--disable-static'. The same applies to the
+`--enable-fast-install=pkgs' flag, which uses
+`--enable-fast-install' and `--disable-fast-install'.
+
+
+
+The package name `default' matches any packages which have not set
+their name in the PACKAGE environment variable.
+
+
+
+This macro also sets the shell variable LIBTOOL_DEPS, that you can
+use to automatically update the libtool script if it becomes
+out-of-date. In order to do that, add to your `configure.in':
+
+
+
+
+If you are using GNU automake, you can omit the assignment, as automake
+will take care of it. You'll obviously have to create some dependency
+on `libtool'.
+
+
+
+
+
+
+
Macro:AC_LIBTOOL_DLOPEN
+
+Enable checking for dlopen support. This macro should be used if
+the package makes use of the `-dlopen' and `-dlpreopen' flags,
+otherwise libtool will assume that the system does not support dlopening.
+The macro must be called beforeAC_PROG_LIBTOOL.
+
+
+
+
+
+
Macro:AC_LIBTOOL_WIN32_DLL
+
+This macro should be used if the package has been ported to build clean
+dlls on win32 platforms. Usually this means that any library data items
+are exported with __declspec(dllexport) and imported with
+__declspec(dllimport). If this macro is not used, libtool will
+assume that the package libraries are not dll clean and will build only
+static libraries on win32 hosts.
+
+
+
+This macro must be called beforeAC_PROG_LIBTOOL, and
+provision must be made to pass `-no-undefined' to libtool
+in link mode from the package Makefile. Naturally, if you pass
+`-no-undefined', you must ensure that all the library symbols
+really are defined at link time!
+
+
+
+
+
+
Macro:AC_DISABLE_FAST_INSTALL
+
+Change the default behaviour for AC_PROG_LIBTOOL to disable
+optimization for fast installation. The user may still override this
+default, depending on platform support, by specifying
+`--enable-fast-install'.
+
+
+
+
+
+
Macro:AC_DISABLE_SHARED
+
+
Macro:AM_DISABLE_SHARED
+
+Change the default behaviour for AC_PROG_LIBTOOL to disable
+shared libraries. The user may still override this default by
+specifying `--enable-shared'.
+
+
+
+
+
+
Macro:AC_DISABLE_STATIC
+
+
Macro:AM_DISABLE_STATIC
+
+Change the default behaviour for AC_PROG_LIBTOOL to disable
+static libraries. The user may still override this default by
+specifying `--enable-static'.
+
+
+
+
+The tests in AC_PROG_LIBTOOL also recognize the following
+environment variables:
+
+
+
+
+
Variable:CC
+
+The C compiler that will be used by the generated libtool. If
+this is not set, AC_PROG_LIBTOOL will look for gcc or
+cc.
+
+
+
+
+
+
Variable:CFLAGS
+
+Compiler flags used to generate standard object files. If this is not
+set, AC_PROG_LIBTOOL will not use any such flags. It affects
+only the way AC_PROG_LIBTOOL runs tests, not the produced
+libtool.
+
+
+
+
+
+
Variable:CPPFLAGS
+
+C preprocessor flags. If this is not set, AC_PROG_LIBTOOL will
+not use any such flags. It affects only the way AC_PROG_LIBTOOL
+runs tests, not the produced libtool.
+
+
+
+
+
+
Variable:LD
+
+The system linker to use (if the generated libtool requires one).
+If this is not set, AC_PROG_LIBTOOL will try to find out what is
+the linker used by CC.
+
+
+
+
+
+
Variable:LDFLAGS
+
+The flags to be used by libtool when it links a program. If
+this is not set, AC_PROG_LIBTOOL will not use any such flags. It
+affects only the way AC_PROG_LIBTOOL runs tests, not the produced
+libtool.
+
+
+
+
+
+
Variable:LIBS
+
+The libraries to be used by AC_PROG_LIBTOOL when it links a
+program. If this is not set, AC_PROG_LIBTOOL will not use any
+such flags. It affects only the way AC_PROG_LIBTOOL runs tests,
+not the produced libtool.
+
+
+
+
+
+
Variable:NM
+
+Program to use rather than checking for nm.
+
+
+
+
+
+
Variable:RANLIB
+
+Program to use rather than checking for ranlib.
+
+
+
+
+
+
Variable:LN_S
+
+A command that creates a link of a program, a soft-link if possible, a
+hard-link otherwise. AC_PROG_LIBTOOL will check for a suitable
+program if this variable is not set.
+
+
+
+
+
+
Variable:DLLTOOL
+
+Program to use rather than checking for dlltool. Only meaningful
+for Cygwin/MS-Windows.
+
+
+
+
+
+
Variable:OBJDUMP
+
+Program to use rather than checking for objdump. Only meaningful
+for Cygwin/MS-Windows.
+
+
+
+
+
+
Variable:AS
+
+Program to use rather than checking for as. Only used on
+Cygwin/MS-Windows at the moment.
+
+
+
+
+
+When you invoke the libtoolize program (see section Invoking libtoolize), it will tell you where to find a definition of
+AC_PROG_LIBTOOL. If you use Automake, the aclocal program
+will automatically add AC_PROG_LIBTOOL support to your
+configure script.
+
+
+
+Nevertheless, it is advisable to include a copy of `libtool.m4' in
+`acinclude.m4', so that, even if `aclocal.m4' and
+`configure' are rebuilt for any reason, the appropriate libtool
+macros will be used. The alternative is to hope the user will have a
+compatible version of `libtool.m4' installed and accessible for
+aclocal. This may lead to weird errors when versions don't
+match.
+
+
+
+
+
+The libtoolize program provides a standard way to add libtool
+support to your package. In the future, it may implement better usage
+checking, or other features to make libtool even easier to use.
+
+
+
+The libtoolize program has the following synopsis:
+
+
+
+
+libtoolize [option]...
+
+
+
+and accepts the following options:
+
+
+
+
+
`--automake'
+
+Work silently, and assume that Automake libtool support is used.
+
+`libtoolize --automake' is used by Automake to add libtool files to
+your package, when AC_PROG_LIBTOOL appears in your
+`configure.in'.
+
+
`--copy'
+
+
`-c'
+
+Copy files from the libtool data directory rather than creating
+symlinks.
+
+
`--debug'
+
+Dump a trace of shell script execution to standard output. This
+produces a lot of output, so you may wish to pipe it to less (or
+more) or redirect to a file.
+
+
`--dry-run'
+
+
`-n'
+
+Don't run any commands that modify the file system, just print them
+out.
+
+
+Install libltdl in a subdirectory of your package.
+
+
`--ltdl-tar'
+
+Add the file libltdl.tar.gz to your package.
+
+
`--version'
+
+Print libtoolize version information and exit.
+
+
+
+
+If libtoolize detects an explicit call to
+AC_CONFIG_AUX_DIR (see section `The Autoconf Manual' in The Autoconf Manual) in your `configure.in', it
+will put the files in the specified directory.
+
+
+
+libtoolize displays hints for adding libtool support to your
+package, as well.
+
+
+
+
+
+The Autoconf package comes with a few macros that run tests, then set a
+variable corresponding to the name of an object file. Sometimes it is
+necessary to use corresponding names for libtool objects.
+
+
+
+Here are the names of variables that list libtool objects:
+
+
+
+
+
Variable:LTALLOCA
+
+
+Substituted by AC_FUNC_ALLOCA (see section `The Autoconf Manual' in The Autoconf Manual). Is either empty, or contains `alloca.lo'.
+
+
+
+
+
+
Variable:LTLIBOBJS
+
+
+Substituted by AC_REPLACE_FUNCS (see section `The Autoconf Manual' in The Autoconf Manual), and a few other functions.
+
+
+
+
+Unfortunately, the stable release of Autoconf (2.13, at the time of
+this writing) does not have any way for libtool to provide support for
+these variables. So, if you depend on them, use the following code
+immediately before the call to AC_OUTPUT in your
+`configure.in':
+
+
+
+
+LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.[^.]* /.lo /g;s/\.[^.]*$/.lo/'`
+AC_SUBST(LTLIBOBJS)
+LTALLOCA=`echo "$ALLOCA" | sed 's/\.[^.]* /.lo /g;s/\.[^.]*$/.lo/'`
+AC_SUBST(LTALLOCA)
+AC_OUTPUT(...)
+
+When you are developing a package, it is often worthwhile to configure
+your package with the `--disable-shared' flag, or to override the
+defaults for AC_PROG_LIBTOOL by using the
+AC_DISABLE_SHARED Autoconf macro (see section The AC_PROG_LIBTOOL macro). This prevents libtool from building
+shared libraries, which has several advantages:
+
+
+
+
+
+
+compilation is twice as fast, which can speed up your development cycle,
+
+
+
+debugging is easier because you don't need to deal with any complexities
+added by shared libraries, and
+
+
+
+you can see how libtool behaves on static-only platforms.
+
+
+
+You may want to put a small note in your package `README' to let
+other developers know that `--disable-shared' can save them time.
+The following example note is taken from the GIMP(5) distribution `README':
+
+
+
+
+The GIMP uses GNU Libtool in order to build shared libraries on a
+variety of systems. While this is very nice for making usable
+binaries, it can be a pain when trying to debug a program. For that
+reason, compilation of shared libraries can be turned off by
+specifying the `--disable-shared' option to `configure'.
+
+The most difficult issue introduced by shared libraries is that of
+creating and resolving runtime dependencies. Dependencies on programs
+and libraries are often described in terms of a single name, such as
+sed. So, one may say "libtool depends on sed," and that is
+good enough for most purposes.
+
+
+
+However, when an interface changes regularly, we need to be more
+specific: "Gnus 5.1 requires Emacs 19.28 or above." Here, the
+description of an interface consists of a name, and a "version
+number."
+
+
+
+Even that sort of description is not accurate enough for some purposes.
+What if Emacs 20 changes enough to break Gnus 5.1?
+
+
+
+The same problem exists in shared libraries: we require a formal version
+system to describe the sorts of dependencies that programs have on
+shared libraries, so that the dynamic linker can guarantee that programs
+are linked only against libraries that provide the interface they
+require.
+
+
+
+
+
+Libtool has its own formal versioning system. It is not as flexible as
+some, but it is definitely the simplest of the more powerful versioning
+systems.
+
+
+
+Think of a library as exporting several sets of interfaces, arbitrarily
+represented by integers. When a program is linked against a library, it
+may use any subset of those interfaces.
+
+
+
+Libtool's description of the interfaces that a program uses is simple:
+it encodes the least and the greatest interface numbers in the resulting
+binary (first-interface, last-interface).
+
+
+
+The dynamic linker is guaranteed that if a library supports every
+interface number between first-interface and last-interface,
+then the program can be relinked against that library.
+
+
+
+Note that this can cause problems because libtool's compatibility
+requirements are actually stricter than is necessary.
+
+
+
+Say `libhello' supports interfaces 5, 16, 17, 18, and 19, and that
+libtool is used to link `test' against `libhello'.
+
+
+
+Libtool encodes the numbers 5 and 19 in `test', and the dynamic
+linker will only link `test' against libraries that support
+every interface between 5 and 19. So, the dynamic linker refuses
+to link `test' against `libhello'!
+
+
+
+In order to eliminate this problem, libtool only allows libraries to
+declare consecutive interface numbers. So, `libhello' can declare at
+most that it supports interfaces 16 through 19. Then, the dynamic
+linker will link `test' against `libhello'.
+
+
+
+So, libtool library versions are described by three integers:
+
+
+
+
+
current
+
+The most recent interface number that this library implements.
+
+
revision
+
+The implementation number of the current interface.
+
+
age
+
+The difference between the newest and oldest interfaces that this
+library implements. In other words, the library implements all the
+interface numbers in the range from number current -
+age to current.
+
+
+
+If two libraries have identical current and age numbers,
+then the dynamic linker chooses the library with the greater
+revision number.
+
+
+
+
+
+If you want to use libtool's versioning system, then you must specify
+the version information to libtool using the `-version-info' flag
+during link mode (see section Link mode).
+
+
+
+This flag accepts an argument of the form
+`current[:revision[:age]]'. So, passing
+`-version-info 3:12:1' sets current to 3, revision to
+12, and age to 1.
+
+
+
+If either revision or age are omitted, they default to 0.
+Also note that age must be less than or equal to the current
+interface number.
+
+
+
+Here are a set of rules to help you update your library version
+information:
+
+
+
+
+
+
+Start with version information of `0:0:0' for each libtool library.
+
+
+
+Update the version information only immediately before a public release
+of your software. More frequent updates are unnecessary, and only
+guarantee that the current interface number gets larger faster.
+
+
+
+If the library source code has changed at all since the last update,
+then increment revision (`c:r:a' becomes
+`c:r+1:a').
+
+
+
+If any interfaces have been added, removed, or changed since the last
+update, increment current, and set revision to 0.
+
+
+
+If any interfaces have been added since the last public release, then
+increment age.
+
+
+
+If any interfaces have been removed since the last public release, then
+set age to 0.
+
+
+
+Never try to set the interface numbers so that they
+correspond to the release number of your package. This is an abuse that
+only fosters misunderstanding of the purpose of library versions.
+Instead, use the `-release' flag (see section Managing release information), but be
+warned that every release of your package will not be binary compatible
+with any other release.
+
+
+
+
+
+Often, people want to encode the name of the package release into the
+shared library so that it is obvious to the user which package their
+programs are linked against. This convention is used especially on
+GNU/Linux:
+
+
+
+
+trick$ ls /usr/lib/libbfd*
+/usr/lib/libbfd.a /usr/lib/libbfd.so.2.7.0.2
+/usr/lib/libbfd.so
+trick$
+
+
+
+On `trick', `/usr/lib/libbfd.so' is a symbolic link to
+`libbfd.so.2.7.0.2', which was distributed as a part of
+`binutils-2.7.0.2'.
+
+
+
+Unfortunately, this convention conflicts directly with libtool's idea of
+library interface versions, because the library interface rarely changes
+at the same time that the release number does, and the library suffix is
+never the same across all platforms.
+
+
+
+So, in order to accommodate both views, you can use the `-release'
+flag in order to set release information for libraries which you do not
+want to use `-version-info'. For the `libbfd' example, the
+next release which uses libtool should be built with `-release
+2.9.0', which will produce the following files on GNU/Linux:
+
+
+
+
+trick$ ls /usr/lib/libbfd*
+/usr/lib/libbfd-2.9.0.so /usr/lib/libbfd.a
+/usr/lib/libbfd.so
+trick$
+
+
+
+In this case, `/usr/lib/libbfd.so' is a symbolic link to
+`libbfd-2.9.0.so'. This makes it obvious that the user is dealing
+with `binutils-2.9.0', without compromising libtool's idea of
+interface versions.
+
+
+
+Note that this option causes a modification of the library name, so do
+not use it unless you want to break binary compatibility with any past
+library releases. In general, you should only use `-release' for
+package-internal libraries or for ones whose interfaces change very
+frequently.
+
+
+
+
+
+Writing a good library interface takes a lot of practice and thorough
+understanding of the problem that the library is intended to solve.
+
+
+
+If you design a good interface, it won't have to change often, you won't
+have to keep updating documentation, and users won't have to keep
+relearning how to use the library.
+
+
+
+Here is a brief list of tips for library interface design, which may
+help you in your exploits:
+
+
+
+
+
Plan ahead
+
+Try to make every interface truly minimal, so that you won't need to
+delete entry points very often.
+
+
Avoid interface changes
+
+
+Some people love redesigning and changing entry points just for the heck
+of it (note: renaming a function is considered changing an entry
+point). Don't be one of those people. If you must redesign an
+interface, then try to leave compatibility functions behind so that
+users don't need to rewrite their existing code.
+
+
Use opaque data types
+
+
+The fewer data type definitions a library user has access to, the
+better. If possible, design your functions to accept a generic pointer
+(which you can cast to an internal data type), and provide access
+functions rather than allowing the library user to directly manipulate
+the data.
+That way, you have the freedom to change the data structures without
+changing the interface.
+
+This is essentially the same thing as using abstract data types and
+inheritance in an object-oriented system.
+
+
Use header files
+
+
+If you are careful to document each of your library's global functions
+and variables in header files, and include them in your library source
+files, then the compiler will let you know if you make any interface
+changes by accident (see section Writing C header files).
+
+
Use the static keyword (or equivalent) whenever possible
+
+
+The fewer global functions your library has, the more flexibility you'll
+have in changing them. Static functions and variables may change forms
+as often as you like... your users cannot access them, so they
+aren't interface changes.
+
+Writing portable C header files can be difficult, since they may be read
+by different types of compilers:
+
+
+
+
+
C++ compilers
+
+C++ compilers require that functions be declared with full prototypes,
+since C++ is more strongly typed than C. C functions and variables also
+need to be declared with the extern "C" directive, so that the
+names aren't mangled. See section Writing libraries for C++, for other issues relevant
+to using C++ with libtool.
+
+
ANSI C compilers
+
+ANSI C compilers are not as strict as C++ compilers, but functions
+should be prototyped to avoid unnecessary warnings when the header file
+is #included.
+
+
non-ANSI C compilers
+
+Non-ANSI compilers will report errors if functions are prototyped.
+
+
+
+These complications mean that your library interface headers must use
+some C preprocessor magic in order to be usable by each of the above
+compilers.
+
+
+
+`foo.h' in the `demo' subdirectory of the libtool distribution
+serves as an example for how to write a header file that can be
+safely installed in a system directory.
+
+
+
+Here are the relevant portions of that file:
+
+
+
+
+/* BEGIN_C_DECLS should be used at the beginning of your declarations,
+ so that C++ compilers don't mangle their names. Use END_C_DECLS at
+ the end of C declarations. */
+#undef BEGIN_C_DECLS
+#undef END_C_DECLS
+#ifdef __cplusplus
+# define BEGIN_C_DECLS extern "C" {
+# define END_C_DECLS }
+#else
+# define BEGIN_C_DECLS /* empty */
+# define END_C_DECLS /* empty */
+#endif
+
+/* PARAMS is a macro used to wrap function prototypes, so that
+ compilers that don't understand ANSI C prototypes still work,
+ and ANSI C compilers can issue warnings about type mismatches. */
+#undef PARAMS
+#if defined (__STDC__) || defined (_AIX) \
+ || (defined (__mips) && defined (_SYSTYPE_SVR4)) \
+ || defined(WIN32) || defined(__cplusplus)
+# define PARAMS(protos) protos
+#else
+# define PARAMS(protos) ()
+#endif
+
+
+
+These macros are used in `foo.h' as follows:
+
+
+
+
+Note that the `#ifndef FOO_H' prevents the body of `foo.h'
+from being read more than once in a given compilation.
+
+
+
+Also the only thing that must go outside the
+BEGIN_C_DECLS/END_C_DECLS pair are #include lines.
+Strictly speaking it is only C symbol names that need to be protected,
+but your header files will be more maintainable if you have a single
+pair of of these macros around the majority of the header contents.
+
+
+
+You should use these definitions of PARAMS, BEGIN_C_DECLS,
+and END_C_DECLS into your own headers. Then, you may use them to
+create header files that are valid for C++, ANSI, and non-ANSI
+compilers(6).
+
+
+
+Do not be naive about writing portable code. Following the tips given
+above will help you miss the most obvious problems, but there are
+definitely other subtle portability issues. You may need to cope with
+some of the following issues:
+
+
+
+
+
+
+Pre-ANSI compilers do not always support the void * generic
+pointer type, and so need to use char * in its place.
+
+
+
+The const, inline and signed keywords are not
+supported by some compilers, especially pre-ANSI compilers.
+
+
+
+The long double type is not supported by many compilers.
+
+By definition, every shared library system provides a way for
+executables to depend on libraries, so that symbol resolution is
+deferred until runtime.
+
+
+
+An inter-library dependency is one in which a library depends on
+other libraries. For example, if the libtool library `libhello'
+uses the cos function, then it has an inter-library dependency
+on `libm', the math library that implements cos.
+
+
+
+Some shared library systems provide this feature in an
+internally-consistent way: these systems allow chains of dependencies of
+potentially infinite length.
+
+
+
+However, most shared library systems are restricted in that they only
+allow a single level of dependencies. In these systems, programs may
+depend on shared libraries, but shared libraries may not depend on other
+shared libraries.
+
+
+
+In any event, libtool provides a simple mechanism for you to declare
+inter-library dependencies: for every library `libname' that
+your own library depends on, simply add a corresponding
+-lname option to the link line when you create your
+library. To make an example of our
+`libhello' that depends on `libm':
+
+
+
+
+When you link a program against `libhello', you don't need to
+specify the same `-l' options again: libtool will do that for you,
+in order to guarantee that all the required libraries are found. This
+restriction is only necessary to preserve compatibility with static
+library systems and simple dynamic library systems.
+
+
+
+Some platforms, such as AIX, do not even allow you this
+flexibility. In order to build a shared library, it must be entirely
+self-contained (that is, have references only to symbols that are found
+in the `.lo' files or the specified `-l' libraries), and you
+need to specify the -no-undefined flag. By default, libtool
+builds only static libraries on these kinds of platforms.
+
+
+
+The simple-minded inter-library dependency tracking code of libtool
+releases prior to 1.2 was disabled because it was not clear when it was
+possible to link one library with another, and complex failures would
+occur. A more complex implementation of this concept was re-introduced
+before release 1.3, but it has not been ported to all platforms that
+libtool supports. The default, conservative behavior is to avoid
+linking one library with another, introducing their inter-dependencies
+only when a program is linked with them.
+
+
+
+
+
+It can sometimes be confusing to discuss dynamic linking, because
+the term is used to refer to two different concepts:
+
+
+
+
+
+
+Compiling and linking a program against a shared library, which is
+resolved automatically at run time by the dynamic linker. In this
+process, dynamic linking is transparent to the application.
+
+
+
+The application calling functions such as dlopen,(7) which load
+arbitrary, user-specified modules at runtime. This type of dynamic
+linking is explicitly controlled by the application.
+
+
+
+To mitigate confusion, this manual refers to the second type of dynamic
+linking as dlopening a module.
+
+
+
+The main benefit to dlopening object modules is the ability to access
+compiled object code to extend your program, rather than using an
+interpreted language. In fact, dlopen calls are frequently used in
+language interpreters to provide an efficient way to extend the
+language.
+
+
+
+As of version 1.4.2, libtool provides support for dlopened
+modules. However, you should indicate that your package is willing to
+use such support, by using the macro `AC_LIBTOOL_DLOPEN' in
+`configure.in'. If this macro is not used (or it is used
+after`AC_PROG_LIBTOOL'), libtool will assume no dlopening
+mechanism is available, and will try to simulate it.
+
+
+
+This chapter discusses how you as a dlopen application developer might
+use libtool to generate dlopen-accessible modules.
+
+
+
+
+
+On some operating systems, a program symbol must be specially declared
+in order to be dynamically resolved with the dlsym (or
+equivalent) function.
+
+
+
+Libtool provides the `-export-dynamic' and `-module'
+link flags (see section Link mode), which do this declaration.
+You need to use these flags if you are linking an application program that
+dlopens other modules or a libtool library that will also be dlopened.
+
+
+
+For example, if we wanted to build a shared library, `libhello',
+that would later be dlopened by an application, we would add
+`-module' to the other link flags:
+
+
+
+
+If symbols from your executable are needed to satisfy unresolved
+references in a library you want to dlopen you will have to use the flag
+`-export-dynamic'.
+You should use `-export-dynamic' while linking the executable that calls
+dlopen:
+
+
+
+
+Libtool provides special support for dlopening libtool object and
+libtool library files, so that their symbols can be resolved even
+on platforms without any dlopen and dlsym
+functions.
+
+
+
+Consider the following alternative ways of loading code into your
+program, in order of increasing "laziness":
+
+
+
+
+
+
+Linking against object files that become part of the program executable,
+whether or not they are referenced. If an object file cannot be found,
+then the linker refuses to create the executable.
+
+
+
+Declaring a static library to the linker, so that it is searched at link
+time in order to satisfy any undefined references in the above object
+files. If the static library cannot be found, then the linker refuses
+to link the executable.
+
+
+
+Declaring a shared library to the runtime linker, so that it is searched
+at runtime in order to satisfy any undefined references in the above
+files. If the shared library cannot be found, then the dynamic linker
+aborts the program before it runs.
+
+
+
+Dlopening a module, so that the application can resolve its own,
+dynamically-computed references. If there is an error opening the
+module, or the module is not found, then the application can recover
+without crashing.
+
+
+
+Libtool emulates `-dlopen' on static platforms by linking objects
+into the program at compile time, and creating data structures that
+represent the program's symbol table.
+
+
+
+In order to use this feature, you must declare the objects you want your
+application to dlopen by using the `-dlopen' or `-dlpreopen'
+flags when you link your program (see section Link mode).
+
+
+
+The name attribute is a null-terminated character string of the
+symbol name, such as "fprintf". The address attribute is a
+generic pointer to the appropriate object, such as &fprintf.
+
+An array of lt_symbol structures, representing all the preloaded
+symbols linked into the program. For each `-dlpreloaded' file
+there is an element with the name of the file and a address
+of 0, followed by all symbols exported from this file.
+For the executable itself the special name @PROGRAM@ is used.
+The last element has a name and address of 0.
+
+
+
+
+Some compilers may allow identifiers which are not valid in ANSI C, such
+as dollar signs. Libtool only recognizes valid ANSI C symbols (an
+initial ASCII letter or underscore, followed by zero or more ASCII
+letters, digits, and underscores), so non-ANSI symbols will not appear
+in lt_preloaded_symbols.
+
+
+
+
+
+After a library has been linked with `-module', it can be dlopened.
+Unfortunately, because of the variation in library names,
+your package needs to determine the correct file to dlopen.
+
+
+
+The most straightforward and flexible implementation is to determine the
+name at runtime, by finding the installed `.la' file, and searching
+it for the following lines:
+
+
+
+
+# The name that we can dlopen.
+dlname='dlname'
+
+
+
+If dlname is empty, then the library cannot be dlopened.
+Otherwise, it gives the dlname of the library. So, if the library was
+installed as `/usr/local/lib/libhello.la', and the dlname was
+`libhello.so.3', then `/usr/local/lib/libhello.so.3' should be
+dlopened.
+
+
+
+If your program uses this approach, then it should search the
+directories listed in the LD_LIBRARY_PATH(8) environment variable, as well as
+the directory where libraries will eventually be installed. Searching
+this variable (or equivalent) will guarantee that your program can find
+its dlopened modules, even before installation, provided you have linked
+them using libtool.
+
+
+
+
+
+The following problems are not solved by using libtool's dlopen support:
+
+
+
+
+
+
+Dlopen functions are generally only available on shared library
+platforms. If you want your package to be portable to static platforms,
+you have to use either libltdl (see section Using libltdl) or develop your
+own alternatives to dlopening dynamic code.
+Most reasonable solutions involve writing wrapper functions for the
+dlopen family, which do package-specific tricks when dlopening
+is unsupported or not available on a given platform.
+
+
+
+There are major differences in implementations of the dlopen
+family of functions. Some platforms do not even use the same function
+names (notably HP-UX, with its shl_load family).
+
+
+
+The application developer must write a custom search function in order
+to discover the correct module filename to supply to dlopen.
+
+Libtool provides a small library, called `libltdl', that aims at
+hiding the various difficulties of dlopening libraries from programmers.
+It consists of a header-file and a small C source file that can be
+distributed with applications that need dlopening functionality. On
+some platforms, whose dynamic linkers are too limited for a simple
+implementation of `libltdl' services, it requires GNU DLD, or it
+will only emulate dynamic linking with libtool's dlpreopening mechanism.
+
+
+
+libltdl supports currently the following dynamic linking mechanisms:
+
+
+
+
+
+
+dlopen (Solaris, Linux and various BSD flavors)
+
+
+shl_load (HP-UX)
+
+
+LoadLibrary (Win16 and Win32)
+
+
+load_add_on (BeOS)
+
+
+GNU DLD (emulates dynamic linking for static libraries)
+
+
+libtool's dlpreopen (see see section Dlpreopening)
+
+
+
+libltdl is licensed under the terms of the GNU Library General Public License,
+with the following exception:
+
+
+
+
+
+As a special exception to the GNU Lesser General Public License,
+if you distribute this file as part of a program or library that
+is built using GNU libtool, you may include it under the same
+distribution terms that you use for the rest of that program.
+
+The libltdl API is similar to the dlopen interface of Solaris and Linux,
+which is very simple but powerful.
+
+
+
+To use libltdl in your program you have to include the header file `ltdl.h':
+
+
+
+
+#include <ltdl.h>
+
+
+
+The last release of libltdl used some symbols that violated the
+POSIX namespace conventions. These symbols are now deprecated,
+and have been replaced by those described here. If you have code that
+relies on the old deprecated symbol names, defining
+`LT_NON_POSIX_NAMESPACE' before you include `ltdl.h' provides
+conversion macros. Whichever set of symbols you use, the new api is
+not binary compatible with the last, so you will need to recompile
+your application in order to use this version of libltdl.
+
+
+
+Note that libltdl is not threadsafe, i.e. a multithreaded application
+has to use a mutex for libltdl. It was reported that GNU/Linux's glibc
+2.0's dlopen with `RTLD_LAZY' (which libltdl uses by
+default) is not thread-safe, but this problem is supposed to be fixed in
+glibc 2.1. On the other hand, `RTLD_NOW' was reported to introduce
+problems in multi-threaded applications on FreeBSD. Working around
+these problems is left as an exercise for the reader; contributions are
+certainly welcome.
+
+
+
+The following types are defined in `ltdl.h':
+
+
+
+
+
Type:lt_ptr
+
+lt_ptr is a generic pointer.
+
+
+
+
+
+
Type:lt_dlhandle
+
+lt_dlhandle is a module "handle".
+Every lt_dlopened module has a handle associated with it.
+
+
+
+
+
+
Type:lt_dlsymlist
+
+lt_dlsymlist is a symbol list for dlpreopened modules.
+This structure is described in see section Dlpreopening.
+
+
+
+
+libltdl provides the following functions:
+
+
+
+
+
Function: int lt_dlinit(void)
+
+Initialize libltdl.
+This function must be called before using libltdl
+and may be called several times.
+Return 0 on success, otherwise the number of errors.
+
+
+
+
+
+
Function: int lt_dlexit(void)
+
+Shut down libltdl and close all modules.
+This function will only then shut down libltdl when it was called as
+many times as lt_dlinit has been successfully called.
+Return 0 on success, otherwise the number of errors.
+
+Open the module with the file name filename and return a
+handle for it. lt_dlopen is able to open libtool dynamic
+modules, preloaded static modules, the program itself and
+native dynamic libraries.
+
+
+
+Unresolved symbols in the module are resolved using its dependency
+libraries (not implemented yet) and previously dlopened modules. If the
+executable using this module was linked with the -export-dynamic
+flag, then the global symbols in the executable will also be used to
+resolve references in the module.
+
+
+
+If filename is NULL and the program was linked with
+-export-dynamic or -dlopen self, lt_dlopen will
+return a handle for the program itself, which can be used to access its
+symbols.
+
+
+
+If libltdl cannot find the library and the file name filename does
+not have a directory component it will additionally search in the
+following search paths for the module (in the order as follows):
+
+
+
+
+
user-defined search path:
+
+This search path can be set by the program using the
+functions lt_dlsetsearchpath and lt_dladdsearchdir.
+
+
libltdl's search path:
+
+This search path is the value of the environment variable
+LTDL_LIBRARY_PATH.
+
+
system library search path:
+
+The system dependent library search path
+(e.g. on Linux it is LD_LIBRARY_PATH).
+
+
+
+Each search path must be a colon-separated list of absolute directories,
+for example, "/usr/lib/mypkg:/lib/foo".
+
+
+
+If the same module is loaded several times, the same handle is returned.
+If lt_dlopen fails for any reason, it returns NULL.
+
+The same as lt_dlopen, except that it tries to append
+different file name extensions to the file name.
+If the file with the file name filename cannot be found
+libltdl tries to append the following extensions:
+
+
+
+
+
the libtool archive extension `.la'
+
+
the extension used for native dynamic libraries on the host platform,
+
+e.g., `.so', `.sl', etc.
+
+
+
+This lookup strategy was designed to allow programs that don't
+have knowledge about native dynamic libraries naming conventions
+to be able to dlopen such libraries as well as libtool modules
+transparently.
+
+
+
+
+
+
Function: int lt_dlclose(lt_dlhandle handle)
+
+Decrement the reference count on the module handle.
+If it drops to zero and no other module depends on this module,
+then the module is unloaded.
+Return 0 on success.
+
+Return the address in the module handle, where the symbol given
+by the null-terminated string name is loaded.
+If the symbol cannot be found, NULL is returned.
+
+
+
+
+
+
Function: {const char *}lt_dlerror (void)
+
+Return a human readable string describing the most
+recent error that occurred from any of libltdl's functions.
+Return NULL if no errors have occurred since initialization
+or since it was last called.
+
+
+
+
+
+
Function: int lt_dlpreload(const lt_dlsymlist *preloaded)
+
+Register the list of preloaded modules preloaded.
+If preloaded is NULL, then all previously registered
+symbol lists, except the list set by lt_dlpreload_default,
+are deleted. Return 0 on success.
+
+
+
+
+
+
Function: int lt_dlpreload_default(const lt_dlsymlist *preloaded)
+
+Set the default list of preloaded modules to preloaded, which
+won't be deleted by lt_dlpreload. Note that this function does
+not require libltdl to be initialized using lt_dlinit and
+can be used in the program to register the default preloaded modules.
+Instead of calling this function directly, most programs will use the
+macro LTDL_SET_PRELOADED_SYMBOLS.
+
+
+
+Return 0 on success.
+
+
+
+
+
+
Macro:LTDL_SET_PRELOADED_SYMBOLS()
+
+Set the default list of preloaded symbols.
+Should be used in your program to initialize libltdl's
+list of preloaded modules.
+
+
+
+
Function: int lt_dladdsearchdir(const char *search_dir)
+
+Add the search directory search_dir to the user-defined library
+search path. Return 0 on success.
+
+
+
+
+
+
Function: int lt_dlsetsearchpath(const char *search_path)
+
+Replace the current user-defined library search path with
+search_path, which must be a colon-separated list of absolute
+directories. Return 0 on success.
+
+Return the current user-defined library search path.
+
+
+
+
+
+
Function: int lt_dlmakeresident(lt_dlhandle handle)
+
+Mark a module so that it cannot be `lt_dlclose'd. This can be
+useful if a module implements some core functionality in your project,
+which would cause your code to crash if removed. Return 0 on success.
+
+
+
+If you use `lt_dlopen (NULL)' to get a handle for the running
+binary, that handle will always be marked as resident, and consequently
+cannot be successfully `lt_dlclose'd.
+
+
+
+
+
+
Function: int lt_dlisresident(lt_dlhandle handle)
+
+Check whether a particular module has been marked as resident, returning 1
+if it has or 0 otherwise. If there is an error while executing this
+function, return -1 and set an error message for retrieval with
+lt_dlerror.
+
+
+
+
+
+
Variable: lt_ptr (*) (size_t size) lt_dlmalloc
+
+
Variable: void (*) (lt_ptr ptr) lt_dlfree
+
+These variables are set to malloc and free, by default,
+but you can set them to any other functions that provides equivalent
+functionality. However, you must not modify their values after calling
+any libltdl function other than lt_dlpreopen_default or the macro
+LTDL_SET_PRELOADED_SYMBOLS.
+
+Libtool modules are like normal libtool libraries with a few exceptions:
+
+
+
+You have to link the module with libtool's `-module' switch,
+and you should link any program that is intended to dlopen the module with
+`-dlopen modulename.la' so that libtool can dlpreopen the module
+on platforms which don't support dlopening. If the module depends on any
+other libraries, make sure you specify them either when you link the module
+or when you link programs that dlopen it.
+If you want to disable see section Library interface versions for a specific module
+you should link it with the `-avoid-version' switch.
+Note that libtool modules don't need to have a "lib" prefix.
+However, automake 1.4 or higher is required to build such modules.
+
+
+
+Usually a set of modules provide the same interface, i.e, exports the same
+symbols, so that a program can dlopen them without having to know more
+about their internals.
+In order to avoid symbol conflicts all exported symbols must be prefixed
+with "modulename_LTX_" (`modulename' is the name of the module).
+Internal symbols must be named in such a way that they won't conflict
+with other modules, for example, by prefixing them with "_modulename_".
+Although some platforms support having the same symbols defined more than
+once it is generally not portable and it makes it impossible to dlpreopen
+such modules. libltdl will automatically cut the prefix off to get
+the real name of the symbol. Additionally, it supports modules which
+don't use a prefix so that you can also dlopen non-libtool modules.
+
+
+
+`foo1.c' gives an example of a portable libtool module.
+Exported symbols are prefixed with "foo1_LTX_", internal symbols
+with "_foo1_". Aliases are defined at the beginning so that the code
+is more readable.
+
+
+
+
+/* aliases for the exported symbols */
+#define foo foo1_LTX_foo
+#define bar foo1_LTX_bar
+
+/* a global variable definition */
+int bar = 1;
+
+/* a private function */
+int _foo1_helper() {
+ return bar;
+}
+
+/* an exported function */
+int foo() {
+ return _foo1_helper();
+}
+
+
+
+The `Makefile.am' contains the necessary rules to build the
+module `foo1.la':
+
+
+
+
+Using the lt_dlmutex_register() function, and by providing some
+appropriate callback function definitions, libltdl can be used in a
+multi-threaded environment.
+
+
+
+
+
Type: void lt_dlmutex_lock(void)
+
+This is the type of a function pointer holding the address of a function
+which will be called at the start of parts of the libltdl implementation
+code which require a mutex lock.
+
+
+
+Because libltdl is inherantly recursive, it is important that the
+locking mechanism employed by these callback functions are reentrant, or
+else strange problems will occur.
+
+Many of the functions in the libltdl API have a special return
+value to indicate to the client that an error has occured. Normally (in
+single threaded applications) a string describing that error can be
+retrieved from internal storage with lt_dlerror().
+
+
+
+A function of this type must be registered with the library in order for
+it to work in a multi-threaded context. The function should store any
+error message passed in thread local storage.
+
+
+
+
+
+
Type: const char * lt_dlmutex_geterror(void)
+
+The type of a matching callback function to retrieve the last stored
+error message from thread local storage.
+
+
+
+When regeistered correctly this function will be used by
+lt_dlerror()) from all threads to retrieve error messages for the
+client.
+
+Use this function to register one of each of function ttypes described
+above in preparation for multi-threaded use of libltdl. All arguments
+must be valid non-NULL function addresses, or else all
+NULL to return to single threaded operation.
+
+Some of the internal information about each loaded module that is
+maintained by libltdl is available to the user, in the form of this
+structure:
+
+
+
+lt_dlinfo is used to store information about a module.
+The filename attribute is a null-terminated character string of
+the real module file name. If the module is a libtool module then
+name is its module name (e.g. "libfoo" for
+"dir/libfoo.la"), otherwise it is set to NULL. The
+ref_count attribute is a reference counter that describes how
+often the same module is currently loaded.
+
+
+
+
+The following function will return a pointer to libltdl's internal copy
+of this structure for the given handle:
+
+
+
+Return a pointer to a struct that contains some information about
+the module handle. The contents of the struct must not be modified.
+Return NULL on failure.
+
+
+
+
+Furthermore, in order to save you from having to keep a list of the
+handles of all the modules you have loaded, these functions allow you to
+iterate over libltdl's list of loaded modules:
+
+
+
+For each loaded module call the function func. The argument
+handle is the handle of one of the loaded modules, data is
+the data argument passed to lt_dlforeach.
+As soon as func returns a non-zero value for one of the handles,
+lt_dlforeach will stop calling func and immediately return 1.
+Otherwise 0 is returned.
+
+Iterate over the loaded module handles, returning the first handle in the
+list if place is NULL, and the next one on subsequent calls.
+If place is the last element in the list of loaded modules, this
+function returns NULL.
+
+
+
+
+Of course, you would still need to maintain your own list of loaded
+module handles to parallel the list maintained by libltdl if there are
+any other data that you need to associate with each handle for the
+purposes of your application. However, if you use the following
+API calls to associate your application data with individual module
+handles as they are loaded there is actually no need to do that. You
+must first obtain a unique caller id from libltdl which you subsequently
+use to retrieve the data you stored earlier. This allows for different
+libraries that each wish to store their own data against loaded modules
+to do so without interfering with one another's data.
+
+
+
+
+
Type:lt_dlcaller_id
+
+The opaque type used to hold individual data set keys.
+
+Set data as the set of data uniquely associated with key and
+handle for later retrieval. This function returns the data
+previously associated with key and handle if any. A result of
+0, may indicate that a diagnostic for the last error (if any) is available
+from lt_dlerror().
+
+
+
+For example, to correctly remove some associated data:
+
+
+
+
+Return the address of the data associated with key and
+handle, or else NULL if there is none.
+
+
+
+
+The preceding functions can be combined with lt_dlforeach to
+implement search and apply operations without the need for your
+application to track the modules that have been loaded and unloaded:
+
+
+
+
+Sometimes libltdl's many ways of gaining access to modules are not
+sufficient for the purposes of a project. You can write your own
+loader, and register it with libltdl so that lt_dlopen will be
+able to use it.
+
+
+
+Writing a loader involves writing at least three functions which can be
+called by lt_dlopen, lt_dlsym and lt_dlclose.
+Optionally, you can provide a finalisation function to perform any
+cleanup operations when lt_dlexit executes, and a symbol prefix
+string which will be prepended to any symbols passed to lt_dlsym.
+These functions must match the function pointer types below, after
+which they can be allocated to an instance of lt_user_dlloader
+and registered.
+
+
+
+Registering the loader requires that you choose a name for it, so that it
+can be recognised by lt_dlloader_find and removed with
+lt_dlloader_remove. The name you choose must be unique, and not
+already in use by libltdl's builtin loaders:
+
+
+
+
+
"dlopen"
+
+The system dynamic library loader, if one exists.
+
"dld"
+
+The GNU dld loader, if `libdld' was installed when libltdl was
+built.
+
"dlpreload"
+
+The loader for lt_dlopening of preloaded static modules.
+
+
+
+The prefix "dl" is reserved for loaders supplied with future versions of
+libltdl, so you should not use that for your own loader names.
+
+
+
+The following types are defined in `ltdl.h':
+
+
+
+
+
Type:lt_module
+
+lt_module is a dlloader dependent module.
+The dynamic module loader extensions communicate using these low
+level types.
+
+
+
+
+
+
Type:lt_dlloader
+
+lt_dlloader is a handle for module loader types.
+
+
+
+
+
+
Type:lt_dlloader_data
+
+lt_dlloader_data is used for specifying loader instance data.
+
+If you want to define a new way to open dynamic modules, and have the
+lt_dlopen API use it, you need to instantiate one of these
+structures and pass it to lt_dlloader_add. You can pass whatever
+you like in the dlloader_data field, and it will be passed back as
+the value of the first parameter to each of the functions specified in
+the function pointer fields.
+
+The type of the loader function for an lt_dlloader module
+loader. The value set in the dlloader_data field of the struct
+lt_user_dlloader structure will be passed into this function in the
+loader_data parameter. Implementation of such a function should
+attempt to load the named module, and return an lt_module
+suitable for passing in to the associated lt_module_close and
+lt_sym_find function pointers. If the function fails it should
+return NULL, and set the error message with lt_dlseterror.
+
+
+
+
+
+
Type: int lt_module_close(lt_dlloader_data loader_data, lt_module module)
+
+The type of the unloader function for a user defined module loader.
+Implementatation of such a function should attempt to release
+any resources tied up by the module module, and then unload it
+from memory. If the function fails for some reason, set the error
+message with lt_dlseterror and return non-zero.
+
+The type of the symbol lookup function for a user defined module loader.
+Implementation of such a function should return the address of the named
+symbol in the module module, or else set the error message
+with lt_dlseterror and return NULL if lookup fails.
+
+
+
+
+
+
Type: int lt_dlloader_exit(lt_user_data loader_data)
+
+The type of the finalisation function for a user defined module loader.
+Implementation of such a function should free any resources associated
+with the loader, including any user specified data in the
+dlloader_data field of the lt_user_dlloader. If non-NULL,
+the function will be called by lt_dlexit, and
+lt_dlloader_remove.
+
+
+
+
+For example:
+
+
+
+
+int
+register_myloader (void)
+{
+ lt_user_dlloader dlloader;
+
+ /* User modules are responsible for their own initialisation. */
+ if (myloader_init () != 0)
+ return MYLOADER_INIT_ERROR;
+
+ dlloader.sym_prefix = NULL;
+ dlloader.module_open = myloader_open;
+ dlloader.module_close = myloader_close;
+ dlloader.find_sym = myloader_find_sym.
+ dlloader.dlloader_exit = myloader_exit;
+ dlloader.dlloader_data = (lt_user_data)myloader_function;
+
+ /* Add my loader as the default module loader. */
+ if (lt_dlloader_add (lt_dlloader_next (NULL), &dlloader, "myloader") != 0)
+ return ERROR;
+
+ return OK;
+}
+
+
+
+Note that if there is any initialisation required for the loader,
+it must be performed manually before the loader is registered --
+libltdl doesn't handle user loader initialisation.
+
+
+
+Finalisation is handled by libltdl however, and it is important
+to ensure the dlloader_exit callback releases any resources claimed
+during the initialisation phase.
+
+
+
+libltdl provides the following functions for writing your own module
+loaders:
+
+
+
+
+
Function: int lt_dlloader_add(lt_dlloader *place, lt_user_dlloader *dlloader, const char *loader_name)
+
+Add a new module loader to the list of all loaders, either as the
+last loader (if place is NULL), else immediately before the
+loader passed as place. loader_name will be returned by
+lt_dlloader_name if it is subsequently passed a newly
+registered loader. These loader_names must be unique, or
+lt_dlloader_remove and lt_dlloader_find cannot
+work. Returns 0 for success.
+
+
+
+
+{
+ /* Make myloader be the last one. */
+ if (lt_dlloader_add (NULL, myloader) != 0)
+ perror (lt_dlerror ());
+}
+
+
+
+
+
+
+
Function: int lt_dlloader_remove(const char *loader_name)
+
+Remove the loader identified by the unique name, loader_name.
+Before this can succeed, all modules opened by the named loader must
+have been closed. Returns 0 for success, otherwise an error message can
+be obtained from lt_dlerror.
+
+
+
+
+Iterate over the module loaders, returning the first loader if place is
+NULL, and the next one on subsequent calls. The handle is for use with
+lt_dlloader_add.
+
+
+
+
+{
+ /* Make myloader be the first one. */
+ if (lt_dlloader_add (lt_dlloader_next (NULL), myloader) != 0)
+ return ERROR;
+}
+
+Return the first loader with a matching loader_name identifier, or else
+NULL, if the identifier is not found.
+
+
+
+The identifiers which may be used by libltdl itself, if the host
+architecture supports them are dlopen(9), dld and dlpreload.
+
+
+
+
+{
+ /* Add a user loader as the next module loader to be tried if
+ the standard dlopen loader were to fail when lt_dlopening. */
+ if (lt_dlloader_add (lt_dlloader_find ("dlopen"), myloader) != 0)
+ return ERROR;
+}
+
+Return the identifying name of PLACE, as obtained from
+lt_dlloader_next or lt_dlloader_find. If this function fails,
+it will return NULL and set an error for retrieval with
+lt_dlerror.
+
+Return the address of the dlloader_data of PLACE, as
+obtained from lt_dlloader_next or lt_dlloader_find. If
+this function fails, it will return NULL and set an error for
+retrieval with lt_dlerror.
+
Function: int lt_dladderror(const char *diagnostic)
+
+This function allows you to integrate your own error messages into
+lt_dlerror. Pass in a suitable diagnostic message for return by
+lt_dlerror, and an error identifier for use with
+lt_dlseterror is returned.
+
+
+
+If the allocation of an identifier fails, this function returns -1.
+
+
+
+
+When writing your own module loaders, you should use this function to
+raise errors so that they are propogated through the lt_dlerror
+interface. All of the standard errors used by libltdl are declared in
+`ltdl.h', or you can add more of your own with
+lt_dladderror. This function returns 0 on success.
+
+
+
+
+Even though libltdl is installed together with libtool, you may wish to
+include libltdl in the distribution of your package, for the convenience
+of users of your package that don't have libtool or libltdl installed.
+In this case, you must decide whether to manually add the ltdl
+objects to your package, or else which flavor of libltdl you want to use:
+a convenience library or an installable libtool library.
+
+
+
+The most simplistic way to add libltdl to your package is to copy
+the source files, `ltdl.c' and `ltdl.h', to a source directory
+withing your package and to build and link them along with the rest of
+your sources. To help you do this, the m4 macros for autoconf are
+available in `ltdl.m4'. You must ensure that they are available in
+`aclocal.m4' before you run autoconf -- by appending the contents
+of `ltdl.m4' to `acinclude.m4', if you are using automake, or
+to `aclocal.m4' if you are not. Having made the macros available,
+you must add a call to the `AC_LIB_LTDL' macro to your package's
+`configure.in' to perform the configure time checks required to
+build `ltdl.o' correctly. This method has problems if you then try
+to link the package binaries with an installed libltdl, or a library
+which depends on libltdl: you may have problems with duplicate symbol
+definitions.
+
+
+
+One advantage of the convenience library is that it is not installed, so
+the fact that you use libltdl will not be apparent to the user, and it
+will not overwrite a pre-installed version of libltdl a user might have.
+On the other hand, if you want to upgrade libltdl for any reason
+(e.g. a bugfix) you'll have to recompile your package instead of just
+replacing an installed version of libltdl.
+However, if your programs or libraries are linked with other libraries
+that use such a pre-installed version of libltdl, you may get linker
+errors or run-time crashes. Another problem is that you cannot link the
+convenience library into more than one libtool library, then link a
+single program with these libraries, because you may get duplicate
+symbols. In general you can safely use the convenience library in programs
+which don't depend on other libraries that might use libltdl too.
+In order to enable this flavor of libltdl, you should add the
+line `AC_LIBLTDL_CONVENIENCE' to your `configure.in',
+before`AC_PROG_LIBTOOL'.
+
+
+
+In order to select the installable version of libltdl, you should add a
+call of the macro `AC_LIBLTDL_INSTALLABLE' to your
+`configure.in'before`AC_PROG_LIBTOOL'. This macro
+will check whether libltdl is already installed and, if not, request the
+libltdl embedded in your package to be built and installed. Note,
+however, that no version checking is performed. The user may override
+the test and determine that the libltdl embedded must be installed,
+regardless of the existence of another version, using the configure
+switch `--enable-ltdl-install'.
+
+
+
+In order to embed libltdl into your package, just add `--ltdl' to
+the libtoolize command line. It will copy the libltdl sources
+to a subdirectory `libltdl' in your package.
+Both macros accept an optional argument to specify the location
+of the `libltdl' directory. By the default both macros assume that it
+is `${top_srcdir}/libltdl'.
+
+
+
+Whatever macro you use, it is up to you to ensure that your
+`configure.in' will configure libltdl, using
+`AC_CONFIG_SUBDIRS', and that your `Makefile's will start
+sub-makes within libltdl's directory, using automake's SUBDIRS,
+for example. Both macros define the shell variables LIBLTDL, to
+the link flag that you should use to link with libltdl, and
+INCLTDL, to the preprocessor flag that you should use to compile
+with programs that include `ltdl.h'. It is up to you to use
+`AC_SUBST' to ensure that this variable will be available in
+`Makefile's, or add them to variables that are `AC_SUBST'ed by
+default, such as LIBS and CPPFLAGS.
+
+
+
+If you're using the convenience libltdl, LIBLTDL will be the
+pathname for the convenience version of libltdl and INCLTDL will be
+`-I' followed by the directory that contains libltdl, both starting
+with `${top_builddir}/' or `${top_srcdir}/', respectively.
+
+
+
+If you request an installed version of libltdl and one is
+found(10), LIBLTDL will
+be set to `-lltdl' and INCLTDL will be empty (which is just a
+blind assumption that `ltdl.h' is somewhere in the include path if
+libltdl is in the library path). If an installable version of libltdl
+must be built, its pathname, starting with `${top_builddir}/',
+will be stored in LIBLTDL, and INCLTDL will be set just like
+in the case of convenience library.
+
+
+
+So, when you want to link a program with libltdl, be it a convenience,
+installed or installable library, just compile with `$(INCLTDL)'
+and link it with `$(LIBLTDL)', using libtool.
+
+
+
+You should probably also add `AC_LIBTOOL_DLOPEN' to your
+`configure.in'before`AC_PROG_LIBTOOL', otherwise
+libtool will assume no dlopening mechanism is supported, and revert to
+dlpreopening, which is probably not what you want.
+
+
+
+Avoid using the -static or -all-static switches when
+linking programs with libltdl. This will not work on all platforms,
+because the dlopening functions may not be available for static linking.
+
+
+
+The following example shows you how to embed the convenience libltdl in
+your package. In order to use the installable variant just replace
+`AC_LIBLTDL_CONVENIENCE' with `AC_LIBLTDL_INSTALLABLE'. We
+assume that libltdl was embedded using `libtoolize --ltdl'.
+
+
+
+configure.in:
+
+
+...
+dnl Enable building of the convenience library
+dnl and set LIBLTDL accordingly
+AC_LIBLTDL_CONVENIENCE
+dnl Substitute INCLTDL and LIBLTDL in the Makefiles
+AC_SUBST(INCLTDL)
+AC_SUBST(LIBLTDL)
+dnl Check for dlopen support
+AC_LIBTOOL_DLOPEN
+dnl Configure libtool
+AC_PROG_LIBTOOL
+dnl Configure libltdl
+AC_CONFIG_SUBDIRS(libltdl)
+...
+
+
+
+Makefile.am:
+
+
+...
+SUBDIRS = libltdl
+
+INCLUDES = $(INCLTDL)
+
+myprog_LDFLAGS = -export-dynamic
+# The quotes around -dlopen below fool automake <= 1.4 into accepting it
+myprog_LDADD = $(LIBLTDL) "-dlopen" self "-dlopen" foo1.la
+myprog_DEPENDENCIES = $(LIBLTDL) foo1.la
+...
+
+Libtool was first implemented in order to add support for writing shared
+libraries in the C language. However, over time, libtool is being
+integrated with other languages, so that programmers are free to reap
+the benefits of shared libraries in their favorite programming language.
+
+
+
+This chapter describes how libtool interacts with other languages,
+and what special considerations you need to make if you do not use C.
+
+
+
+
+
+Creating libraries of C++ code should be a fairly straightforward
+process, because its object files differ from C ones in only three ways:
+
+
+
+
+
+
+Because of name mangling, C++ libraries are only usable by the C++
+compiler that created them. This decision was made by the designers of
+C++ in order to protect users from conflicting implementations of
+features such as constructors, exception handling, and RTTI.
+
+
+
+On some systems, the C++ compiler must take special actions for the
+dynamic linker to run dynamic (i.e., run-time) initializers. This means
+that we should not call `ld' directly to link such libraries, and
+we should use the C++ compiler instead.
+
+
+
+C++ compilers will link some Standard C++ library in by default, but
+libtool does not know which are these libraries, so it cannot even run
+the inter-library dependence analyzer to check how to link it in.
+Therefore, running `ld' to link a C++ program or library is deemed
+to fail. However, running the C++ compiler directly may lead to
+problems related with inter-library dependencies.
+
+
+
+The conclusion is that libtool is not ready for general use for C++
+libraries. You should avoid any global or static variable
+initializations that would cause an "initializer element is not
+constant" error if you compiled them with a standard C compiler.
+
+
+
+There are other ways of working around this problem, but they are beyond
+the scope of this manual.
+
+
+
+Furthermore, you'd better find out, at configure time, what are the C++
+Standard libraries that the C++ compiler will link in by default, and
+explicitly list them in the link command line. Hopefully, in the
+future, libtool will be able to do this job by itself.
+
+
+
+
+
+Libtool is under constant development, changing to remain up-to-date
+with modern operating systems. If libtool doesn't work the way you
+think it should on your platform, you should read this chapter to help
+determine what the problem is, and how to resolve it.
+
+
+
+
+
+Libtool comes with its own set of programs that test its capabilities,
+and report obvious bugs in the libtool program. These tests, too, are
+constantly evolving, based on past problems with libtool, and known
+deficiencies in other operating systems.
+
+
+
+As described in the `INSTALL' file, you may run make check
+after you have built libtool (possibly before you install it) in order
+to make sure that it meets basic functional requirements.
+
+
+
+
+
+Here is a list of the current programs in the test suite, and what they
+test for:
+
+
+
+
+
`cdemo-conf.test'
+
+
`cdemo-exec.test'
+
+
`cdemo-make.test'
+
+
`cdemo-static.test'
+
+
`cdemo-shared.test'
+
+
+
+
+
+
+These programs check to see that the `cdemo' subdirectory of the
+libtool distribution can be configured and built correctly.
+
+The `cdemo' subdirectory contains a demonstration of libtool
+convenience libraries, a mechanism that allows build-time static
+libraries to be created, in a way that their components can be later
+linked into programs or other libraries, even shared ones.
+
+The tests `cdemo-make.test' and `cdemo-exec.test' are executed
+three times, under three different libtool configurations:
+`cdemo-conf.test' configures `cdemo/libtool' to build both
+static and shared libraries (the default for platforms that support
+both), `cdemo-static.test' builds only static libraries
+(`--disable-shared'), and `cdemo-shared.test' builds only
+shared libraries (`--disable-static').
+
+
`demo-conf.test'
+
+
`demo-exec.test'
+
+
`demo-inst.test'
+
+
`demo-make.test'
+
+
`demo-unst.test'
+
+
`demo-static.test'
+
+
`demo-shared.test'
+
+
`demo-nofast.test'
+
+
`demo-pic.test'
+
+
`demo-nopic.test'
+
+
+
+
+
+
+
+
+
+
+
+These programs check to see that the `demo' subdirectory of the
+libtool distribution can be configured, built, installed, and
+uninstalled correctly.
+
+The `demo' subdirectory contains a demonstration of a trivial
+package that uses libtool. The tests `demo-make.test',
+`demo-exec.test', `demo-inst.test' and
+`demo-unst.test' are executed four times, under four different
+libtool configurations: `demo-conf.test' configures
+`demo/libtool' to build both static and shared libraries,
+`demo-static.test' builds only static libraries
+(`--disable-shared'), and `demo-shared.test' builds only
+shared libraries (`--disable-static').
+`demo-nofast.test' configures `demo/libtool' to
+disable the fast-install mode (`--enable-fast-install=no').
+`demo-pic.test' configures `demo/libtool' to
+prefer building PIC code (`--with-pic'), `demo-nopic.test'
+to prefer non-PIC code (`--without-pic').
+
+
`deplibs.test'
+
+
+Many systems cannot link static libraries into shared libraries.
+libtool uses a deplibs_check_method to prevent such cases.
+This tests checks whether libtool's deplibs_check_method
+works properly.
+
+
`hardcode.test'
+
+
+On all systems with shared libraries, the location of the library can be
+encoded in executables that are linked against it see section Linking executables. This test checks the conditions under which your system
+linker hardcodes the library location, and guarantees that they
+correspond to libtool's own notion of how your linker behaves.
+
+
`build-relink.test'
+
+
+Checks whether variable shlibpath_overrides_runpath is properly
+set. If the test fails and VERBOSE is set, it will indicate what
+the variable should have been set to.
+
+
`noinst-link.test'
+
+
+Checks whether libtool will not try to link with a previously installed
+version of a library when it should be linking with a just-built one.
+
+
`depdemo-conf.test'
+
+
`depdemo-exec.test'
+
+
`depdemo-inst.test'
+
+
`depdemo-make.test'
+
+
`depdemo-unst.test'
+
+
`depdemo-static.test'
+
+
`depdemo-shared.test'
+
+
`depdemo-nofast.test'
+
+
+
+
+
+
+
+
+
+These programs check to see that the `depdemo' subdirectory of the
+libtool distribution can be configured, built, installed, and
+uninstalled correctly.
+
+The `depdemo' subdirectory contains a demonstration of inter-library
+dependencies with libtool. The test programs link some interdependent
+libraries.
+
+The tests `depdemo-make.test', `depdemo-exec.test',
+`depdemo-inst.test' and `depdemo-unst.test' are executed
+four times, under four different libtool configurations:
+`depdemo-conf.test' configures `depdemo/libtool' to build both
+static and shared libraries, `depdemo-static.test' builds only static
+libraries (`--disable-shared'), and `depdemo-shared.test' builds
+only shared libraries (`--disable-static').
+`depdemo-nofast.test' configures `depdemo/libtool' to
+disable the fast-install mode (`--enable-fast-install=no'.
+
+
`mdemo-conf.test'
+
+
`mdemo-exec.test'
+
+
`mdemo-inst.test'
+
+
`mdemo-make.test'
+
+
`mdemo-unst.test'
+
+
`mdemo-static.test'
+
+
`mdemo-shared.test'
+
+
+
+
+
+
+
+
+These programs check to see that the `mdemo' subdirectory of the
+libtool distribution can be configured, built, installed, and
+uninstalled correctly.
+
+The `mdemo' subdirectory contains a demonstration of a package that
+uses libtool and the system independent dlopen wrapper `libltdl' to
+load modules. The library `libltdl' provides a dlopen wrapper for
+various platforms (Linux, Solaris, HP/UX etc.) including support for
+dlpreopened modules (see section Dlpreopening).
+
+The tests `mdemo-make.test', `mdemo-exec.test',
+`mdemo-inst.test' and `mdemo-unst.test' are executed
+three times, under three different libtool configurations:
+`mdemo-conf.test' configures `mdemo/libtool' to build both
+static and shared libraries, `mdemo-static.test' builds only static
+libraries (`--disable-shared'), and `mdemo-shared.test' builds
+only shared libraries (`--disable-static').
+
+
`dryrun.test'
+
+
+This test checks whether libtool's --dry-run mode works properly.
+
+
`assign.test'
+
+
+Checks whether we don't put break or continue on the same
+line as an assignment in the libtool script.
+
+
`link.test'
+
+
+This test guarantees that linking directly against a non-libtool static
+library works properly.
+
+
`link-2.test'
+
+
+This test makes sure that files ending in `.lo' are never linked
+directly into a program file.
+
+
`nomode.test'
+
+
+Check whether we can actually get help for libtool.
+
+
`quote.test'
+
+
+This program checks libtool's metacharacter quoting.
+
+
`sh.test'
+
+
+Checks whether a `test' command was forgotten in libtool.
+
+
`suffix.test'
+
+
+When other programming languages are used with libtool (see section Using libtool with other languages), the source files may end in suffixes other than `.c'.
+This test validates that libtool can handle suffixes for all the file
+types that it supports, and that it fails when the suffix is invalid.
+
+
+Each of the above tests are designed to produce no output when they are
+run via make check. The exit status of each program tells the
+`Makefile' whether or not the test succeeded.
+
+
+
+If a test fails, it means that there is either a programming error in
+libtool, or in the test program itself.
+
+
+
+To investigate a particular test, you may run it directly, as you would
+a normal program. When the test is invoked in this way, it produces
+output which may be useful in determining what the problem is.
+
+
+
+Another way to have the test programs produce output is to set the
+VERBOSE environment variable to `yes' before running them.
+For example, env VERBOSE=yes make check runs all the tests, and
+has each of them display debugging information.
+
+
+
+
+
+If you think you have discovered a bug in libtool, you should think
+twice: the libtool maintainer is notorious for passing the buck (or
+maybe that should be "passing the bug"). Libtool was invented to fix
+known deficiencies in shared library implementations, so, in a way, most
+of the bugs in libtool are actually bugs in other operating systems.
+However, the libtool maintainer would definitely be happy to add support
+for somebody else's buggy operating system. [I wish there was a good
+way to do winking smiley-faces in Texinfo.]
+
+
+
+Genuine bugs in libtool include problems with shell script portability,
+documentation errors, and failures in the test suite (see section The libtool test suite).
+
+
+
+First, check the documentation and help screens to make sure that the
+behaviour you think is a problem is not already mentioned as a feature.
+
+
+
+Then, you should read the Emacs guide to reporting bugs (see section `Reporting Bugs' in The Emacs Manual). Some of the details
+listed there are specific to Emacs, but the principle behind them is a
+general one.
+
+
+
+Finally, send a bug report to the libtool bug reporting address bug-libtool@gnu.org with any appropriate
+facts, such as test suite output (see section When tests fail), all
+the details needed to reproduce the bug, and a brief description of why
+you think the behaviour is a bug. Be sure to include the word
+"libtool" in the subject line, as well as the version number you are
+using (which can be found by typing libtool --version).
+
+
+
+
+
+This chapter contains information that the libtool maintainer finds
+important. It will be of no use to you unless you are considering
+porting libtool to new systems, or writing your own libtool.
+
+
+
+
+
+Before you embark on porting libtool to an unsupported system, it is
+worthwhile to send e-mail to the libtool mailing list libtool@gnu.org, to make sure that you are
+not duplicating existing work.
+
+
+
+If you find that any porting documentation is missing, please complain!
+Complaints with patches and improvements to the documentation, or to
+libtool itself, are more than welcome.
+
+
+
+
+
+Once it is clear that a new port is necessary, you'll generally need the
+following information:
+
+
+
+
+
canonical system name
+
+You need the output of config.guess for this system, so that you
+can make changes to the libtool configuration process without affecting
+other systems.
+
+
man pages for ld and cc
+
+These generally describe what flags are used to generate PIC, to create
+shared libraries, and to link against only static libraries. You may
+need to follow some cross references to find the information that is
+required.
+
+
man pages for ld.so, rtld, or equivalent
+
+These are a valuable resource for understanding how shared libraries are
+loaded on the system.
+
+
man page for ldconfig, or equivalent
+
+This page usually describes how to install shared libraries.
+
+
output from ls -l /lib /usr/lib
+
+This shows the naming convention for shared libraries on the system,
+including which names should be symbolic links.
+
+
any additional documentation
+
+Some systems have special documentation on how to build and install
+shared libraries.
+
+
+
+If you know how to program the Bourne shell, then you can complete the
+port yourself; otherwise, you'll have to find somebody with the relevant
+skills who will do the work. People on the libtool mailing list are
+usually willing to volunteer to help you with new ports, so you can send
+the information to them.
+
+
+
+To do the port yourself, you'll definitely need to modify the
+libtool.m4 macros in order to make platform-specific changes to
+the configuration process. You should search that file for the
+PORTME keyword, which will give you some hints on what you'll
+need to change. In general, all that is involved is modifying the
+appropriate configuration variables (see section libtool script contents).
+
+
+
+Your best bet is to find an already-supported system that is similar to
+yours, and make your changes based on that. In some cases, however,
+your system will differ significantly from every other supported system,
+and it may be necessary to add new configuration variables, and modify
+the ltmain.in script accordingly. Be sure to write to the
+mailing list before you make changes to ltmain.in, since they may
+have advice on the most effective way of accomplishing what you want.
+
+
+
+
+
+Since version 1.2c, libtool has re-introduced the ability to do
+inter-library dependency on some platforms, thanks to a patch by Toshio
+Kuratomi badger@prtr-13.ucsc.edu. Here's a shortened version
+of the message that contained his patch:
+
+
+
+The basic architecture is this: in `libtool.m4', the person who
+writes libtool makes sure `$deplibs' is included in
+`$archive_cmds' somewhere and also sets the variable
+`$deplibs_check_method', and maybe `$file_magic_cmd' when
+`deplibs_check_method' is file_magic.
+
+
+
+`deplibs_check_method' can be one of five things:
+
+
+
`file_magic [regex]'
+
+
+
+
+looks in the library link path for libraries that have the right
+libname. Then it runs `$file_magic_cmd' on the library and checks
+for a match against regex using egrep. When
+file_magic_test_file is set by `libtool.m4', it is used as an
+argument to `$file_magic_cmd' in order to verify whether the
+regular expression matches its output, and warn the user otherwise.
+
+
`test_compile'
+
+
+just checks whether it is possible to link a program out of a list of
+libraries, and checks which of those are listed in the output of
+ldd. It is currently unused, and will probably be dropped in the
+future.
+
+
`pass_all'
+
+
+will pass everything without any checking. This may work on platforms
+in which code is position-independent by default and inter-library
+dependencies are properly supported by the dynamic linker, for example,
+on DEC OSF/1 3 and 4.
+
+
`none'
+
+
+It causes deplibs to be reassigned deplibs="". That way
+`archive_cmds' can contain deplibs on all platforms, but not have
+deplibs used unless needed.
+
+
`unknown'
+
+
+is the default for all systems unless overridden in `libtool.m4'.
+It is the same as `none', but it documents that we really don't
+know what the correct value should be, and we welcome patches that
+improve it.
+
+
+
+Then in `ltmain.in' we have the real workhorse: a little
+initialization and postprocessing (to setup/release variables for use
+with eval echo libname_spec etc.) and a case statement that decides
+which method is being used. This is the real code... I wish I could
+condense it a little more, but I don't think I can without function
+calls. I've mostly optimized it (moved things out of loops, etc) but
+there is probably some fat left. I thought I should stop while I was
+ahead, work on whatever bugs you discover, etc before thinking about
+more than obvious optimizations.
+
+
+
+
+
+This table describes when libtool was last known to be tested on
+platforms where it claims to support shared libraries:
+
+
+
+
+-------------------------------------------------------
+canonical host name compiler libtool results
+ (tools versions) release
+-------------------------------------------------------
+alpha-dec-osf5.1 cc 1.3e ok (1.910)
+alpha-dec-osf4.0f gcc 1.3e ok (1.910)
+alpha-dec-osf4.0f cc 1.3e ok (1.910)
+alpha-dec-osf3.2 gcc 0.8 ok
+alpha-dec-osf3.2 cc 0.8 ok
+alpha-dec-osf2.1 gcc 1.2f NS
+alpha*-unknown-linux-gnu gcc 1.3b ok
+ (egcs-1.1.2, GNU ld 2.9.1.0.23)
+hppa2.0w-hp-hpux11.00 cc 1.2f ok
+hppa2.0-hp-hpux10.20 cc 1.3.2 ok
+hppa1.1-hp-hpux10.20 gcc 1.2f ok
+hppa1.1-hp-hpux10.20 cc 1.3c ok (1.821)
+hppa1.1-hp-hpux10.10 gcc 1.2f ok
+hppa1.1-hp-hpux10.10 cc 1.2f ok
+hppa1.1-hp-hpux9.07 gcc 1.2f ok
+hppa1.1-hp-hpux9.07 cc 1.2f ok
+hppa1.1-hp-hpux9.05 gcc 1.2f ok
+hppa1.1-hp-hpux9.05 cc 1.2f ok
+hppa1.1-hp-hpux9.01 gcc 1.2f ok
+hppa1.1-hp-hpux9.01 cc 1.2f ok
+i*86-*-beos gcc 1.2f ok
+i*86-*-bsdi4.0.1 gcc 1.3c ok
+ (gcc-2.7.2.1)
+i*86-*-bsdi4.0 gcc 1.2f ok
+i*86-*-bsdi3.1 gcc 1.2e NS
+i*86-*-bsdi3.0 gcc 1.2e NS
+i*86-*-bsdi2.1 gcc 1.2e NS
+i*86-pc-cygwin gcc 1.3b NS
+ (egcs-1.1 stock b20.1 compiler)
+i*86-*-dguxR4.20MU01 gcc 1.2 ok
+i*86-*-freebsd4.3 gcc 1.3e ok (1.912)
+i*86-*-freebsdelf4.0 gcc 1.3c ok
+ (egcs-1.1.2)
+i*86-*-freebsdelf3.2 gcc 1.3c ok
+ (gcc-2.7.2.1)
+i*86-*-freebsdelf3.1 gcc 1.3c ok
+ (gcc-2.7.2.1)
+i*86-*-freebsdelf3.0 gcc 1.3c ok
+i*86-*-freebsd3.0 gcc 1.2e ok
+i*86-*-freebsd2.2.8 gcc 1.3c ok
+ (gcc-2.7.2.1)
+i*86-*-freebsd2.2.6 gcc 1.3b ok
+ (egcs-1.1 & gcc-2.7.2.1, native ld)
+i*86-*-freebsd2.1.5 gcc 0.5 ok
+i*86-*-netbsd1.5 gcc 1.3e ok (1.901)
+ (egcs-1.1.2)
+i*86-*-netbsd1.4 gcc 1.3c ok
+ (egcs-1.1.1)
+i*86-*-netbsd1.4.3A gcc 1.3e ok (1.901)
+i*86-*-netbsd1.3.3 gcc 1.3c ok
+ (gcc-2.7.2.2+myc2)
+i*86-*-netbsd1.3.2 gcc 1.2e ok
+i*86-*-netbsd1.3I gcc 1.2e ok
+ (egcs 1.1?)
+i*86-*-netbsd1.2 gcc 0.9g ok
+i*86-*-linux-gnu gcc 1.3e ok (1.901)
+ (Red Hat 7.0, gcc "2.96")
+i*86-*-linux-gnu gcc 1.4.2 ok
+ (SuSE 7.0, gcc 2.95.2)
+i*86-*-linux-gnulibc1 gcc 1.2f ok
+i*86-*-openbsd2.5 gcc 1.3c ok
+ (gcc-2.8.1)
+i*86-*-openbsd2.4 gcc 1.3c ok
+ (gcc-2.8.1)
+i*86-*-solaris2.7 gcc 1.3b ok
+ (egcs-1.1.2, native ld)
+i*86-*-solaris2.6 gcc 1.2f ok
+i*86-*-solaris2.5.1 gcc 1.2f ok
+i*86-ncr-sysv4.3.03 gcc 1.2f ok
+i*86-ncr-sysv4.3.03 cc 1.2e ok
+ (cc -Hnocopyr)
+i*86-pc-sco3.2v5.0.5 cc 1.3c ok
+i*86-pc-sco3.2v5.0.5 gcc 1.3c ok
+ (gcc 95q4c)
+i*86-pc-sco3.2v5.0.5 gcc 1.3c ok
+ (egcs-1.1.2)
+i*86-sco-sysv5uw7.1.1 gcc 1.3e ok (1.901)
+ (gcc-2.95.2, SCO linker)
+i*86-UnixWare7.1.0-sysv5 cc 1.3c ok
+i*86-UnixWare7.1.0-sysv5 gcc 1.3c ok
+ (egcs-1.1.1)
+m68k-next-nextstep3 gcc 1.2f NS
+m68k-sun-sunos4.1.1 gcc 1.2f NS
+ (gcc-2.5.7)
+m88k-dg-dguxR4.12TMU01 gcc 1.2 ok
+m88k-motorola-sysv4 gcc 1.3 ok
+ (egcs-1.1.2)
+mips-sgi-irix6.5 gcc 1.2f ok
+ (gcc-2.8.1)
+mips-sgi-irix6.4 gcc 1.2f ok
+mips-sgi-irix6.3 gcc 1.3b ok
+ (egcs-1.1.2, native ld)
+mips-sgi-irix6.3 cc 1.3b ok
+ (cc 7.0)
+mips-sgi-irix6.2 gcc 1.2f ok
+mips-sgi-irix6.2 cc 0.9 ok
+mips-sgi-irix5.3 gcc 1.2f ok
+ (egcs-1.1.1)
+mips-sgi-irix5.3 gcc 1.2f NS
+ (gcc-2.6.3)
+mips-sgi-irix5.3 cc 0.8 ok
+mips-sgi-irix5.2 gcc 1.3b ok
+ (egcs-1.1.2, native ld)
+mips-sgi-irix5.2 cc 1.3b ok
+ (cc 3.18)
+mips-sni-sysv4 cc 1.3.5 ok
+ (Siemens C-compiler)
+mips-sni-sysv4 gcc 1.3.5 ok
+ (gcc-2.7.2.3, GNU assembler 2.8.1, native ld)
+mipsel-unknown-openbsd2.1 gcc 1.0 ok
+powerpc-ibm-aix4.3.1.0 gcc 1.2f ok
+ (egcs-1.1.1)
+powerpc-ibm-aix4.2.1.0 gcc 1.2f ok
+ (egcs-1.1.1)
+powerpc-ibm-aix4.1.5.0 gcc 1.2f ok
+ (egcs-1.1.1)
+powerpc-ibm-aix4.1.5.0 gcc 1.2f NS
+ (gcc-2.8.1)
+powerpc-ibm-aix4.1.4.0 gcc 1.0 ok
+powerpc-ibm-aix4.1.4.0 xlc 1.0i ok
+rs6000-ibm-aix4.1.5.0 gcc 1.2f ok
+ (gcc-2.7.2)
+rs6000-ibm-aix4.1.4.0 gcc 1.2f ok
+ (gcc-2.7.2)
+rs6000-ibm-aix3.2.5 gcc 1.0i ok
+rs6000-ibm-aix3.2.5 xlc 1.0i ok
+sparc-sun-solaris2.8 gcc 1.4.2 ok
+ (gcc-2.95.2 & native ld)
+sparc-sun-solaris2.8 gcc 1.4.2 ok
+ (gcc-3.0.1 & GNU ld 2.11.2)
+sparc-sun-solaris2.7 gcc 1.3e ok (1.913)
+ (gcc-2.95.3 & native ld)
+sparc-sun-solaris2.6 gcc 1.3e ok (1.913)
+ (gcc-2.95.3 & native ld)
+sparc-sun-solaris2.5.1 gcc 1.4.2 ok
+ (gcc-2.95.1 & GNU ld 2.9.1)
+sparc-sun-solaris2.5 gcc 1.3b ok
+ (egcs-1.1.2, GNU ld 2.9.1 & native ld)
+sparc-sun-solaris2.5 cc 1.3b ok
+ (SC 3.0.1)
+sparc-sun-solaris2.4 gcc 1.0a ok
+sparc-sun-solaris2.4 cc 1.0a ok
+sparc-sun-solaris2.3 gcc 1.2f ok
+sparc-sun-sunos4.1.4 gcc 1.2f ok
+sparc-sun-sunos4.1.4 cc 1.0f ok
+sparc-sun-sunos4.1.3_U1 gcc 1.2f ok
+sparc-sun-sunos4.1.3C gcc 1.2f ok
+sparc-sun-sunos4.1.3 gcc 1.3b ok
+ (egcs-1.1.2, GNU ld 2.9.1 & native ld)
+sparc-sun-sunos4.1.3 cc 1.3b ok
+sparc-unknown-bsdi4.0 gcc 1.2c ok
+sparc-unknown-linux-gnulibc1 gcc 1.2f ok
+sparc-unknown-linux-gnu gcc 1.3b ok
+ (egcs-1.1.2, GNU ld 2.9.1.0.23)
+sparc64-unknown-linux-gnu gcc 1.2f ok
+
+Notes:
+- "ok" means "all tests passed".
+- "NS" means "Not Shared", but OK for static libraries
+
+
+
+Note: The vendor-distributed HP-UX sed(1) programs are horribly
+broken, and cannot handle libtool's requirements, so users may report
+unusual problems. There is no workaround except to install a working
+sed (such as GNU sed) on these systems.
+
+
+
+Note: The vendor-distributed NCR MP-RAS cc programs emits
+copyright on standard error that confuse tests on size of
+`conftest.err'. The workaround is to specify CC
+when run configure with CC='cc -Hnocopyr'.
+
+
+
+
+
+This section is dedicated to the sanity of the libtool maintainers. It
+describes the programs that libtool uses, how they vary from system to
+system, and how to test for them.
+
+
+
+Because libtool is a shell script, it can be difficult to understand
+just by reading it from top to bottom. This section helps show why
+libtool does things a certain way. Combined with the scripts
+themselves, you should have a better sense of how to improve libtool, or
+write your own.
+
+
+
+
+
+The only compiler characteristics that affect libtool are the flags
+needed (if any) to generate PIC objects. In general, if a C compiler
+supports certain PIC flags, then any derivative compilers support the
+same flags. Until there are some noteworthy exceptions to this rule,
+this section will document only C compilers.
+
+
+
+The following C compilers have standard command line options, regardless
+of the platform:
+
+
+
+
+
gcc
+
+This is the GNU C compiler, which is also the system compiler for many
+free operating systems (FreeBSD, GNU/Hurd, GNU/Linux, Lites, NetBSD, and
+OpenBSD, to name a few).
+
+The `-fpic' or `-fPIC' flags can be used to generate
+position-independent code. `-fPIC' is guaranteed to generate
+working code, but the code is slower on m68k, m88k, and Sparc chips.
+However, using `-fpic' on those chips imposes arbitrary size limits
+on the shared libraries.
+
+
+
+The rest of this subsection lists compilers by the operating system that
+they are bundled with:
+
+
+
+
+
aix3*
+
+
aix4*
+
+AIX compilers have no PIC flags, since AIX has been ported only to
+PowerPC and RS/6000 chips. (11)
+
+
hpux10*
+
+Use `+Z' to generate PIC.
+
+
osf3*
+
+Digital/UNIX 3.x does not have PIC flags, at least not on the PowerPC
+platform.
+
+
+On all known systems, a reloadable object can be created by running
+ld -r -o output.o input1.o input2.o. This
+reloadable object may be treated as exactly equivalent to other
+objects.
+
+
+
+
+
+On most modern platforms the order that dependent libraries are listed
+has no effect on object generation. In theory, there are platforms
+which require libraries which provide missing symbols to other libraries
+to listed after those libraries whose symbols they provide.
+
+
+
+Particularly, if a pair of static archives each resolve some of the
+other's symbols, it might be necessary to list one of those archives
+both before and after the other one. Libtool does not currently cope
+with this situation well, since dupicate libraries are removed from
+thr link line.
+
+
+
+If you find yourself developing on a host that requires you to list
+libraries multiple times in order for it to generate correctly linked
+objects, you can defeat libtool's removal algorithm like this:
+
+
+
+
+On all known systems, building a static library can be accomplished by
+running ar cru libname.a obj1.o obj2.o ...,
+where the `.a' file is the output library, and each `.o' file is an
+object file.
+
+
+
+On all known systems, if there is a program named ranlib, then it
+must be used to "bless" the created library before linking against it,
+with the ranlib libname.a command. Some systems, like Irix,
+use the ar ts command, instead.
+
+
+
+
+
+Since version 1.4, the libtool script is generated by
+configure (see section Configuring libtool). In earlier versions,
+configure achieved this by calling a helper script called
+`ltconfig'. From libtool version 0.7 to 1.0, this script
+simply set shell variables, then sourced the libtool backend,
+ltmain.sh. ltconfig from libtool version 1.1 through 1.3
+inlined the contents of ltmain.sh into the generated
+libtool, which improved performance on many systems. The tests
+that `ltconfig' used to perform are now kept in `libtool.m4'
+where thay can be written using Autoconf. This has the runtime
+performance benefits of inlined ltmain.sh, and improves
+the build time a little while considerably easing the amount of raw
+shell code that used to need maintaining.
+
+
+
+The convention used for naming variables which hold shell commands for
+delayed evaluation, is to use the suffix _cmd where a single
+line of valid shell script is needed, and the suffix _cmds where
+multiple lines of shell script may be delayed for later
+evaluation. By convention, _cmds variables delimit the
+evaluation units with the ~ character where necessary.
+
+
+
+Here is a listing of each of the configuration variables, and how they
+are used within ltmain.sh (see section Configuring libtool):
+
+
+
+
+
Variable:AR
+
+The name of the system library archiver.
+
+
+
+
+
+
Variable:CC
+
+The name of the C compiler used to configure libtool.
+
+
+
+
+
+
Variable:LD
+
+The name of the linker that libtool should use internally for reloadable
+linking and possibly shared libraries.
+
+
+
+
+
+
Variable:NM
+
+The name of a BSD-compatible nm program, which produces listings
+of global symbols in one the following formats:
+
+
+
+
+address C global-variable-name
+address D global-variable-name
+address T global-function-name
+
+
+
+
+
+
+
Variable:RANLIB
+
+Set to the name of the ranlib program, if any.
+
+
+
+
+
+
Variable:allow_undefined_flag
+
+The flag that is used by `archive_cmds' in order to declare that
+there will be unresolved symbols in the resulting shared library.
+Empty, if no such flag is required. Set to `unsupported' if there
+is no way to generate a shared library with references to symbols that
+aren't defined in that library.
+
+
+
+
+
+
Variable:always_export_symbols
+
+Whether libtool should automatically generate a list of exported symbols
+using export_symbols_cmds before linking an archive.
+Set to `yes' or `no'. Default is `no'.
+
+
+
+
+
+
Variable:archive_cmds
+
+
Variable:archive_expsym_cmds
+
+
Variable:old_archive_cmds
+
+Commands used to create shared libraries, shared libraries with
+`-export-symbols' and static libraries, respectively.
+
+
+
+
+
+
Variable:old_archive_from_new_cmds
+
+If the shared library depends on a static library,
+`old_archive_from_new_cmds' contains the commands used to create that
+static library. If this variable is not empty, `old_archive_cmds' is
+not used.
+
+
+
+
+
+
Variable:old_archive_from_expsyms_cmds
+
+If a static library must be created from the export symbol list in order to
+correctly link with a shared library, `old_archive_from_expsyms_cmds'
+contains the commands needed to create that static library. When these
+commands are executed, the variable soname contains the name of the
+shared library in question, and the $objdir/$newlib contains the
+path of the static library these commands should build. After executing
+these commands, libtool will proceed to link against $objdir/$newlib
+instead of soname.
+
+
+
+
+
+
Variable:build_libtool_libs
+
+Whether libtool should build shared libraries on this system. Set to
+`yes' or `no'.
+
+
+
+
+
+
Variable:build_old_libs
+
+Whether libtool should build static libraries on this system. Set to
+`yes' or `no'.
+
+
+
+
+
+
Variable:compiler_c_o
+
+Whether the compiler supports the -c and -o options
+simultaneously. Set to `yes' or `no'.
+
+
+
+
+
+
Variable:compiler_o_lo
+
+Whether the compiler supports compiling directly to a ".lo" file,
+i.e whether object files do not have to have the suffix ".o".
+Set to `yes' or `no'.
+
+
+
+
+
+
Variable:dlopen_support
+
+Whether dlopen is supported on the platform.
+Set to `yes' or `no'.
+
+
+
+
+
+
Variable:dlopen_self
+
+Whether it is possible to dlopen the executable itself.
+Set to `yes' or `no'.
+
+
+
+
+
+
Variable:dlopen_self_static
+
+Whether it is possible to dlopen the executable itself, when it
+is linked statically (`-all-static'). Set to `yes' or
+`no'.
+
+
+
+
+
+
Variable:echo
+
+An echo program which does not interpret backslashes as an
+escape character.
+
+
+
+
+
+
Variable:exclude_expsyms
+
+List of symbols that should not be listed in the preloaded symbols.
+
+
+
+
+
+
Variable:export_dynamic_flag_spec
+
+Compiler link flag that allows a dlopened shared library to reference
+symbols that are defined in the program.
+
+
+
+
+
+
Variable:export_symbols_cmds
+
+Commands to extract exported symbols from libobjs to the
+file export_symbols.
+
+
+
+
+
+
Variable:extract_expsyms_cmds
+
+Commands to extract the exported symbols list from a shared library.
+These commands are executed if there is no file $objdir/$soname-def,
+and should write the names of the exported symbols to that file, for
+the use of `old_archive_from_expsyms_cmds'.
+
+
+
+
+
+
Variable:fast_install
+
+Determines whether libtool will privilege the installer or the
+developer. The assumption is that installers will seldom run programs
+in the build tree, and the developer will seldom install. This is only
+meaningful on platforms in which shlibpath_overrides_runpath is
+not `yes', so fast_install will be set to `needless' in
+this case. If fast_install set to `yes', libtool will create
+programs that search for installed libraries, and, if a program is run
+in the build tree, a new copy will be linked on-demand to use the
+yet-to-be-installed libraries. If set to `no', libtool will create
+programs that use the yet-to-be-installed libraries, and will link
+a new copy of the program at install time. The default value is
+`yes' or `needless', depending on platform and configuration
+flags, and it can be turned from `yes' to `no' with the
+configure flag `--disable-fast-install'.
+
+
+
+
+
+
Variable:finish_cmds
+
+Commands to tell the dynamic linker how to find shared libraries in a
+specific directory.
+
+
+
+
+
+
Variable:finish_eval
+
+Same as finish_cmds, except the commands are not displayed.
+
+
+
+
+
+
Variable:fix_srcfile_path
+
+Expression to fix the shell variable $srcfile for the compiler.
+
+
+
+
+
+
Variable:global_symbol_pipe
+
+A pipeline that takes the output of NM, and produces a listing of
+raw symbols followed by their C names. For example:
+
+
+
+
+The first column contains the symbol type (used to tell data from code
+on some platforms), but its meaning is system dependent.
+
+
+
+
+
+
Variable:global_symbol_to_cdecl
+
+A pipeline that translates the output of global_symbol_pipe into
+proper C declarations. On platforms whose linkers differentiate code
+from data, such as HP/UX, data symbols will be declared as such, and
+code symbols will be declared as functions. On platforms that don't
+care, everything is assumed to be data.
+
+
+
+
+
+
Variable:hardcode_action
+
+Either `immediate' or `relink', depending on whether shared
+library paths can be hardcoded into executables before they are installed,
+or if they need to be relinked.
+
+
+
+
+
+
Variable:hardcode_direct
+
+Set to `yes' or `no', depending on whether the linker
+hardcodes directories if a library is directly specified on the command
+line (such as `dir/libname.a') when
+hardcode_libdir_flag_spec is specified.
+
+
+
+
+
+
Variable:hardcode_into_libs
+
+Whether the platform supports hardcoding of run-paths into libraries.
+If enabled, linking of programs will be much simpler but libraries will
+need to be relinked during installation. Set to `yes' or `no'.
+
+
+
+
+
+
Variable:hardcode_libdir_flag_spec
+
+Flag to hardcode a libdir variable into a binary, so that the
+dynamic linker searches libdir for shared libraries at runtime.
+If it is empty, libtool will try to use some other hardcoding mechanism.
+
+
+
+
+
+
Variable:hardcode_libdir_separator
+
+If the compiler only accepts a single hardcode_libdir_flag, then
+this variable contains the string that should separate multiple
+arguments to that flag.
+
+
+
+
+
+
Variable:hardcode_minus_L
+
+Set to `yes' or `no', depending on whether the linker
+hardcodes directories specified by `-L' flags into the resulting
+executable when hardcode_libdir_flag_spec is specified.
+
+
+
+
+
+
Variable:hardcode_shlibpath_var
+
+Set to `yes' or `no', depending on whether the linker
+hardcodes directories by writing the contents of `$shlibpath_var'
+into the resulting executable when hardcode_libdir_flag_spec is
+specified. Set to `unsupported' if directories specified by
+`$shlibpath_var' are searched at run time, but not at link time.
+
+
+
+
+
+
Variable:host
+
+
Variable:host_alias
+
+For information purposes, set to the specified and canonical names of
+the system that libtool was configured for.
+
+
+
+
+
+
Variable:include_expsyms
+
+List of symbols that must always be exported when using export_symbols.
+
+
+
+
+
+
Variable:libext
+
+The standard old archive suffix (normally "a").
+
+
+
+
+
+
Variable:libname_spec
+
+The format of a library name prefix. On all Unix systems, static
+libraries are called `libname.a', but on some systems (such
+as OS/2 or MS-DOS), the library is just called `name.a'.
+
+
+
+
+
+
Variable:library_names_spec
+
+A list of shared library names. The first is the name of the file,
+the rest are symbolic links to the file. The name in the list is
+the file name that the linker finds when given `-lname'.
+
+
+
+
+
+
Variable:link_all_deplibs
+
+Whether libtool must link a program against all its dependency libraries.
+Set to `yes' or `no'. Default is `unknown', which is
+a synonym for `yes'.
+
+
+
+
+
+
Variable:link_static_flag
+
+Linker flag (passed through the C compiler) used to prevent dynamic
+linking.
+
+
+
+
+
+
Variable:need_lib_prefix
+
+Whether libtool should automatically prefix module names with 'lib'.
+Set to `yes' or `no'. By default, it is `unknown', which
+means the same as `yes', but documents that we are not really sure
+about it.
+`yes' means that it is possible both to dlopen and to
+link against a library without 'lib' prefix,
+i.e. it requires hardcode_direct to be `yes'.
+
+
+
+
+
+
Variable:need_version
+
+Whether versioning is required for libraries, i.e. whether the
+dynamic linker requires a version suffix for all libraries.
+Set to `yes' or `no'. By default, it is `unknown', which
+means the same as `yes', but documents that we are not really sure
+about it.
+
+
+
+
+
+
Variable:need_locks
+
+Whether files must be locked to prevent conflicts when compiling
+simultaneously. Set to `yes' or `no'.
+
+
+
+
+
+
Variable:no_builtin_flag
+
+Compiler flag to disable builtin functions that conflict with declaring
+external global symbols as char.
+
+
+
+
+
+
Variable:no_undefined_flag
+
+The flag that is used by `archive_cmds' in order to declare that
+there will be no unresolved symbols in the resulting shared library.
+Empty, if no such flag is required.
+
+
+
+
+
+
Variable:objdir
+
+The name of the directory that contains temporary libtool files.
+
+
+
+
+
+
Variable:objext
+
+The standard object file suffix (normally "o").
+
+
+
+
+
+
Variable:pic_flag
+
+Any additional compiler flags for building library object files.
+
+
+
+
+
+
Variable:postinstall_cmds
+
+
Variable:old_postinstall_cmds
+
+Commands run after installing a shared or static library, respectively.
+
+
+
+
+
+
Variable:postuninstall_cmds
+
+
Variable:old_postuninstall_cmds
+
+Commands run after uninstalling a shared or static library, respectively.
+
+
+
+
+
+
Variable:reload_cmds
+
+
Variable:reload_flag
+
+Commands to create a reloadable object.
+
+
+
+
+
+
Variable:runpath_var
+
+The environment variable that tells the linker which directories to
+hardcode in the resulting executable.
+
+
+
+
+
+
Variable:shlibpath_overrides_runpath
+
+Indicates whether it is possible to override the hard-coded library
+search path of a program with an environment variable. If this is set
+to no, libtool may have to create two copies of a program in the build
+tree, one to be installed and one to be run in the build tree only.
+When each of these copies is created depends on the value of
+fast_install. The default value is `unknown', which is
+equivalent to `no'.
+
+
+
+
+
+
Variable:shlibpath_var
+
+The environment variable that tells the dynamic linker where to find
+shared libraries.
+
+
+
+
+
+
Variable:soname_spec
+
+The name coded into shared libraries, if different from the real name of
+the file.
+
+
+
+
+
+
Variable:striplib
+
+
Variable:old_striplib
+
+Command to strip a shared (striplib) or static (old_striplib)
+library, respectively. If these variables are empty, the strip flag
+in the install mode will be ignored for libraries (see section Install mode).
+
+
+
+
+
+
Variable:sys_lib_dlsearch_path_spec
+
+Expression to get the run-time system library search path. Directories
+that appear in this list are never hard-coded into executables.
+
+
+
+
+
+
Variable:sys_lib_search_path_spec
+
+Expression to get the compile-time system library search path. This
+variable is used by libtool when it has to test whether a certain
+library is shared or static. The directories listed in
+shlibpath_var are automatically appended to this list, every time
+libtool runs (i.e., not at configuration time), because some linkers use
+this variable to extend the library search path. Linker switches such
+as -L also augment the search path.
+
+
+
+
+
+
Variable:thread_safe_flag_spec
+
+Linker flag (passed through the C compiler) used to generate thread-safe
+libraries.
+
+
+
+
+
+
Variable:version_type
+
+The library version numbering type. One of `libtool',
+`freebsd-aout', `freebsd-elf', `irix', `linux',
+`osf', `sunos', `windows', or `none'.
+
+
+
+
+
+
Variable:whole_archive_flag_spec
+
+Compiler flag to generate shared objects from convenience archives.
+
+
+
+
+
+
Variable:wl
+
+The C compiler flag that allows libtool to pass a flag directly to the
+linker. Used as: ${wl}some-flag.
+
+
+
+
+Variables ending in `_cmds' or `_eval' contain a
+`~'-separated list of commands that are evaled one after
+another. If any of the commands return a nonzero exit status, libtool
+generally exits with an error message.
+
+
+
+Variables ending in `_spec' are evaled before being used by
+libtool.
+
+
+
+
+
+Here are a few tricks that you can use in order to make maintainership
+easier:
+
+
+
+
+
+
+When people report bugs, ask them to use the `--config',
+`--debug', or `--features' flags, if you think they will help
+you. These flags are there to help you get information directly, rather
+than having to trust second-hand observation.
+
+
+
+Rather than reconfiguring libtool every time I make a change to
+ltmain.in, I keep a permanent libtool script in my
+PATH, which sources ltmain.in directly.
+
+The following steps describe how to create such a script, where
+/home/src/libtool is the directory containing the libtool source
+tree, /home/src/libtool/libtool is a libtool script that has been
+configured for your platform, and ~/bin is a directory in your
+PATH:
+
+
+
+The output of the final `libtool --version' command shows that the
+ltmain.in script is being used directly. Now, modify
+~/bin/libtool or /home/src/libtool/ltmain.in directly in
+order to test new changes without having to rerun configure.
+
+
+
+
+
+Copyright (C) 2000 Free Software Foundation, Inc.
+ 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+The purpose of this License is to make a manual, textbook, or other
+written document "free" in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially. Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+
+
+This License is a kind of "copyleft", which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+
+
+
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The "Document", below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as "you".
+
+
+
+A "Modified Version" of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+
+
+A "Secondary Section" is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+
+
+The "Invariant Sections" are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+
+
+The "Cover Texts" are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+
+
+A "Transparent" copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not "Transparent" is called "Opaque".
+
+
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML designed for human modification. Opaque formats include
+PostScript, PDF, proprietary formats that can be read and edited only
+by proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML produced by some word processors for output
+purposes only.
+
+
+
+The "Title Page" means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, "Title Page" means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+
+
+
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+
+
+
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+
+
+
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+
+
+
+
+
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+
+
+ List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has less than five).
+
+
+
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+
+
+ Preserve all the copyright notices of the Document.
+
+
+
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+
+
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+
+
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+
+
+Include an unaltered copy of this License.
+
+
+
+Preserve the section entitled "History", and its title, and add to
+it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section entitled "History" in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+
+
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the "History" section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+
+
+In any section entitled "Acknowledgements" or "Dedications",
+preserve the section's title, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements
+and/or dedications given therein.
+
+
+
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
+
+
+Delete any section entitled "Endorsements". Such a section
+may not be included in the Modified Version.
+
+
+
+Do not retitle any existing section as "Endorsements"
+or to conflict in title with any Invariant Section.
+
+
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+
+
+You may add a section entitled "Endorsements", provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+
+
+
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+
+
+In the combination, you must combine any sections entitled "History"
+in the various original documents, forming one section entitled
+"History"; likewise combine any sections entitled "Acknowledgements",
+and any sections entitled "Dedications". You must delete all sections
+entitled "Endorsements."
+
+
+
+
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+
+
+
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an "aggregate", and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
+
+
+
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
+
+
+
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+
+
+
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+http://www.gnu.org/copyleft/.
+
+
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+
+
+
+
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+
+
+
+Copyright (c) YEAR YOUR NAME.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation;
+with the Invariant Sections being LIST THEIR TITLES, with the
+Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+A copy of the license is included in the section entitled "GNU
+Free Documentation License".
+
+
+
+If you have no Invariant Sections, write "with no Invariant Sections"
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write "no Front-Cover Texts" instead of
+"Front-Cover Texts being LIST"; likewise for Back-Cover Texts.
+
+
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+
+
+
+
GNU shtool is a compilation of small but very stable and portable shell
+scripts into a single shell tool. All ingredients were in successful use over
+many years in various free software projects. The compiled shtool script is
+intended to be used inside the source tree of those free software packages.
+There it can take over various (usually non-portable) tasks related to the
+building and installation of such packages.
For the configuration, build and installation environment of modern free
+software packages one nowadays uses GNU autoconf and friends (i.e.
+usually autoconf, automake and libtool). Autoconf covers the
+configuration, automake covers the generation of the build environment and
+libtool covers most of a libraries build process. But at least when it
+comes to the installation step one usually have to use a few auxiliary scripts
+like mkdir.sh, install.sh, etc. These scripts are usually replacements
+for system tools and are required mainly for portability reasons. The result
+is usually an etc/ subdirectory in the source tree where over time a
+lot shell scripts accumulate.
The problem with those etc/ shell scripts starts if one has to maintain
+lots of free software packages as it's the case for the author of shtool.
+Then over time all etc/ directories diverge and with every day it gets more
+and more nasty to always keep them in sync. Especially if some scripts
+were locally adjusted because no centralized maintainance location exists, of
+course. For autoconf no such problem exists, because the resulting
+configure script is generated on-the-fly. The same applies to automake
+and the various Makefile.in files.
+
Only for libtool one always has to grab the latest copy. But because it's
+just two files (ltmain.sh and ltconfig), keeping a source trees in sync
+is not too complicated (especially not if using the handy libtoolize
+program). But the etc/ shell script mess is nasty, especially because there
+is no master version on the net. Additionally everytime one starts a new
+project, one has to establish a new source tree. For a GNU hacker it's
+immediately clear that autoconf and friends are part of the game. But which
+etc/ shell scripts are needed this time? And from which existing source
+tree to copy them from? Hmmm... the same procedure as last year?!
When a free software package has a large source tree (say, more than 50 files
+and especially with one or more subdirectories) it's usually no problem to
+have an additional etc/ subdirectory with some scripts. They then totally
+go down. But for smaller packages, especially those living in a single source
+directory (a degenerated tree), some people (like the author of shtool)
+have aesthetic problems. Because it looks strange to them that 20% of the
+files in the source tree are just auxiliary scripts. Sure, the actual amount
+of script code even shtool cannot reduce, but shtool merges them
+together into a single file and this way they optically totally disappear from
+the source tree.
+
This is a pure aesthetical issue, of course. But keep in mind that hacking is
+a piece of art. And a well layouted source tree is a piece of art for real
+hackers, too. Oh, and for those who really insist on a technical reason: it's
+also easier to upgrade a single file than multiple files ;)
So, wouldn't it be nice to have a fourth package (beside autoconf,
+automake and libtool) which fills the gap, i.e. which provides the
+functionality of the old files in etc/, is maintained at a centralized
+location and even consists of just a single (perhaps large) script one can
+threat as a black box the same way one already does this for libtool? The
+author thought this would be actually very useful and the result is the
+current GNU shtool package which at least successfully solved the above
+problems of the author.
To better understand the intentions behind shtool and to avoid confusion,
+here are the original goals of the shtool script:
+
+
1. It has to be self-contained and reside in a single file
+
+This was achieved by compiling the resulting shtool script out of the
+ingredient source scripts. The advantage is that shtool is still easily
+maintainable, because one can test each script separately. But the final
+functionality then resides in an all-in-one script which can be easily spread
+over multiple source trees.
+
+
3. It has to be maximum portable over all Unix flavors
+
+This was achieved by basing the ingredient shell scripts only on well-proven
+code which already survived practice in other projects over more than a few
+months. Especially this means that a lot of complicated emulations are done to
+avoid the use of unportable Unix programs (like fmt, tr, etc) or
+unportable features of well-known Unix programs (like shell functions, special
+sed features, etc. pp). That's why shtool's code sometimes looks crazy
+and like overkill to you. Don't think this is because of the authors
+crazyness. Instead it's most of the time mainly for portability reasons.
+
+
4. It has to be clean and fully documented
+
+This was achieved by reimplementing too ugly functionality from scratch and
+cleaning up old shell script code plus writing this complete manual page.
+
+
5. It has to stay under a reasonable and common license
+
+This was achieved by placing the shtool package under the GNU General
+Public License (GPL). This way the shtool package itself is well protected
+and is guarrantied to be kept free software, but the resulting shtool
+script can be nevertheless used in all types of source trees. Notice
+here: given that one includes GNU shtool verbatim into an own source tree,
+one is justified in saying that it remains separate from the own package, and
+that this way one is simply just usingshtool. So, in this situation,
+there is no requirement that the package itself is licensed under the GNU
+General Public License in order to take advantage of shtool. Keep this in
+mind ;)
+
+
6. It has to be modularized for flexibility reasons
+
+This was achieved by using an auxiliary tool shtoolize(1) which can be used to
+build individual shtool scripts out of the ingredient shell scripts. This
+way if one don't need all the available functionality one can assemble
+together an individual shtool script.
+
The following commands are provided by shtool. They are all called via
+``shtoolcommand''. Any trailing command_options are specific to the
+particular command. They are listed (here and also below) sorted by topic,
+i.e. related commands are listed side-by-side.
+mkdir(1) style command providing support for auto-parent-dir creation,
+directory permission control and smart skipping if directory already
+exists.
+
+
+This is an echo(1) style print command which provides special expansion
+constructs (terminal bold mode, environment details, date) and newline
+control. Per default string is written to stdout followed by a newline
+character (``\n''). When option ``-n'' is used this newline character is
+left out.
+
The str can contain special ``%x'' constructs which which
+are expanded before the output is written if option ``-e'' is
+used. Currently the following constructs are recognized: ``%B''
+for switching to terminal bold mode, ``%b'' for switching terminal
+mode back to normal display mode, ``%u'' for the current user name,
+``%U'' for the current user id (numerical), ``%g'' for the current
+group name, ``%G'' for the current group id (numerical), ``%h''
+for the current hostname, ``%d'' for the current domain name,
+``%D'' for the current day of the month, ``%M'' for the current
+month (numerical), ``%m'' for the current month name and ``%Y''
+for the current year.
+
The trick of this command is that it provides a portable ``-n'' option and
+hides the gory details needed to find out the environment details.
+
Examples:
+
+ # shell script
+ shtool echo -n -e "Enter your name [%B%u%b]: "; read name
+ shtool echo -e "Your Email address might be %u@%h%d"
+ shtool echo -e "The current date is %D-%m-%Y"
+This command pretty-prints the last modification time of a file or directory
+path. Option ``-n'' suppresses the output of a trailing newline
+character, option ``-z'' pads numeric day (and optionally month) with a
+leading zero, option ``-s'' shortens the months name to an abbreviation of
+three characters, option ``-d'' replaces the month name with the
+corresponding digits, option ``-f'' uses str as the field separator
+(default is a single space character) and option ``-o'' specified the order
+in which the fields are printed.
+
The default for spec is ``dmy'' which means an output of ``<day> <month>
+<year>''. Any combination of the chars ``d'', ``m'' and ``y'' or
+allowed for spec.
+
The trick of this command is that it provides a portable way to find out the
+date of a file or directory while still allowing one to specify the format of
+the date display.
+This pretty-prints a sep-separated list of strings as a table. Per
+default a colon-separated list (sep=``:'') is pretty printed as a
+three-column (<cols>=3) table no longer than 79 chars (strip=79) is
+generated where each column is 15 characters wide (width=15).
+
The trick of this command is that it avoids to use the unportable tr(1) and
+fmt(1) commands and instead is based entirely on sh(1), awk(1) and sed(1)
+functionality.
+This command displays a processing indication though a running propeller. The
+option ``-p'' can be used to set a particular prefix str which is
+displayed in front of the propeller. The default is no prefix string, i.e. the
+propeller is at the left border of the terminal. This command is intended to
+be run at the end of a pipe (``|'') sequence where on stdin
+logging/processing informations found. For every line on stdin the
+propeller cycles one step clock-wise.
+
The trick of this command is that it provides a portable and easy to use way
+to display such nice and psychologically important process indicators.
+This is a mv(1) style command, but with two special features: First if
+option ``-e'' (`expand') is used and an asterisk occurs somewhere in src
+one can use ``%n'' (where n is 1,2,...) in dst-file. This is
+useful for renaming multiple files at once. Second, if option ``-p''
+(for `preserve') is used and src-file and dst-file are byte-wise the
+same it just deletes src-file. The intention is that the permissions and
+time stamps on dst aren't changed which is important if dst-file is
+used in conjunction with Makefiles. Option ``-v'' (verbose) can be used to
+enable the output of extra processing information. Option ``-t'' (trace)
+can be used to enable the output of the essential shell commands which are
+executed.
+
The trick of this command is that it can rename multiple files at once and
+preserves the timestamps if the contents isn't changed.
+This command installs a program, script or datafile (dependent on mode) in
+a portable way while providing all important options of the BSD install(1)
+command. Per default file is moved to the target path, but with option
+``-c'' file is copied. The target file is created with owner/group set
+to the current active uid/gid, but if this script is called as root (uid 0)
+the options ``-o'' and ``-g'' can be used to override this.
+
Additionally program executables is stripped with strip(1) after
+installation if option ``-s'' is used. Option ``-C'' is like
+``-c'', except if the destination file already exists and the files
+are the same, the source is just removed. Option ``-e'' can be used
+one or multiple times to apply one or more sed(1) commands on-the-fly
+to the contents of the input file before the output file is created.
+Option ``-v'' (verbose) can be used to enable the output of extra
+processing information. Option ``-t'' (trace) can be used to enable
+the output of the essential shell commands which are executed.
+
The trick of this command is that it provides the functionality of BSD
+install(1) in a portable emulated way.
+This is a mkdir(1) style command providing support for automatic parent
+directory creation (if option ``-p'' is used), directory permission
+control (with option ``-mmode'' where mode can be in any of
+the formats specified to the chmod(1) command) and smart skipping if
+dir already exists (triggered by the force option ``-f''). Option
+``-t'' (trace) can be used to enable the output of the essential
+shell commands which are executed.
+
The trick of this command is that it provides both a portable ``-p''
+functionality and the ability to be smart if the directory already exists
+which is important for installation procedures.
+This is a ln(1) style command which provides automatic calculation and usage
+of relative links if possible, i.e. usually if src-path and dst-path
+are not absolute paths or at least they share a common prefix except the root
+directory (``/''). When more than one src-path is specified, all of them
+are linked into dst-path. Options ``-f'' and ``-s'' are similar to
+ln(1), i.e. they force the creation of the link (even if it exists) and
+create a symbolic link instead of a hard-link. Option ``-t'' (trace) can
+be used to enable the output of the essential ``ln'' command which is
+executed.
+
The trick of this command is that it tried hard to calculate the paths to get
+the maximum possible relative paths.
+This command creates a shadow tree of src-dir under dst-dir by
+recreating the directory hierarchy of src-dir under dst-dir and by
+creating the files of src-dir by linking them into the corresponding
+directories under dst-dir via symbolic links. When src-dir can be
+reached via relative paths from dst-dir, relative symbolic links are used,
+too.
+
Option ``-v'' (verbose) can be used to enable some displaying of processing
+information. Option ``-t'' (trace) can be used to display all commands
+which are executed in order to construct dst-dir. Option ``-a'' (all)
+can be used to really shadow all files and directories in src-dir. Per
+default CVS related files and directories, backup files, object files, etc.
+are not shadowed.
+
The trick of this is that is provides such a high-level functionality with a
+single command and hides all gory details.
+This command fixes file permissions inside a source tree under path by
+cleaning up the permission bits. It determines the cleaned up permission from
+the already set bits. It's intended to be run before a tarball is rolled out
+of the source tree. Option ``-v'' can be used to display some processing
+information. Option ``-t'' (trace) can be used to enable the output of the
+essential shell commands which are executed.
+
The trick is that this is more convenient that having to set the permissions
+manually or with a large file list.
+This command rotates a logfile file by subsequently creating up to
+count (optionally compressed) archive files of it. Archive files are
+named ``file.number[compress-suffix]'' where number is the
+version number, 0 being the newest and ``count-1'' the oldest.
+
A rotation step consists of the following steps: 1. remove archive file
+number count-1; 2. move archive file number N-1 to N for N
+counting from 1 to count-1; 3. move file to archive file number 0;
+4. creating a new and empty instance of file.
+
Option ``-s'' can be used to only start a rotation step if file is
+at least size bytes long. The argument size can be specified also
+with the trailing units K (kilo), M (mega) or G (giga).
+
Option ``-c'' changes the approach of moving file to archive file
+number 0: instead of a move followed by the creation of a new file, a
+copy is performed followed by a truncation of file. The difference is
+that in the first case (the default), if an application has file
+still opened, after the rotation step it will have archive file number
+0 opened and usually has to reopen the new file, while in the second
+case the application can keep its open file handles to file. The
+drawback of the second approach is that logfile entries are lost when
+they are written to file between the execution of the copy and the
+subsequent truncation operation.
+
Option ``-r'' removes file after rotation instead of providing a
+new empty file. Option ``-a'' forces archive files to be created in
+the separate directory dir.
+
Option ``-z'' enables compression of archive files with compression
+level level (if option ``-b'' is present, compression takes place in
+background). By default, the tools bzip2(1), gzip(1) and compress(1) are
+searched for in $PATH (in this order), but one also can override this
+by prefixing the compression level with one of the three particular tool
+names. Option ``-d'' delays the compression of archive file number 0.
+This is useful if option ``-c'' is not used, because an application
+might still write to archive file 0 (through an open file handle).
+
Option ``-p'' enables padding with leading zeros in the number
+part of the filename ``file.numbercompress-suffix''. The default
+padding len is 1. This is interesting if more than 10 archive files
+are used, because it leads to still sorted directory listings.
+
Options ``-o'', ``-g'' and ``-m'' can be used to make sure that
+the created files have particular file attributes. The valid arguments
+are the same as for chown(1), chgrp(1) and chmod(1). Be aware that using
+options ``-o'' and ``-g'' require root privileges.
+
Option ``-M'' allows one to execute a ``migration'' command just before
+the archive file number count-1 is removed from the filesystem. The
+specified cmd gets the archive filename as an argument appended.
+Options ``-P'' (prolog) and ``-E'' (epilog) can be used to execute
+commands before and after the rotation step. They are interesting in
+conjunction with option ``-s'', because they are not executed at all
+if it is decided that no rotation step is performed.
+
Option ``-f'' (force) can be used to allow the archive directory
+(option ``-a'') to be silently created if it still does not exist and
+that still not existing intermediate logfiles are silently skipped in
+the rotation step.
+
Option ``-v'' (verbose) can be used to display the files which are
+rotated. Option ``-t'' (trace) can be used to enable the output of
+the essential shell commands which are executed for the rotation step.
+This command is for `rolling' distribution `tarballs', i.e. for the creation
+of distribution files generated by `tar'. The important aspects of
+standardized free software tarballs are: first they have to unpack into a
+single top-level directory; second this top-level directory should correspond
+to the tarball filename (i.e. a tarball `foobar-0.8.15.tar' per convention
+unpacks into a top-level directory `foobar-0.8.15/'); third the files in
+the tarball should be sorted to allow users to use the `tar tvf -' command
+in a reasonable way; fourth the owner and group of the files in the tarball
+for security reasons can be set to arbitrary names.
+
The input files are given by the file or directory arguments path.
+Directories are expanded before the comma-separated exclude (option -e)
+patterns (grep regular expressions) are used to filter the list. The
+default filter is ``CVS,\\.cvsignore,\\.[oa]\$''. Then the tarball is
+created with its files owned by user (option -u) and group (option
+-g). Finally the resulting tarball is piped through an optional compression
+(option -c) program and written to the output file tarball (option
+-o). Option ``-v'' can be used to display the files which are stored in
+the tarball. Option ``-t'' (trace) can be used to enable the output of the
+essential shell commands which are executed.
+
The trick of this command is that it combines the complex process of rolling a
+good tarball into a single command.
+
Example:
+
+ # Makefile.in
+ dist:
+ ...
+ V=`shtool version -d short ...'; \
+ shtool tarball -o foobar-$$V.tar.gz -c 'gzip -9' \
+ -u bar -g gnu -e 'CVS,\.cvsignore' .
+This command applies one or more sed(1) substitution operations to
+stdin or any number of files. The sed(1) operations are either
+specified on the command line with option ``-e'' or are contained
+in a file cmd-file and are specified with option ``-f''. The
+original untouched file is usually overridden. If option ``-b''
+is given and specifies a file extension, the original file is preserved
+as ``file.ext''. If option ``-s'' (stealth) is specified,
+the timestamp is preserved on file, too. Option ``-i'' enables
+interactive mode where the user has to approve each operation. Option
+``-n'' (no operation) can be used to disable the actual execution of
+the essential shell commands which would be executed. Option ``-t''
+(trace) can be used to enable the output of the essential shell commands
+which are executed. Option ``-v'' (verbose) can be used to display
+the files which are patched.
+
+This command is a simple operating system and platform architecture guesser
+which determines a so-called ``GNU platform-triple'' style identification
+string ``arch-hardware-ososversion''. For instance a FreeBSD 3.1
+running on a Pentium II is identified as ``i686-pc-freebsd3.1''. When you
+need a more sophisticated platform guesser, use the GNU
+config.guess/config.sub scripts, please.
+
+This is a wrapper around the archive (``ar'') tool. It provides the ability
+to create archives out of existing archives, i.e. if one of file matches
+``*.a'' the archive member files of file are used instead of file
+itself. When option ``-t'' (trace) is given arx shows the actually
+involved shell commands. Option ``-C'' can be used to set the ``ar''
+command to cmd.
+
The trick of this command is the automatic handling of archive members which
+is especially interesting if one wants to construct a (usually top-level)
+library archive out of pre-build sub-library archives (usually staying inside
+subdirs) in a large source tree.
+This command separates the linker options ``-L'' and ``-l'' by library
+class. It's argument line can actually be an arbitrary command line where those
+options are contained. slo parses these two options only and ignores the
+remaining contents. The result is a trivial shell script on stdout which
+defines six variables containing the ``-L'' and ``-l'' options sorted by
+class:
+
``SLO_DIRS_OBJ'' and ``SLO_LIBS_OBJ'' contains the ``-L'' and
+``-l'' options of static libraries, ``SLO_DIRS_PIC'' and
+``SLO_LIBS_PIC'' contains the ``-L'' and ``-l'' options of static
+libraries containing PIC (``Position Independent Code'') and
+``SLO_DIRS_DSO'' and ``SLO_LIBS_DSO'' contains the ``-L'' and
+``-l'' options of shared libraries. The -p option can be used to
+change the default variable prefix from ``SLO_'' to str.
+
The intent of this separation is to provide a way between static and shared
+libraries which is important if one wants to link custom DSOs against
+libraries, because not all platforms all one to link these DSOs against shared
+libraries. So one first has to separate out the shared libraries and link the
+DSO only against the static libraries. One can use this command also to just
+sort the options.
+This command is an additional ANSI C source file pre-processor for sharing
+cpp(1) code segments, internal variables and internal functions. The intention
+for this comes from writing libraries in ANSI C. Here a common shared internal
+header file is usually used for sharing information between the library
+source files.
+
The operation is to parse special constructs in files, generate a few
+things out of these constructs and insert them at position mark in tfile
+by writing the output to ofile. Additionally the files are never touched
+or modified. Instead the constructs are removed later by the cpp(1) phase of
+the build process. The only prerequisite is that every file has a
+``#include "ofile"'' at the top.
+
This command provides the following features: First it avoids namespace
+pollution and reduces prototyping efforts for internal symbols by recognizing
+functions and variables which are defined with the storage class identifier
+``cname''. For instance if cname is ``intern'', a function ``intern
+void *foobar(int quux)'' in one of the files is translated into both a
+``#define foobar __foobar'' and a ``extern void *foobar(int quux);'' in
+ofile. Additionally a global ``#definecname/**/'' is also
+created in ofile to let the compiler silently ignore this additional
+storage class identifier.
+
Second, the library source files usually want to share typedefs,
+#defines, etc. over the source file boundaries. To achieve this one can
+either place this stuff manually into tfile or use the second feature of
+scpp: All code in files encapsulated with ``#if dname ...
+#endif'' is automatically copied to ofile. Additionally a global
+``#definedname0'' is also created in ofile to let the compiler
+silently skip this parts (because it was already found in the header).
+
Option ``-v'' can be used to enable some processing output. Option
+``-p'' can be used to make the decision whether to overwrite ofile
+independent of the generated ``#line'' lines. This is useful for
+Makefiles if the real contents of ofile will not change, just
+line numbers. Option ``-f'' (which can occur multiple times) can
+be used to apply one or more pre-processing sed(1)filter commands
+(usually of type ``s/.../.../'') to each input file before their
+input is parsed.
+This command generates and maintains a version information
+file file for program name name in either textual
+(lang=``txt''), ANSI C (lang=``c''), Perl (lang=``perl'') or
+Python (lang=``python'') language. The version is always described
+with a triple <version,revision,level> and is
+represented by a string which always matches the regular expression
+``[0-9]+\.[0-9]+[sabp.][0-9]+''. When the option ``-s'' is given,
+the contents of file is overridden with the specified version.
+
When option ``-i'' is used, the current version in file is updated
+by increasing one element of the version where knob can be one of
+the following: ``v'' for increasing the version by 1 (and resetting
+revision and level to 0), ``r'' for increasing the revision by 1 (and
+resetting level to 0) or ``l'' for increasing the level by 1. Option
+``-e'' can be used to interactively enter a new version.
+
Unless option ``-e'', ``-i'' or ``-s'' is specified, the performed
+action is to display the current version. Option ``-d'' then can be used
+to control the display type: ``short'' for a short version display, ``long''
+for a longer version display, ``hex'' for a hexadecimal display of the version
+and ``libtool'' for a format suitable for use with GNU libtool.
+
The hexadecimal format for a version v.rtl is VVRRTLL where VV
+and RR directly correspond to v and r, T encodes the level
+type as 9, 2, 1, 0 (representing s, p/., b, a
+in this order) and LL is either directly corresponding to l or set
+to 99 if level type is s.
+
Example:
+
+ # shell script
+ shtool version -l c -n FooBar -p foobar -s 1.2b3 version.c
+
+ # configure.in
+ V=`shtool version -l c -d long version.c`
+ echo "Configuring FooBar, Version $V"
+This command deals with shell $PATH variables. It can find a program
+executable in $PATH or path through one or more filenames (given by one or
+more str arguments). The result is the absolute filesystem path to the
+program displayed on stdout plus an exit code of 0 if it was really
+found.
+
The option ``-s'' can be used to suppress the output which is useful to
+just test whether a program exists with the help of the return code. The
+option ``-m'' enables some magic where currently for the programs
+``perl'' and ``cpp'' an advanced magic search is done. The option
+``-r'' can be used to transform a forward path to a subdirectory into a
+reverse path. Option ``-d'' and ``-b'' just output the directory or base
+name of str.
Some scripts contained in GNU shtool were already written in 1994 by
+Ralf S. Engelschall for use inside some private source trees. Then
+they evolved into more elaborated versions over the years and were used
+in various free software projects like ePerl, WML, iSelect, gFONT, etc.
+They were complemented with other scripts from the author which he wrote
+in March 1998 for the ``Apache Autoconf-style Interface'' (APACI) for
+Apache 1.3. In April 1999 the shtool package was created out of the
+accumulated master versions of the scripts and in June 1999 it entered
+the status of an official GNU program and this way finally joined the
+group of GNU autoconf, GNU automake and GNU libtool.
+Traditional compiler construction tools such as lex and yacc focus on
+the lexical analysis and parsing phases of compilation. But they
+provide very little to support semantic analysis and code generation.
+
+
+
+Yacc allows grammar rules to be tagged with semantic actions and values,
+but it doesn't provide any routines that assist in the process of tree
+building, semantic analysis, or code generation. Because those processes
+are language-specific, yacc leaves the details to the programmer.
+
+
+
+Support for semantic analysis was also a lot simpler in the languages
+that were prevalent when lex and yacc were devised. C and Pascal
+require declare before use, which allows the semantic information
+about a statement to be determined within the parser at the point of
+use.(1) If extensive optimization
+is not required, then code generation can also be performed within
+the grammar, leading to a simple one-pass compiler structure.
+
+
+
+Modern languages allow deferred declaration of methods, fields, and
+types. For example, Java allows a method to refer to a field that
+is declared further down the .java source file. A field can be
+declared with a type whose class definition has not yet been parsed.
+
+
+
+Hence, most of the semantic analysis that used to be performed inline
+within a yacc grammar must now be performed after the entire program
+has been parsed. Tree building and walking is now more important
+than it was in older declare before use languages.
+
+
+
+
+
+Building parse tree data structures and walking them is not terribly
+difficult, but it is extremely time-consuming and error-prone. A
+modern programming language may have hundreds of node types, divided
+into categories for statements, expressions, types, declarations, etc.
+When a new programming language is being devised, new node types may
+be added quite frequently. This has ramifications in trying to manage
+the code's complexity.(2)
+
+
+
+For example, consider nodes that correspond to programming language
+types in a C-like language. There will be node types for integer
+types, floating-point types, pointers, structures, functions, etc.
+There will be semantic analysis routines for testing types for
+equality, comparing types for coercions and casts, evaluating the
+size of a type for memory layout purposes, determining if the type
+falls into a general category such as "integer" or "pointer", etc.
+
+
+
+Let's say we wanted to add a new "128-bit integer" type to this
+language. Adding a new node type is fairly straight-forward.
+But we also need to track down every place in the code where the
+compiler walks a type or deals with integers and add an appropriate
+case for the new type. This is very error-prone. Such code is
+likely to be split over many files, and good coding practices only
+help to a certain extent.
+
+
+
+This problem gets worse when new kinds of expressions and statements
+are added to the language. The change not only affects semantic
+analysis, but also optimization and code generation. Some compilers
+use multiple passes over the tree to perform optimization, with
+different algorithms used in each pass. Code generation may use a
+number of different strategies, depending upon how an expression or
+statement is used. If even one of these places is missed when the
+new node type is added, then there is the potential for a very nasty
+bug that may go unnoticed for months or years.
+
+
+
+Object-oriented languages such as C++ can help a bit in constructing
+robust tree structures. The base class can declare abstract methods
+for any semantic analysis, optimization, or code generation routine
+that needs to be implemented for all members of the node category.
+But another code maintainence problem arises. What happens when
+we want to add a new optimization pass in the future? We must go
+into hundreds of classes and implement the methods.
+
+
+
+To avoid changing hundreds of classes, texts on Design Patterns
+suggest using a Visitor pattern. Then the new optimization pass
+can be encapsulated in a visitor. This would work, except for
+the following drawback of visitor patterns, as described in Gamma,
+et al:
+
+
+
+
+
+The Visitor pattern makes it hard to add new subclasses of
+Element. Each new ConcreteElement gives rise to a new abstract
+operation on Visitor and a corresponding implementation in
+every ConcreteVisitor class.
+
+
+
+... The Visitor class hierarchy can be difficult to maintain
+when new ConcreteElement classes are added frequently. In such
+cases, it's probably easier just to define operations on the
+classes that make up the structure.
+
+
+
+That is, if we add a new node type in the future, we have a large
+maintainence problem on our hands. The solution is to scatter the
+implementation through-out every class, which is the situation we
+were trying to avoid by using the Visitor pattern.
+
+
+
+Because compiler construction deals with a large set of rapidly
+changing node types and operations, neither of the usual approaches
+work very well.
+
+
+
+The ideal programming language for designing compilers needs to have
+some way to detect when the programmer forgets to implement an operation
+for a new node type, and to ensure that a new operation covers all
+existing node types adequately. Existing OO languages do not perform
+this kind of global error checking. What few checking procedures they
+have change the maintainence problem into a different problem of
+similar complexity.
+
+
+
+
+
+A new field in language design has emerged in recent years called
+"Aspect-Oriented Programming" (AOP). A good review of the field
+can be found in the October 2001 issue of the Communications of
+the ACM, and on the AspectJ Web site, http://www.aspectj.org/.
+
+
+
+The following excerpt from the introduction to the AOP section in the
+CACM issue describes the essential aspects of AOP, and the difference
+between OOP and AOP:
+
+
+
+
+
+AOP is based on the idea that computer systems are better programmed
+by separately specifying the various concerns (properties or areas
+of interest) of a system and some description of their relationships,
+and then relying on mechanisms in the underlying AOP environment to
+weave or compose them together into a coherent program. ...
+While the tendancy in OOP's is to find commonality among classes
+and push it up the inheritance tree, AOP attempts to realize
+scattered concerns as first-class elements, and eject them
+horizontally from the object structure.
+
+
+
+Aspect-orientation gives us some hope of solving our compiler
+complexity problems. We can view each operation on node types
+(semantic analysis, optimization, code generation, etc) as an
+"aspect" of the compiler's construction. The AOP language weaves
+these aspects with the node types to create the final compiler.
+
+
+
+
+
+We don't really want to implement a new programming language
+just for compiler construction. Especially since the new language's
+implementation would have all of the problems described above and would
+therefore also be difficult to debug and maintain.
+
+
+
+The approach that we take with "treecc" is similar to that used by
+"yacc". A simple rule-based language is devised that is used to describe
+the intended behaviour declaratively. Embedded code is used to provide
+the specific implementation details. A translator then converts the input
+into source code that can be compiled in the usual fashion.
+
+
+
+The translator is responsible for generating the tree building and
+walking code, and for checking that all relevant operations have been
+implemented on the node types. Functions are provided that make
+it easier to build and walk the tree data structures from within
+a "yacc" grammar and other parts of the compiler.
+
+
+
+
+
+(We will ignore the problems of precedence and associativity and
+assume that the reader is familiar with how to resolve such issues
+in yacc grammars).
+
+
+
+There are 7 types of nodes for this grammar: `intnum', `floatnum',
+`plus', `minus', `multiply', `divide', and `negate'.
+They are defined in treecc as follows:
+
+
+
+
+We have introduced three extra node types that refer
+to any expression, binary expressions, and unary expressions. These
+can be seen as superclasses in an OO-style framework. We have
+declared these node types as `abstract' because the yacc grammar
+will not be permitted to create instances of these classes directly.
+
+
+
+The `binary', `unary', `intnum', and `floatnum'
+node types have field definitions associated with them. These have
+a similar syntax to C struct declarations.
+
+
+
+The yacc grammar is augmented as follows to build the parse tree:
+
+
+
+
+The treecc translator generates the `*_create' functions so that
+the rest of the compiler can build the necessary data structures
+on demand. The parameters to the `*_create' functions
+are identical in type and order to the members of the structure for
+that node type.
+
+
+
+Because `expression', `binary', and `unary' are abstract,
+there will be no `*_create' functions associated with them. This will
+help the programmer catch certain kinds of errors.
+
+
+
+The type that is returned from a `*_create' function is the first
+superclass of the node that has a `%typedef' keyword associated with it;
+`expression *' in this case.
+
+
+
+
+
+Normally we will want to store extra information with a node beyond
+that which is extracted by the yacc grammar. In our expression
+example, we probably want to store type information in the nodes
+so that we can determine if the whole expression is integer or
+floating point during semantic analysis. We can add type information
+to the `expression' node type as follows:
+
+
+
+
+The `%nocreate' flag indicates that the field should not be passed
+to the `*_create' functions as a parameter. i.e. it provides semantic
+information that isn't present in the grammar. When nodes are created,
+any fields that are declared as `%nocreate' will be undefined in value.
+A default value can be specified as follows:
+
+
+
+
+Default values must be enclosed in `{' and `}' because they are
+pieces of code in the underlying source language (C, C++, etc), instead
+of tokens in the treecc syntax. Any legitimate expression in the
+underlying source language may be used.
+
+
+
+We also need to arrange for `type_code' to be declared. One way to
+do this is by adding a `%decls' section to the front of the treecc
+input file:
+
+
+
+
+We could have introduced the definition by placing a `#include'
+directive into the `%decls' section instead, or by defining a
+treecc enumerated type:
+
+
+
+
+This example demonstrates using the abstract node types `binary' and
+`unary' to define operations on all subclasses. The treecc translator
+will generate code for a full C function called `infer_type' that
+incorporates all of the cases.
+
+
+
+But hang on a second! What happened to `floatnum'? Where did it
+go? It turns out that treecc will catch this. It will report
+an error to the effect that `node type `floatnum' is not handled in
+operation `infer_type''. Here is its definition:
+
+
+
+
+That's all there is to it! When treecc re-translates the input
+file, it will modify the definition of `infer_type' to include the
+extra case for `power' nodes. Because `power' is a subclass of
+`binary', treecc already knows how to perform type inferencing for the
+new node and it doesn't warn us about a missing declaration.
+
+
+
+What if we wanted to restrict the second argument of `power' to be
+an integer value? We can add the following case to `infer_type':
+
+
+
+
+infer_type(power)
+{
+ infer_type(e->expr1);
+ infer_type(e->expr2);
+
+ if(e->expr2->type != int_type)
+ {
+ error("second argument to `^' is not an integer");
+ }
+
+ e->type = e->expr1->type;
+}
+
+
+
+The translator now notices that there is a more specific implementation
+of `infer_type' for `power', and won't use the `binary'
+case for it.
+
+
+
+The most important thing to realise here is that the translator always
+checks that there are sufficient declarations for `infer_type' to cover
+all relevant node types. If it detects a lack, it will immediately
+raise an error to the user. This allows tree coverage problems to
+be found a lot sooner than with the traditional approach.
+
+
+
+The general form of treecc's command-line syntax is as follows:
+
+
+
+
+treecc [OPTIONS] INPUT ...
+
+
+
+Treecc accepts the following command-line options:
+
+
+
+
+
-o FILE
+
+
--output FILE
+
+Set the name of the output file to `FILE'. If this option is not
+supplied, then the name of the first input file will be used, with its
+extension changed to `.c'. If the input is standard input,
+the default output file is `yy_tree.c'.
+
+This option may be overridden using the `%output' keyword in
+the input files.
+
+
-h FILE
+
+
--header FILE
+
+Set the name of the header output file to `FILE'. This is only
+used for the C and C++ output languages. If this option is not supplied,
+then the name of the output file will be used, with its extension
+changed to `.h'. If the input is standard input, the default header
+output file is `yy_tree.h'.
+
+This option may be overriden using the `%header' keyword in the
+input files. If this option is used with a language that does not require
+headers, it will be ignored.
+
+
-d DIR
+
+
--output-dir DIR
+
+Set the name of the Java output directory to `DIR'. This is only
+used for the Java language. If this option is not supplied, then the
+directory corresponding to the first input file is used. If the input
+is standard input, the default is the current directory.
+
+This option may be overriden using the `%outdir' keyword in the
+input files. If this option is used with a language other than Java,
+it will be ignored.
+
+
-s DIR
+
+
--skeleton-dir DIR
+
+Set the name of the directory that contains the skeleton files for the
+C and C++ node memory managers to `DIR'.
+
+
-e EXT
+
+
--extension EXT
+
+Change the default output file extension to `ext', instead of
+`.c'. The value `ext' can have a leading dot, but this is
+not required.
+
+
-f
+
+
--force-create
+
+Treecc normally attempts to optimise the creation of output files
+so that they are only modified if a non-trivial change has
+occurred in the input. This can reduce the number of source
+code recompiles when treecc is used in combination with make.
+
+This option forces the output files to be created, even if they
+are the same as existing files with the same name.
+
+The declaration `%option force' can be used in the input files
+to achieve the same effect as this option.
+
+
-n
+
+
--no-output
+
+Suppress the generation of output files. Treecc parses the
+input files, checks for errors, and then stops.
+
+
--help
+
+Print a usage message for the treecc program.
+
+
-v
+
+
--version
+
+Print the version of the treecc program.
+
+
--
+
+Marks the end of the command-line options, and the beginning of
+the input filenames. You may need to use this if your filename
+begins with `-'. e.g. `treecc -- -input.tc'. This is
+not needed if the input is standard input: `treecc -'
+is perfectly valid.
+
+Treecc input files consist of zero or more declarations that define
+nodes, operations, options, etc. The following sections describe each
+of these elements.
+
+
+
+
+
+Node types are defined using the `node' keyword in input files.
+The general form of the declaration is:
+
+
+
+
+%node NAME [ PNAME ] [ FLAGS ] [ = FIELDS ]
+
+
+
+
+
`NAME'
+
+An identifier that is used to refer to the node type elsewhere
+in the treecc definition. It is also the name of the type that will be
+visible to the programmer in literal code blocks.
+
+
`PNAME'
+
+An identifier that refers to the parent node type that `NAME' inherits
+from. If `PNAME' is not supplied, then `NAME' is a top-level
+declaration. It is legal to supply a `PNAME' that has not yet
+been defined in the input.
+
+
`FLAGS'
+
+Any combination of `%abstract' and `%typedef':
+
+
+
+
`%abstract'
+
+
+The node type cannot be constructed by the programmer. In addition,
+the programmer does not need to define operation cases for this node
+type if all subtypes have cases associated with them.
+
+
`%typedef'
+
+
+The node type is used as the common return type for node creation
+functions. Top-level declarations must have a `%typedef' keyword.
+
+
+
+
+The `FIELDS' part of a node declaration defines the fields that
+make up the node type. Each field has the following general form:
+
+
+
+
+[ %nocreate ] TYPE FNAME [ = VALUE ] ';'
+
+
+
+
+
`%nocreate'
+
+
+The field is not used in the node's constructor. When the node is
+constructed, the value of this field will be undefined unless
+`VALUE' is specified.
+
+
`TYPE'
+
+The type that is associated with the field. Types can be declared
+using a subset of the C declaration syntax, augmented with some C++
+and Java features. See section Types used in fields and parameters, for more information.
+
+
`FNAME'
+
+The name to associate with the field. Treecc verifies that the field
+does not currently exist in this node type, or in any of its ancestor
+node types.
+
+
`VALUE'
+
+The default value to assign to the field in the node's constructor.
+This can only be used on fields that are declared with `%nocreate'.
+The value must be enclosed in braces. For example `{NULL}' would
+be used to initialize a field with `NULL'.
+
+The braces are required because the default value is expressed in
+the underlying source language, and can use any of the usual constant
+declaration features present in that language.
+
+
+
+When the output language is C, treecc creates a struct-based type
+called `NAME' that contains the fields for `NAME' and
+all of its ancestor classes. The type also contains some house-keeping
+fields that are used internally by the generated code. The following
+is an example:
+
+
+
+
+The programmer should avoid using any identifier that
+ends with `__', because it may clash with house-keeping
+identifiers that are generated by treecc.
+
+
+
+When the output language is C++, Java, or C#, treecc creates a class
+called `NAME', that inherits from the class `PNAME'.
+The field definitions for `NAME' are converted into public members
+in the output.
+
+
+
+
+
+Types that are used in field and parameter declarations have a
+syntax which is subset of features found in C, C++, and Java:
+
+
+
+
+TypeAndName ::= Type [ IDENTIFIER ]
+
+Type ::= TypeName
+ | Type '*'
+ | Type '&'
+ | Type '[' ']'
+
+TypeName ::= IDENTIFIER { IDENTIFIER }
+
+
+
+Types are usually followed by an identifier that names the field or
+parameter. The name is required for fields and is optional for parameters.
+For example `int' is usually equivalent to `int x' in parameter
+declarations.
+
+
+
+The following are some examples of using types:
+
+
+
+
+int
+int x
+const char *str
+expression *expr
+Element[][] array
+Item&
+unsigned int y
+const Element
+
+
+
+The grammar used by treecc is slightly ambiguous. The last example above
+declares a parameter called `Element', that has type `const'.
+The programmer probably intended to declare an anonymous parameter with type
+`const Element' instead.
+
+
+
+This ambiguity is unavoidable given that treecc is not fully
+aware of the underlying language's type system. When treecc
+sees a type that ends in a sequence of identifiers, it will
+always interpret the last identifier as the field or parameter
+name. Thus, the programmer must write the following instead:
+
+
+
+
+const Element e
+
+
+
+Treecc cannot declare types using the full power of C's type system.
+The most common forms of declarations are supported, and the rest
+can usually be obtained by defining a `typedef' within a
+literal code block. See section Literal code declarations, for more information
+on literal code blocks.
+
+
+
+It is the responsibility of the programmer to use type constructs
+that are supported by the underlying programming language. Types such
+as `const char *' will give an error when the output is compiled
+with a Java compiler, for example.
+
+
+
+
+
+Enumerated types are a special kind of node type that can be used
+by the programmer for simple values that don't require a full abstract
+syntax tree node. The following is an example of defining a list
+of the primitive machine types used in a Java virtual machine:
+
+
+
+
+Enumerations are useful when writing code generators and type
+inferencing routines. The general form is:
+
+
+
+
+%enum NAME = { VALUES }
+
+
+
+
+
`NAME'
+
+An identifier to be used to name the enumerated type. The name must
+not have been previously used as a node type, an enumerated type, or
+an enumerated value.
+
+
`VALUES'
+
+A comma-separated list of identifiers that name the values within
+the enumeration. Each of the names must be unique, and must not have
+been used previously as a node type, an enumerated type, or an
+enumerated value.
+
+
+
+Logically, each enumerated value is a special node type that inherits from
+a parent node type corresponding to the enumerated type `NAME'.
+
+
+
+When the output language is C or C++, treecc generates an enumerated
+typedef for `NAME' that contains the enumerated values in the
+same order as was used in the input file. The typedef name can be
+used elsewhere in the code as the type of the enumeration.
+
+
+
+When the output language is Java, treecc generates a class called
+`NAME' that contains the enumerated values as integer constants.
+Elsewhere in the code, the type `int' must be used to declare
+variables of the enumerated type. Enumerated values are referred
+to as `NAME.VALUE'. If the enumerated type is used as a trigger
+parameter, then `NAME' must be used instead of `int':
+treecc will convert the type when the Java code is output.
+
+
+
+When the output language is C#, treecc generates an enumerated value
+type called `NAME' that contains the enumerated values as
+members. The C# type `NAME' can be used elsewhere in the code
+as the type of the enumeration. Enumerated values are referred to
+as `NAME.VALUE'.
+
+
+
+
+
+Operations are declared in two parts: the declaration, and the
+cases. The declaration part defines the prototype for the
+operation and the cases define how to handle specific kinds of
+nodes for the operation.
+
+
+
+Operations are defined over one or more trigger parameters. Each
+trigger parameter specifies a node type or an enumerated type that
+is selected upon to determine what course of action to take. The
+following are some examples of operation declarations:
+
+
+
+
+Trigger parameters are specified by enclosing them in square
+brackets. If none of the parameters are enclosed in square
+brackets, then treecc assumes that the first parameter is the
+trigger.
+
+
+
+The general form of an operation declaration is as follows:
+
+
+
+
+
+Specifies that the operation is associated with a node type as
+a virtual method. There must be only one trigger parameter,
+and it must be the first parameter.
+
+Non-virtual operations are written to the output source files
+as global functions.
+
+
`%inline'
+
+
+Optimise the generation of the operation code so that all cases
+are inline within the code for the function itself. This can
+only be used with non-virtual operations, and may improve
+code efficiency if there are lots of operation cases with a
+small amount of code in each.
+
+
`%split'
+
+
+Split the generation of the multi-trigger operation code across
+multiple functions, to reduce the size of each individual function.
+It is sometimes necessary to split large %inline operations
+to avoid compiler limits on function size.
+
+
`RTYPE'
+
+The type of the return value for the operation. This should be
+`void' if the operation does not have a return value.
+
+
`CLASS'
+
+The name of the class to place the operation's definition within.
+This can only be used with non-virtual operations, and is
+intended for languages such as Java and C# that cannot declare
+methods outside of classes. The class name will be ignored if
+the output language is C.
+
+If a class name is required, but the programmer did not supply it,
+then `NAME' will be used as the default. The exception to
+this is the C# language: `CLASS' must always be supplied and
+it must be different from `NAME'. This is due to a "feature"
+in some C# compilers that forbid a method with the same name as
+its enclosing class.
+
+
`NAME'
+
+The name of the operation.
+
+
`PARAMS'
+
+The parameters to the operation. Trigger parameters may be
+enclosed in square brackets. Trigger parameters must be
+either node types or enumerated types.
+
+
+
+Once an operation has been declared, the programmer can specify
+its cases anywhere in the input files. It is not necessary that
+the cases appear after the operation, or that they be contiguous
+within the input files. This permits the programmer to place
+operation cases where they are logically required for maintainence
+reasons.
+
+
+
+There must be sufficient operation cases defined to cover every
+possible combination of node types and enumerated values that
+inherit from the specified trigger types. An operation case
+has the following general form:
+
+
+
+
+"(*)" is used below to indicate an option that is enabled by default.
+
+
+
+
+
`%option track_lines'
+
+
+Enable the generation of code that can track the current filename and
+line number when nodes are created. See section Tracking line numbers in source files, for more
+information. (*)
+
+
`%option no_track_lines'
+
+
+Disable the generation of code that performs line number tracking.
+
+
`%option singletons'
+
+
+Optimise the creation of singleton node types. These are
+node types without any fields. Treecc can optimise the code
+so that only one instance of a singleton node type exists in
+the system. This can speed up the creation of nodes for
+constants within compilers. (*)
+
+Singleton optimisations will have no effect if `track_lines'
+is enabled, because line tracking uses special hidden fields in
+every node.
+
+
`%option no_singletons'
+
+
+Disable the optimisation of singleton node types.
+
+
`%option reentrant'
+
+
+Enable the generation of reentrant code that does not rely
+upon any global variables. Separate copies of the compiler
+state can be used safely in separate threads. However, the
+same copy of the compiler state cannot be used safely in two or
+more threads.
+
+
`%option no_reentrant'
+
+
+Disable the generation of reentrant code. The interface to
+node management functions is simpler, but cannot be used
+in a threaded environment. (*)
+
+
`%option force'
+
+
+Force output source files to be written, even if they are
+unchanged. This option can also be set using the `-f'
+command-line option.
+
+
`%option no_force'
+
+
+Don't force output source files to be written if they are the
+same as before. (*)
+
+This option can help smooth integration of treecc with make.
+Only those output files that have changed will be modified.
+This reduces the number of files that the underlying source
+language compiler must process after treecc is executed.
+
+
`%option virtual_factory'
+
+
+Use virtual methods in the node type factories, so that the
+programmer can subclass the factory and provide new
+implementations of node creation functions. This option is
+ignored for C, which does not use factories.
+
+
`%option no_virtual_factory'
+
+
+Don't use virtual methods in the node type factories. (*)
+
+
`%option abstract_factory'
+
+
+Use abstract virtual methods in the node type factories.
+The programmer is responsible for subclassing the factory
+to provide node creation functionality.
+
+
`%option no_abstract_factory'
+
+
+Don't use abstract virtual methods in the node type factories. (*)
+
+
`%option kind_in_node'
+
+
+Put the kind field in the node, for more efficient access at runtime. (*)
+
+
`%option kind_in_vtable'
+
+
+Put the kind field in the vtable, and not the node. This saves some
+memory, at the cost of slower access to the kind value at runtime.
+This option only applies when the language is C. The kind field is
+always placed in the node in other languages, because it isn't possible
+to modify the vtable.
+
+
`%option prefix = PREFIX'
+
+
+Specify the prefix to be used in output files in place of "yy".
+
+
`%option state_type = NAME'
+
+
+Specify the name of the state type. The state type is generated
+by treecc to perform centralised memory management and reentrancy
+support. The default value is `YYNODESTATE'. If the output language
+uses factories, then this will also be the name of the factory
+base class.
+
+
`%option namespace = NAME'
+
+
+Specify the namespace to write definitions to in the output
+source files. This option is ignored when the output language
+is C.
+
+
`%option package = NAME'
+
+
+Same as `%option namespace = NAME'. Provided because `package'
+is more natural for Java programmers.
+
+
`%option base = NUM'
+
+
+Specify the numeric base to use for allocating numeric values to
+node types. By default, node type allocation begins at 1.
+
+
`%option lang = LANGUAGE'
+
+
+Specify the output language. Must be one of "C", "C++",
+"Java", or "C#". The default is "C".
+
+
`%option block_size = NUM'
+
+
+Specify the size of the memory blocks to use in C and C++ node allocators.
+
+
`%option strip_filenames'
+
+
+Strip filenames down to their base name in #line directives.
+i.e. strip off the directory component. This can be helpful in
+combination with the %include %readonly command when
+treecc input files may processed from different directories,
+causing common output files to change unexpectedly.
+
+
`%option no_strip_filenames'
+
+
+Don't strip filenames in #line directives. (*)
+
+Sometimes it is necessary to embed literal code within output `.h'
+and source files. Usually this is to `#include' definitions
+from other files, or to define functions that cannot be easily expressed
+as operations.
+
+
+
+A literal code block is specified by enclosing it in `%{' and
+`%}'. The block can also be prefixed with the following flags:
+
+
+
+
+
`%decls'
+
+
+Write the literal code to the currently active declaration header file,
+instead of the source file.
+
+
`%both'
+
+
+Write the literal code to both the currently active declaration header file
+and the currently active source file.
+
+
`%end'
+
+
+Write the literal code to the end of the file, instead of the beginning.
+
+
+
+Another form of literal code block is one which begins with `%%' and
+extends to the end of the current input file. This form implicitly has
+the `%end' flag.
+
+
+
+
+
+Most treecc compiler definitions will be too large to be manageable
+in a single input file. They also will be too large to write to a
+single output file, because that may overload the source language
+compiler.
+
+
+
+Multiple input files can be specified on the command-line, or
+they can be explicitly included by other input files with
+the following declarations:
+
+
+
+
+
`%include [ %readonly ] FILENAME'
+
+
+
+
+Include the contents of the specified file at the current point
+within the current input file. `FILENAME' is interpreted
+relative to the name of the current input file.
+
+If the `%readonly' keyword is supplied, then any output
+files that are generated by the included file must be read-only.
+That is, no changes are expected by performing the inclusion.
+
+The `%readonly' keyword is useful for building compilers
+in layers. The programmer may group a large number of useful
+node types and operations together that are independent of the
+particulars of a given language. The programmer then defines
+language-specific compilers that "inherit" the common definitions.
+
+Read-only inclusions ensure that any extensions that are added
+by the language-specific parts do not "leak" into the common code.
+
+
+
+Output files can be changed using the follow declarations:
+
+
+
+
+
`%header FILENAME'
+
+
+
+Change the currently active declaration header file to `FILENAME',
+which is interpreted relative to the current input file. This option
+has no effect for languages without header files (Java and C#).
+
+Any node types and operations that are defined after a `%header'
+declaration will be declared in `FILENAME'.
+
+
`%output FILENAME'
+
+
+
+Change the currently active source file to `FILENAME',
+which is interpreted relative to the current input file. This option
+has no effect for languages that require a single class per file (Java).
+
+Any node types and operations that are defined after a `%header'
+declaration will have their implementations placed in `FILENAME'.
+
+
`%outdir DIRNAME'
+
+
+
+Change the output source directory to `DIRNAME'. This is only
+used for Java, which requires that a single file be used for each class.
+All classes are written to the specified directory. By default,
+`DIRNAME' is the current directory where treecc was invoked.
+
+
+
+When treecc generates the output source code, it must insert several
+common house-keeping functions and classes into the code. By default,
+these are written to the first header and source files. This can
+be changed with the `%common' declaration:
+
+
+
+
+
`%common'
+
+
+
+Output the common house-keeping code to the currently active
+declaration header file and the currently active source file.
+This is typically used as follows:
+
+
+
+When compilers emit error messages to the programmer, it is generally
+a good idea to indicate which file and which line gave rise to the
+error. Syntax errors can be emitted fairly easily because the parser
+usually has access to the current line number. However, semantic
+errors are harder to report because the parser may no longer be
+active when the error is detected.
+
+
+
+Treecc can generate code that automatically keeps track of what line
+in the source file was active when a node is created. Every node
+has two extra private fields that specify the name of the file and the
+line number. Semantic analysis routines can query this information
+when reporting errors.
+
+
+
+Because treecc is not aware of how to obtain this information, the
+programmer must supply some additional functions. See section API's available in the generated output,
+for more information.
+
+
+
+The source code that is generated by treecc exports a number of
+application programmer interfaces (API's) to the programmer. These
+can be used elsewhere in the compiler implementation to manipulate
+abstract syntax trees. The following sections describe the API's
+for each of the output languages.
+
+
+
+
+
+In the C output language, each node type is converted into a `typedef'
+that contains the node's fields, and the fields of its ancestor node
+types. The following example demonstrates how treecc node declarations
+are converted into C source code:
+
+
+
+
+Programmers should avoid using any identifiers that end in
+`__'. Such identifiers are reserved for internal use by treecc
+and its support routines.
+
+
+
+For each non-abstract node type called `NAME', treecc generates a
+function called `NAME_create' that creates nodes of that type.
+The general form of the function's prototype is as follows:
+
+
+
+
+The return node type, which is the nearest ancestor that has the
+`%typedef' flag.
+
+
`NAME'
+
+The name of the node type that is being created.
+
+
`state'
+
+The system state, if reentrant code is being generated.
+
+
`PARAMS'
+
+The create parameters, consisting of every field that does not
+have the `%nocreate' flag. The parameters appear in the
+same order as the fields in the node types, from the top-most
+ancestor down to the node type itself. For example:
+
+
+
+Calls to `infer_type' can then be made with `infer_type(node)'.
+
+
+
+Non-virtual operations are converted into C functions:
+
+
+
+
+%operation void infer_type(expression *e)
+
+
+
+becomes:
+
+
+
+
+extern void infer_type(expression *e);
+
+
+
+Because virtual and non-virtual operations use a similar call syntax,
+it is very easy to convert a virtual operation into a non-virtual
+operation when the output language is C. This isn't possible with
+the other output languages.
+
+
+
+Other house-keeping tasks are performed by the following functions
+and macros. Some of these must be supplied by the programmer.
+The `state' parameter is required only if a reentrant compiler is
+being built.
+
+
+
+
+
int yykind(ANY *node)
+
+
+Gets the numeric kind value associated with a particular node.
+The kind value for node type `NAME' is called `NAME_kind'.
+
+
const char *yykindname(ANY *node)
+
+
+Gets the name of the node kind associated with a particular node.
+This may be helpful for debugging and logging code.
+
+
int yyisa(ANY *node, type)
+
+
+Determines if `node' is an instance of the node type `type'.
+
+
char *yygetfilename(ANY *node)
+
+
+Gets the filename corresponding to where `node' was created
+during parsing. This macro is only generated if `%option track_lines'
+was specified.
+
+
long yygetlinenum(ANY *node)
+
+
+Gets the line number corresponding to where `node' was created
+during parsing. This macro is only generated if `%option track_lines'
+was specified.
+
+
void yysetfilename(ANY *node, char *value)
+
+
+Sets the filename associated with `node' to `value'. The
+string is not copied, so `value' must persist for the lifetime
+of the node. This macro will rarely be required, unless a node
+corresponds to a different line than the current parse line. This
+macro is only generated if `%option track_lines' was specified.
+
+
void yysetlinenum(ANY *node, long value)
+
+
+Sets the line number associated with `node' to `value'.
+This macro will rarely be required, unless a node corresponds to a
+different line than the current parse line. This macro is only
+generated if `%option track_lines' was specified.
+
+
char *yycurrfilename([YYNODESTATE *state])
+
+
+Get the name of the current input file from the parser. The pointer
+that is returned from this function is stored as-is: the string is
+not copied. Therefore, the value must persist for at least as long
+as the node will persist. This function must be supplied by the programmer
+if `%option track_lines' was specified.
+
+
long yycurrlinenum([YYNODESTATE *state])
+
+
+Get the number of the current input line from the parser. This
+function must be supplied by the programmer if `%option track_lines'
+was specified.
+
+
void yynodeinit([YYNODESTATE *state])
+
+
+Initializes the node memory manager. If the system is reentrant, then
+the node memory manager is `state'. Otherwise a global node
+memory manager is used.
+
+
void *yynodealloc([YYNODESTATE *state,] unsigned int size)
+
+
+Allocates a block of memory of `size' bytes in size from the
+node memory manager. This function is called automatically from
+the node-specific `*_create' functions. The programmer will
+not normally need to call this function.
+
+This function will return NULL if the system is out of
+memory, or if `size' is too large to be allocated within
+the node memory manager. If the system is out of memory, then
+`yynodealloc' will call `yynodefailed' prior to
+returning NULL.
+
+
int yynodepush([YYNODESTATE *state])
+
+
+Pushes the current node memory manager position. The next time
+yynodepop is called, the node memory manager will reset to
+the pushed position. This function returns zero if the system
+is out of memory.
+
+
void yynodepop([YYNODESTATE *state])
+
+
+Pops the current node memory manager position. This function has
+no effect if yynodepush was not called previously.
+
+The yynodepush and yynodepop functions can be used
+to perform a simple kind of garbage collection on nodes. When
+the parser enters a scope, it pushes the node memory manager
+position. After all definitions in the scope have been dealt
+with, the parser pops the node memory manager to reclaim all
+of the memory used.
+
+
void yynodeclear([YYNODESTATE *state])
+
+
+Clears the entire node memory manager and returns it to the
+state it had after calling yynodeinit. This is typically
+used upon program shutdown to free all remaining node memory.
+
+
void yynodefailed([YYNODESTATE *state])
+
+
+Called when yynodealloc or yynodepush detects that
+the system is out of memory. This function must be supplied by
+the programmer. The programmer may choose to exit to program
+when the system is out of memory; in which case yynodealloc
+will never return NULL.
+
+In the C++ output language, each node type is converted into a `class'
+that contains the node's fields, virtual operations, and other house-keeping
+definitions. The following example demonstrates how treecc node declarations
+are converted into C++ source code:
+
+
+
+
+The following standard methods are available on every node type:
+
+
+
+
+
int getKind()
+
+
+Gets the numeric kind value associated with a particular node.
+The kind value for node type `NAME' is called `NAME_kind'.
+
+
virtual const char *getKindName()
+
+
+Gets the name of the node kind associated with a particular node.
+This may be helpful for debugging and logging code.
+
+
virtual int isA(int kind)
+
+
+Determines if the node is a member of the node type that corresponds
+to the numeric kind value `kind'.
+
+
const char *getFilename()
+
+
+Gets the filename corresponding to where the node was created
+during parsing. This method is only generated if `%option track_lines'
+was specified.
+
+
long getLinenum()
+
+
+Gets the line number corresponding to where the node was created
+during parsing. This method is only generated if `%option track_lines'
+was specified.
+
+
void setFilename(char *value)
+
+
+Sets the filename associated with the node to `value'. The
+string is not copied, so `value' must persist for the lifetime
+of the node. This method will rarely be required, unless a node
+corresponds to a different line than the current parse line. This
+method is only generated if `%option track_lines' was specified.
+
+
void setLinenum(long value)
+
+
+Sets the line number associated with the node to `value'.
+This method will rarely be required, unless a node corresponds to a
+different line than the current parse line. This method is only
+generated if `%option track_lines' was specified.
+
+
+
+If the generated code is non-reentrant, then the constructor for the
+class can be used to construct nodes of the specified node type. The
+constructor parameters are the same as the fields within the node type's
+definition, except for `%nocreate' fields.
+
+
+
+If the generated code is reentrant, then nodes cannot be constructed
+using the C++ `new' operator. The `*Create' methods
+on the `YYNODESTATE' factory class must be used instead.
+
+
+
+The `YYNODESTATE' class contains a number of house-keeping methods
+that are used to manage nodes:
+
+
+
+
+
static YYNODESTATE *getState()
+
+
+Gets the global `YYNODESTATE' instance that is being used by
+non-reentrant code. If an instance has not yet been created,
+this method will create one.
+
+When using non-reentrant code, the programmer will normally subclass
+`YYNODESTATE', override some of the methods below, and then
+construct an instance of the subclass. This constructed instance
+will then be returned by future calls to `getState'.
+
+
void *alloc(size_t size)
+
+
+Allocates a block of memory of `size' bytes in size from the
+node memory manager. This function is called automatically from
+the node-specific constructors and `*Create' methods. The programmer
+will not normally need to call this function.
+
+This function will return NULL if the system is out of
+memory, or if `size' is too large to be allocated within
+the node memory manager. If the system is out of memory, then
+`alloc' will call `failed' prior to returning NULL.
+
+
int push()
+
+
+Pushes the current node memory manager position. The next time
+pop is called, the node memory manager will reset to
+the pushed position. This function returns zero if the system
+is out of memory.
+
+
void pop()
+
+
+Pops the current node memory manager position. This function has
+no effect if push was not called previously.
+
+The push and pop methods can be used
+to perform a simple kind of garbage collection on nodes. When
+the parser enters a scope, it pushes the node memory manager
+position. After all definitions in the scope have been dealt
+with, the parser pops the node memory manager to reclaim all
+of the memory used.
+
+
void clear()
+
+
+Clears the entire node memory manager and returns it to the
+state it had after construction.
+
+
virtual void failed()
+
+
+Called when alloc or push detects that
+the system is out of memory. This method is typically
+overridden by the programmer in subclasses. The programmer may
+choose to exit to program when the system is out of memory; in
+which case alloc will never return NULL.
+
+
virtual char *currFilename()
+
+
+Get the name of the current input file from the parser. The pointer
+that is returned from this function is stored as-is: the string is
+not copied. Therefore, the value must persist for at least as long
+as the node will persist. This method is usually overrriden by
+the programmer in subclasses if `%option track_lines' was specified.
+
+
virtual long currLinenum()
+
+
+Get the number of the current input line from the parser. This
+method is usually overridden by the programmer in subclasses
+if `%option track_lines' was specified.
+
+
+
+The programmer will typically subclass `YYNODESTATE' to provide
+additional functionality, and then create an instance of this class
+to act as the node memory manager and node creation factory.
+
+
+
+
+
+In the Java output language, each node type is converted into a `class'
+that contains the node's fields, virtual operations, and other house-keeping
+definitions. The following example demonstrates how treecc node declarations
+are converted into Java source code:
+
+
+
+
+public class expression
+{
+ protected int kind__;
+ protected String filename__;
+ protected long linenum__;
+
+ public int getKind() { return kind__; }
+ public String getFilename() { return filename__; }
+ public long getLinenum() const { return linenum__; }
+ public void setFilename(String filename) { filename__ = filename; }
+ public void setLinenum(long linenum) { linenum__ = linenum; }
+
+ public static final int KIND = 1;
+
+ public type_code type;
+
+ protected expression()
+ {
+ this.kind__ = KIND;
+ this.filename__ = YYNODESTATE.getState().currFilename();
+ this.linenum__ = YYNODESTATE.getState().currLinenum();
+ }
+
+ public int isA(int kind)
+ {
+ if(kind == KIND)
+ return 1;
+ else
+ return 0;
+ }
+
+ public String getKindName()
+ {
+ return "expression";
+ }
+}
+
+public class binary extends expression
+{
+ public static final int KIND = 2;
+
+ public expression expr1;
+ public expression expr2;
+
+ protected binary(expression expr1, expression expr2)
+ {
+ super();
+ this.kind__ = KIND;
+ this.expr1 = expr1;
+ this.expr2 = expr2;
+ }
+
+ public int isA(int kind)
+ {
+ if(kind == KIND)
+ return 1;
+ else
+ return super.isA(kind);
+ }
+
+ public String getKindName()
+ {
+ return "binary";
+ }
+}
+
+public class plus extends binary
+{
+ public static final int KIND = 3;
+
+ public plus(expression expr1, expression expr2)
+ {
+ super(expr1, expr2);
+ this.kind__ = KIND;
+ }
+
+ public int isA(int kind)
+ {
+ if(kind == KIND)
+ return 1;
+ else
+ return super.isA(kind);
+ }
+
+ public String getKindName()
+ {
+ return "plus";
+ }
+}
+
+
+
+The following standard members are available on every node type:
+
+
+
+
+
int KIND
+
+
+The kind value for the node type corresponding to this class.
+
+
int getKind()
+
+
+Gets the numeric kind value associated with a particular node.
+The kind value for node type `NAME' is called `NAME.KIND'.
+
+
String getKindName()
+
+
+Gets the name of the node kind associated with a particular node.
+This may be helpful for debugging and logging code.
+
+
int isA(int kind)
+
+
+Determines if the node is a member of the node type that corresponds
+to the numeric kind value `kind'.
+
+
String getFilename()
+
+
+Gets the filename corresponding to where the node was created
+during parsing. This method is only generated if `%option track_lines'
+was specified.
+
+
long getLinenum()
+
+
+Gets the line number corresponding to where the node was created
+during parsing. This method is only generated if `%option track_lines'
+was specified.
+
+
void setFilename(String value)
+
+
+Sets the filename associated with the node to `value'.
+This method will rarely be required, unless a node corresponds to
+a different line than the current parse line. This method is only
+generated if `%option track_lines' was specified.
+
+
void setLinenum(long value)
+
+
+Sets the line number associated with the node to `value'.
+This method will rarely be required, unless a node corresponds to a
+different line than the current parse line. This method is only
+generated if `%option track_lines' was specified.
+
+
+
+If the generated code is non-reentrant, then the constructor for the
+class can be used to construct nodes of the specified node type. The
+constructor parameters are the same as the fields within the node type's
+definition, except for `%nocreate' fields.
+
+
+
+If the generated code is reentrant, then nodes cannot be constructed
+using the Java `new' operator. The `*Create' methods
+on the `YYNODESTATE' factory class must be used instead.
+
+
+
+Enumerated types are converted into a Java `class':
+
+
+
+
+public class JavaType
+{
+ public static final int JT_BYTE = 0;
+ public static final int JT_SHORT = 1;
+ public static final int JT_CHAR = 2;
+ public static final int JT_INT = 3;
+ public static final int JT_LONG = 4;
+ public static final int JT_FLOAT = 5;
+ public static final int JT_DOUBLE = 6;
+ public static final int JT_OBJECT_REF = 7;
+}
+
+
+
+References to enumerated types in fields and operation parameters
+are replaced with the type `int'.
+
+
+
+Virtual operations are converted into public methods on the Java
+node classes.
+
+
+
+Non-virtual operations are converted into a static method within
+a class named for the operation. For example,
+
+
+
+
+public class InferType
+{
+ public static void infer_type(expression e)
+ {
+ ...
+ }
+}
+
+
+
+If the class name (`InferType' in the above example) is omitted,
+then the name of the operation is used as both the class name and the
+the method name.
+
+
+
+The `YYNODESTATE' class contains a number of house-keeping methods
+that are used to manage nodes:
+
+
+
+
+
static YYNODESTATE getState()
+
+
+Gets the global `YYNODESTATE' instance that is being used by
+non-reentrant code. If an instance has not yet been created,
+this method will create one.
+
+When using non-reentrant code, the programmer will normally subclass
+`YYNODESTATE', override some of the methods below, and then
+construct an instance of the subclass. This constructed instance
+will then be returned by future calls to `getState'.
+
+This method will not be present if a reentrant system is being
+generated.
+
+
String currFilename()
+
+
+Get the name of the current input file from the parser. This method
+is usually overrriden by the programmer in subclasses if
+`%option track_lines' was specified.
+
+
long currLinenum()
+
+
+Get the number of the current input line from the parser. This
+method is usually overridden by the programmer in subclasses
+if `%option track_lines' was specified.
+
+
+
+The programmer will typically subclass `YYNODESTATE' to provide
+additional functionality, and then create an instance of this class
+to act as the global state and node creation factory.
+
+
+
+
+
+In the C# output language, each node type is converted into a `class'
+that contains the node's fields, virtual operations, and other house-keeping
+definitions. The following example demonstrates how treecc node declarations
+are converted into C# source code:
+
+
+
+
+public class expression
+{
+ protected int kind__;
+ protected String filename__;
+ protected long linenum__;
+
+ public int getKind() { return kind__; }
+ public String getFilename() { return filename__; }
+ public long getLinenum() const { return linenum__; }
+ public void setFilename(String filename) { filename__ = filename; }
+ public void setLinenum(long linenum) { linenum__ = linenum; }
+
+ public const int KIND = 1;
+
+ public type_code type;
+
+ protected expression()
+ {
+ this.kind__ = KIND;
+ this.filename__ = YYNODESTATE.getState().currFilename();
+ this.linenum__ = YYNODESTATE.getState().currLinenum();
+ }
+
+ public virtual int isA(int kind)
+ {
+ if(kind == KIND)
+ return 1;
+ else
+ return 0;
+ }
+
+ public virtual String getKindName()
+ {
+ return "expression";
+ }
+}
+
+public class binary : expression
+{
+ public const int KIND = 2;
+
+ public expression expr1;
+ public expression expr2;
+
+ protected binary(expression expr1, expression expr2)
+ : expression()
+ {
+ this.kind__ = KIND;
+ this.expr1 = expr1;
+ this.expr2 = expr2;
+ }
+
+ public override int isA(int kind)
+ {
+ if(kind == KIND)
+ return 1;
+ else
+ return base.isA(kind);
+ }
+
+ public override String getKindName()
+ {
+ return "binary";
+ }
+}
+
+public class plus : binary
+{
+ public const int KIND = 5;
+
+ public plus(expression expr1, expression expr2)
+ : binary(expr1, expr2)
+ {
+ this.kind__ = KIND;
+ }
+
+ public override int isA(int kind)
+ {
+ if(kind == KIND)
+ return 1;
+ else
+ return base.isA(kind);
+ }
+
+ public override String getKindName()
+ {
+ return "plus";
+ }
+}
+
+
+
+The following standard members are available on every node type:
+
+
+
+
+
const int KIND
+
+
+The kind value for the node type corresponding to this class.
+
+
int getKind()
+
+
+Gets the numeric kind value associated with a particular node.
+The kind value for node type `NAME' is called `NAME.KIND'.
+
+
virtual String getKindName()
+
+
+Gets the name of the node kind associated with a particular node.
+This may be helpful for debugging and logging code.
+
+
virtual int isA(int kind)
+
+
+Determines if the node is a member of the node type that corresponds
+to the numeric kind value `kind'.
+
+
String getFilename()
+
+
+Gets the filename corresponding to where the node was created
+during parsing. This method is only generated if `%option track_lines'
+was specified.
+
+
long getLinenum()
+
+
+Gets the line number corresponding to where the node was created
+during parsing. This method is only generated if `%option track_lines'
+was specified.
+
+
void setFilename(String value)
+
+
+Sets the filename associated with the node to `value'.
+This method will rarely be required, unless a node corresponds to
+a different line than the current parse line. This method is only
+generated if `%option track_lines' was specified.
+
+
void setLinenum(long value)
+
+
+Sets the line number associated with the node to `value'.
+This method will rarely be required, unless a node corresponds to a
+different line than the current parse line. This method is only
+generated if `%option track_lines' was specified.
+
+
+
+If the generated code is non-reentrant, then the constructor for the
+class can be used to construct nodes of the specified node type. The
+constructor parameters are the same as the fields within the node type's
+definition, except for `%nocreate' fields.
+
+
+
+If the generated code is reentrant, then nodes cannot be constructed
+using the C# `new' operator. The `*Create' methods
+on the `YYNODESTATE' factory class must be used instead.
+
+
+
+Enumerated types are converted into a C# `enum' definition:
+
+
+
+
+public class InferType
+{
+ public static void infer_type(expression e)
+ {
+ ...
+ }
+}
+
+
+
+If the class name (`InferType' in the above example) is omitted,
+then the name of the operation is used as both the class name and the
+the method name.
+
+
+
+The `YYNODESTATE' class contains a number of house-keeping methods
+that are used to manage nodes:
+
+
+
+
+
static YYNODESTATE getState()
+
+
+Gets the global `YYNODESTATE' instance that is being used by
+non-reentrant code. If an instance has not yet been created,
+this method will create one.
+
+When using non-reentrant code, the programmer will normally subclass
+`YYNODESTATE', override some of the methods below, and then
+construct an instance of the subclass. This constructed instance
+will then be returned by future calls to `getState'.
+
+This method will not be present if a reentrant system is being
+generated.
+
+
virtual String currFilename()
+
+
+Get the name of the current input file from the parser. This method
+is usually overrriden by the programmer in subclasses if
+`%option track_lines' was specified.
+
+
virtual long currLinenum()
+
+
+Get the number of the current input line from the parser. This
+method is usually overridden by the programmer in subclasses
+if `%option track_lines' was specified.
+
+
+
+The programmer will typically subclass `YYNODESTATE' to provide
+additional functionality, and then create an instance of this class
+to act as the global state and node creation factory.
+
+
+
+
+
+The EBNF syntax for treecc input files uses the following
+lexical tokens:
+
+
+
+
+IDENTIFIER ::= <A-Za-z_> { <A-Za-z0-9_> }
+
+STRING ::= '"' <anything that does not include '"'> '"'
+ | "'" <anything that does not include "'"> "'"
+
+LITERAL_DEFNS ::= "%{" <anything except "%}"> "%}"
+
+LITERAL_END ::= "%%" <any character sequence until EOF>
+
+LITERAL_CODE ::= '{' <anything with matched '{' and '}'> '}'
+
+
+
+In addition, anything that begins with "%" in the following syntax
+is a lexical keyword.
+
+
+