| <sect1 id="appendix.porting.build_hacking" xreflabel="build_hacking"> |
| <?dbhtml filename="build_hacking.html"?> |
| |
| <sect1info> |
| <keywordset> |
| <keyword> |
| C++ |
| </keyword> |
| <keyword> |
| BUILD_HACKING |
| </keyword> |
| <keyword> |
| version |
| </keyword> |
| <keyword> |
| dynamic |
| </keyword> |
| <keyword> |
| shared |
| </keyword> |
| </keywordset> |
| </sect1info> |
| |
| <title>Configure and Build Hacking</title> |
| |
| <sect2 id="build_hacking.prereq" xreflabel="build_hacking.prereq"> |
| <title>Prerequisites</title> |
| <para> |
| As noted <ulink |
| url="http://gcc.gnu.org/install/prerequisites.html">previously</ulink>, |
| 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> |
| </sect2> |
| |
| <sect2 id="build_hacking.map" xreflabel="build_hacking.map"> |
| <title>Overview: What Comes from Where</title> |
| |
| <screen> |
| <inlinemediaobject> |
| <imageobject> |
| <imagedata fileref="../images/confdeps.png"/> |
| </imageobject> |
| <textobject> |
| <phrase>Dependency Graph Configure to Build Files</phrase> |
| </textobject> |
| </inlinemediaobject> |
| </screen> |
| |
| <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.7 && autoconf-2.59 && |
| autoheader-2.59 && automake-1.7"</code> The version |
| numbers may be absent entirely or otherwise vary depending on |
| <ulink url="http://gcc.gnu.org/install/prerequisites.html">the |
| current requirements</ulink> and your vendor's choice of |
| installation names. |
| </para> |
| </sect2> |
| |
| <sect2 id="build_hacking.scripts" xreflabel="build_hacking.scripts"> |
| <title>Storing Information in non-AC files (like configure.host)</title> |
| |
| <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> |
| </sect2> |
| |
| <sect2 id="build_hacking.conventions" xreflabel="build_hacking.conventions"> |
| <title>Coding and Commenting Conventions</title> |
| |
| <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> |
| </sect2> |
| |
| <sect2 id="build_hacking.acinclude" xreflabel="build_hacking.acinclude"> |
| <title>The acinclude.m4 layout</title> |
| <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> |
| |
| </sect2> |
| |
| <sect2 id="build_hacking.enable" xreflabel="build_hacking.enable"> |
| <title><constant>GLIBCXX_ENABLE</constant>, the <literal>--enable</literal> maker</title> |
| |
| <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 <ulink |
| url="http://www.gnu.org/software/autoconf/manual/autoconf-2.57/html_node/autoconf_95.html#SEC95"><emphasis>quadrigraphs</emphasis></ulink> |
| 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> |
| |
| </sect2> |
| |
| </sect1> |