Table of Contents
+ As noted previously,
+ certain other tools are necessary for hacking on files that
+ control configure (configure.ac,
+ acinclude.m4) and make
+ (Makefile.am). These additional tools
+ (automake, and autoconf) are further
+ described in detail in their respective manuals. All the libraries
+ in GCC try to stay in sync with each other in terms of versions of
+ the auto-tools used, so please try to play nicely with the
+ neighbors.
+
++
+ Regenerate all generated files by using the command sequence
+ "autoreconf" at the top level of the libstdc++ source
+ directory. The following will also work, but is much more complex:
+ "aclocal-1.7 && autoconf-2.59 &&
+ autoheader-2.59 && automake-1.7" The version
+ numbers may be absent entirely or otherwise vary depending on
+ the
+ current requirements and your vendor's choice of
+ installation names.
+
+ Until that glorious day when we can use AC_TRY_LINK with a + cross-compiler, we have to hardcode the results of what the tests + would have shown if they could be run. So we have an inflexible + mess like crossconfig.m4. +
+ Wouldn't it be nice if we could store that information in files + like configure.host, which can be modified without needing to + regenerate anything, and can even be tweaked without really + knowing how the configury all works? Perhaps break the pieces of + crossconfig.m4 out and place them in their appropriate + config/{cpu,os} directory. +
+ Alas, writing macros like
+ "AC_DEFINE(HAVE_A_NICE_DAY)" can only be done inside
+ files which are passed through autoconf. Files which are pure
+ shell script can be source'd at configure time. Files which
+ contain autoconf macros must be processed with autoconf. We could
+ still try breaking the pieces out into "config/*/cross.m4" bits,
+ for instance, but then we would need arguments to aclocal/autoconf
+ to properly find them all when generating configure. I would
+ discourage that.
+
+ Most comments should use {octothorpes, shibboleths, hash marks,
+ pound signs, whatever} rather than "dnl". Nearly all comments in
+ configure.ac should. Comments inside macros written in ancilliary
+ .m4 files should. About the only comments which should
+ not use #, but use dnl instead, are comments
+ outside our own macros in the ancilliary
+ files. The difference is that # comments show up in
+ configure (which is most helpful for debugging),
+ while dnl'd lines just vanish. Since the macros in ancilliary
+ files generate code which appears in odd places, their "outside"
+ comments tend to not be useful while reading
+ configure.
+
+ Do not use any $target* variables, such as
+ $target_alias. The single exception is in
+ configure.ac, for automake+dejagnu's sake.
+
+ The nice thing about acinclude.m4/aclocal.m4 is that macros aren't + actually performed/called/expanded/whatever here, just loaded. So + we can arrange the contents however we like. As of this writing, + acinclude.m4 is arranged as follows: +
+ GLIBCXX_CHECK_HOST + GLIBCXX_TOPREL_CONFIGURE + GLIBCXX_CONFIGURE +
+ All the major variable "discovery" is done here. CXX, multilibs, + etc. +
+ fragments included from elsewhere +
+ Right now, "fragments" == "the math/linkage bits". +
+ GLIBCXX_CHECK_COMPILER_FEATURES + GLIBCXX_CHECK_LINKER_FEATURES + GLIBCXX_CHECK_WCHAR_T_SUPPORT +
+ Next come extra compiler/linker feature tests. Wide character + support was placed here because I couldn't think of another place + for it. It will probably get broken apart like the math tests, + because we're still disabling wchars on systems which could actually + support them. +
+ GLIBCXX_CHECK_SETRLIMIT_ancilliary + GLIBCXX_CHECK_SETRLIMIT + GLIBCXX_CHECK_S_ISREG_OR_S_IFREG + GLIBCXX_CHECK_POLL + GLIBCXX_CHECK_WRITEV + + GLIBCXX_CONFIGURE_TESTSUITE +
+ Feature tests which only get used in one place. Here, things used + only in the testsuite, plus a couple bits used in the guts of I/O. +
+ GLIBCXX_EXPORT_INCLUDES + GLIBCXX_EXPORT_FLAGS + GLIBCXX_EXPORT_INSTALL_INFO +
+ Installation variables, multilibs, working with the rest of the + compiler. Many of the critical variables used in the makefiles are + set here. +
+ GLIBGCC_ENABLE + GLIBCXX_ENABLE_C99 + GLIBCXX_ENABLE_CHEADERS + GLIBCXX_ENABLE_CLOCALE + GLIBCXX_ENABLE_CONCEPT_CHECKS + GLIBCXX_ENABLE_CSTDIO + GLIBCXX_ENABLE_CXX_FLAGS + GLIBCXX_ENABLE_C_MBCHAR + GLIBCXX_ENABLE_DEBUG + GLIBCXX_ENABLE_DEBUG_FLAGS + GLIBCXX_ENABLE_LONG_LONG + GLIBCXX_ENABLE_PCH + GLIBCXX_ENABLE_SJLJ_EXCEPTIONS + GLIBCXX_ENABLE_SYMVERS + GLIBCXX_ENABLE_THREADS +
+ All the features which can be controlled with enable/disable + configure options. Note how they're alphabetized now? Keep them + like that. :-) +
+ AC_LC_MESSAGES + libtool bits +
+ Things which we don't seem to use directly, but just has to be + present otherwise stuff magically goes wonky. +
+ All the GLIBCXX_ENABLE_FOO macros use a common helper, + GLIBCXX_ENABLE. (You don't have to use it, but it's easy.) The + helper does two things for us: +
+ Builds the call to the AC_ARG_ENABLE macro, with --help text + properly quoted and aligned. (Death to changequote!) +
+ Checks the result against a list of allowed possibilities, and + signals a fatal error if there's no match. This means that the + rest of the GLIBCXX_ENABLE_FOO macro doesn't need to test for + strange arguments, nor do we need to protect against + empty/whitespace strings with the
"x$foo" = "xbar"+ idiom. +
Doing these things correctly takes some extra autoconf/autom4te code, + which made our macros nearly illegible. So all the ugliness is factored + out into this one helper macro. +
Many of the macros take an argument, passed from when they are expanded + in configure.ac. The argument controls the default value of the + enable/disable switch. Previously, the arguments themselves had defaults. + Now they don't, because that's extra complexity with zero gain for us. +
There are three "overloaded signatures". When reading the descriptions + below, keep in mind that the brackets are autoconf's quotation characters, + and that they will be stripped. Examples of just about everything occur + in acinclude.m4, if you want to look. +
+ GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING) + GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, permit a|b|c) + GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, SHELL-CODE-HANDLER) +
+ FEATURE is the string that follows --enable. The results of the + test (such as it is) will be in the variable $enable_FEATURE, + where FEATURE has been squashed. Example: +
[extra-foo], controlled by the --enable-extra-foo + option and stored in $enable_extra_foo. ++ DEFAULT is the value to store in $enable_FEATURE if the user does + not pass --enable/--disable. It should be one of the permitted + values passed later. Examples:
[yes], or +[bar], or[$1](which passes the + argument given to the GLIBCXX_ENABLE_FOO macro as the + default). ++ For cases where we need to probe for particular models of things, + it is useful to have an undocumented "auto" value here (see + GLIBCXX_ENABLE_CLOCALE for an example). +
+ HELP-ARG is any text to append to the option string itself in the + --help output. Examples:
[](i.e., an empty string, + which appends nothing),[=BAR], which produces +--enable-extra-foo=BAR, and +[@<:@=BAR@:>@], which produces +--enable-extra-foo[=BAR]. See the difference? See + what it implies to the user? ++ If you're wondering what that line noise in the last example was, + that's how you embed autoconf special characters in output text. + They're called quadrigraphs + and you should use them whenever necessary. +
HELP-STRING is what you think it is. Do not include the + "default" text like we used to do; it will be done for you by + GLIBCXX_ENABLE. By convention, these are not full English + sentences. Example: [turn on extra foo] +
+ With no other arguments, only the standard autoconf patterns are
+ allowed: "--{enable,disable}-foo[={yes,no}]" The
+ $enable_FEATURE variable is guaranteed to equal either "yes" or "no"
+ after the macro. If the user tries to pass something else, an
+ explanatory error message will be given, and configure will halt.
+
+ The second signature takes a fifth argument, "[permit
+ a | b | c | ...]"
+ This allows a or b or
+ ... after the equals sign in the option, and $enable_FEATURE is
+ guaranteed to equal one of them after the macro. Note that if you
+ want to allow plain --enable/--disable with no "=whatever", you must
+ include "yes" and "no" in the list of permitted values. Also note
+ that whatever you passed as DEFAULT must be in the list. If the
+ user tries to pass something not on the list, a semi-explanatory
+ error message will be given, and configure will halt. Example:
+ [permit generic|gnu|ieee_1003.1-2001|yes|no|auto]
+
+ The third signature takes a fifth argument. It is arbitrary shell + code to execute if the user actually passes the enable/disable + option. (If the user does not, the default is used. Duh.) No + argument checking at all is done in this signature. See + GLIBCXX_ENABLE_CXX_FLAGS for an example of handling, and an error + message. +