Appendix B. + Porting and Maintenance + +
Prev	Part IV. + Appendices +	Next

+ Porting and Maintenance + +

Configure and Build Hacking

Prerequisites

+ 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. +

Overview: What Comes from Where

Figure B.1. Configure and Build File Dependencies

Dependency Graph for Configure and Build Files

+ 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.11 && autoconf-2.64 && + autoheader-2.64 && automake-1.11" The version + numbers may be absent entirely or otherwise vary depending on + the + current requirements and your vendor's choice of + installation names. +

+    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. +

`GLIBCXX_ENABLE`, the `--enable` maker

+ 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. +

Prev	Up	Next
Design Notes	Home	Writing and Generating Documentation