diff options
Diffstat (limited to 'libstdc++-v3/doc/xml/manual/build_hacking.xml')
| -rw-r--r-- | libstdc++-v3/doc/xml/manual/build_hacking.xml | 355 |
1 files changed, 355 insertions, 0 deletions
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 @@ +<section xmlns="http://docbook.org/ns/docbook" version="5.0" + xml:id="appendix.porting.build_hacking" xreflabel="Build Hacking"> +<?dbhtml filename="build_hacking.html"?> + +<info><title>Configure and Build Hacking</title> + <keywordset> + <keyword> + C++ + </keyword> + <keyword> + BUILD_HACKING + </keyword> + <keyword> + version + </keyword> + <keyword> + dynamic + </keyword> + <keyword> + shared + </keyword> + </keywordset> +</info> + +<section xml:id="build_hacking.prereq"><info><title>Prerequisites</title></info> + + <para> + As noted <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/install/prerequisites.html">previously</link>, + certain other tools are necessary for hacking on files that + control configure (<code>configure.ac</code>, + <code>acinclude.m4</code>) and make + (<code>Makefile.am</code>). These additional tools + (<code>automake</code>, and <code>autoconf</code>) 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. + </para> +</section> + +<section xml:id="build_hacking.map"><info><title>Overview: What Comes from Where</title></info> + + + <figure> + <title>Configure and Build File Dependencies</title> + <mediaobject> + <imageobject> + <imagedata align="center" format="PDF" fileref="/mnt/share/src/gcc.svn-trunk/libstdc++-v3/doc/xml/images/confdeps.pdf"/> + </imageobject> + <imageobject> + <imagedata align="center" format="PNG" fileref="/mnt/share/src/gcc.svn-trunk/libstdc++-v3/doc/xml/images/confdeps.png"/> + </imageobject> + <textobject> + <phrase>Dependency Graph for Configure and Build Files</phrase> + </textobject> + </mediaobject> + </figure> + + <para> + Regenerate all generated files by using the command sequence + <code>"autoreconf"</code> at the top level of the libstdc++ source + directory. The following will also work, but is much more complex: + <code>"aclocal-1.11 && autoconf-2.64 && + autoheader-2.64 && automake-1.11"</code> The version + numbers may be absent entirely or otherwise vary depending on + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/install/prerequisites.html">the + current requirements</link> and your vendor's choice of + installation names. + </para> +</section> + +<section xml:id="build_hacking.scripts"><info><title>Storing Information in non-AC files (like configure.host)</title></info> + + + <para> + 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. + </para> + + <para> + 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. + </para> + + <para> + Alas, writing macros like + "<code>AC_DEFINE(HAVE_A_NICE_DAY)</code>" 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. +</para> +</section> + +<section xml:id="build_hacking.conventions"><info><title>Coding and Commenting Conventions</title></info> + + + <para> + 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 + <emphasis>not</emphasis> use #, but use dnl instead, are comments + <emphasis>outside</emphasis> our own macros in the ancilliary + files. The difference is that # comments show up in + <code>configure</code> (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 + <code>configure</code>. + </para> + + <para> + Do not use any <code>$target*</code> variables, such as + <code>$target_alias</code>. The single exception is in + configure.ac, for automake+dejagnu's sake. + </para> +</section> + +<section xml:id="build_hacking.acinclude"><info><title>The acinclude.m4 layout</title></info> + + <para> + 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: + </para> + <programlisting> + GLIBCXX_CHECK_HOST + GLIBCXX_TOPREL_CONFIGURE + GLIBCXX_CONFIGURE + </programlisting> + <para> + All the major variable "discovery" is done here. CXX, multilibs, + etc. + </para> + <programlisting> + fragments included from elsewhere + </programlisting> + <para> + Right now, "fragments" == "the math/linkage bits". + </para> +<programlisting> + GLIBCXX_CHECK_COMPILER_FEATURES + GLIBCXX_CHECK_LINKER_FEATURES + GLIBCXX_CHECK_WCHAR_T_SUPPORT +</programlisting> +<para> + 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. +</para> +<programlisting> + GLIBCXX_CHECK_SETRLIMIT_ancilliary + GLIBCXX_CHECK_SETRLIMIT + GLIBCXX_CHECK_S_ISREG_OR_S_IFREG + GLIBCXX_CHECK_POLL + GLIBCXX_CHECK_WRITEV + + GLIBCXX_CONFIGURE_TESTSUITE +</programlisting> +<para> + 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. +</para> +<programlisting> + GLIBCXX_EXPORT_INCLUDES + GLIBCXX_EXPORT_FLAGS + GLIBCXX_EXPORT_INSTALL_INFO +</programlisting> +<para> + Installation variables, multilibs, working with the rest of the + compiler. Many of the critical variables used in the makefiles are + set here. +</para> +<programlisting> + 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 +</programlisting> +<para> + All the features which can be controlled with enable/disable + configure options. Note how they're alphabetized now? Keep them + like that. :-) +</para> +<programlisting> + AC_LC_MESSAGES + libtool bits +</programlisting> +<para> + Things which we don't seem to use directly, but just has to be + present otherwise stuff magically goes wonky. +</para> + +</section> + +<section xml:id="build_hacking.enable"><info><title><constant>GLIBCXX_ENABLE</constant>, the <literal>--enable</literal> maker</title></info> + + + <para> + 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: + </para> + +<orderedlist> + <listitem> + <para> + Builds the call to the AC_ARG_ENABLE macro, with --help text + properly quoted and aligned. (Death to changequote!) + </para> + </listitem> + <listitem> + <para> + 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 <code>"x$foo" = "xbar"</code> + idiom. + </para> + </listitem> +</orderedlist> + +<para>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. +</para> + +<para>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. +</para> + +<para>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. +</para> + +<programlisting> + 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) +</programlisting> + +<itemizedlist> + <listitem> + <para> + 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: + <code>[extra-foo]</code>, controlled by the --enable-extra-foo + option and stored in $enable_extra_foo. + </para> + </listitem> + <listitem> + <para> + 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: <code>[yes]</code>, or + <code>[bar]</code>, or <code>[$1]</code> (which passes the + argument given to the GLIBCXX_ENABLE_FOO macro as the + default). + </para> + <para> + 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). + </para> + </listitem> + <listitem> + <para> + HELP-ARG is any text to append to the option string itself in the + --help output. Examples: <code>[]</code> (i.e., an empty string, + which appends nothing), <code>[=BAR]</code>, which produces + <code>--enable-extra-foo=BAR</code>, and + <code>[@<:@=BAR@:>@]</code>, which produces + <code>--enable-extra-foo[=BAR]</code>. See the difference? See + what it implies to the user? + </para> + <para> + 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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.gnu.org/software/autoconf/manual/autoconf.html#Quadrigraphs"><emphasis>quadrigraphs</emphasis></link> + and you should use them whenever necessary. + </para> + </listitem> + <listitem> + <para>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] + </para> + </listitem> +</itemizedlist> + +<para> + With no other arguments, only the standard autoconf patterns are + allowed: "<code>--{enable,disable}-foo[={yes,no}]</code>" 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. +</para> + +<para> + The second signature takes a fifth argument, "<code>[permit + a | b | c | ...]</code>" + This allows <emphasis>a</emphasis> or <emphasis>b</emphasis> 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: + <code>[permit generic|gnu|ieee_1003.1-2001|yes|no|auto]</code> +</para> + +<para> + 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. +</para> + +</section> + +</section> |