From 554fd8c5195424bdbcabf5de30fdc183aba391bd Mon Sep 17 00:00:00 2001 From: upstream source tree Date: Sun, 15 Mar 2015 20:14:05 -0400 Subject: obtained gcc-4.6.4.tar.bz2 from upstream website; verified gcc-4.6.4.tar.bz2.sig; imported gcc-4.6.4 source tree from verified upstream tarball. downloading a git-generated archive based on the 'upstream' tag should provide you with a source tree that is binary identical to the one extracted from the above tarball. if you have obtained the source via the command 'git clone', however, do note that line-endings of files in your working directory might differ from line-endings of the respective files in the upstream repository. --- libstdc++-v3/doc/xml/manual/build_hacking.xml | 355 ++++++++++++++++++++++++++ 1 file changed, 355 insertions(+) create mode 100644 libstdc++-v3/doc/xml/manual/build_hacking.xml (limited to 'libstdc++-v3/doc/xml/manual/build_hacking.xml') diff --git a/libstdc++-v3/doc/xml/manual/build_hacking.xml b/libstdc++-v3/doc/xml/manual/build_hacking.xml new file mode 100644 index 000000000..945ef4996 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/build_hacking.xml @@ -0,0 +1,355 @@ +
+ + +Configure and Build Hacking + + + C++ + + + BUILD_HACKING + + + version + + + dynamic + + + shared + + + + +
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 + + +
+ 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. + +
+ +
Storing Information in non-AC files (like configure.host) + + + + 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. + +
+ +
Coding and Commenting Conventions + + + + 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 acinclude.m4 layout + + + 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. + + +
+ +
<constant>GLIBCXX_ENABLE</constant>, the <literal>--enable</literal> 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. + + +
+ +
-- cgit v1.2.3