--- /dev/null
+<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>
projects / msp430-gcc.git / blobdiff