mirror of git://gcc.gnu.org/git/gcc.git
355 lines
12 KiB
XML
355 lines
12 KiB
XML
<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">
|
|
<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">
|
|
<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.11 && autoconf-2.64 &&
|
|
autoheader-2.64 && automake-1.11"</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">
|
|
<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">
|
|
<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">
|
|
<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">
|
|
<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.html#Quadrigraphs"><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>
|