Table of Contents
std::
not supportedisspace
from <cctype>
is a macro
vector::at
, deque::at
, string::at
std::char_traits<char>::eof
string::clear
ostream::form
and istream::scan
extensions
basic_stringbuf
, basic_stringstream
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.
The configure process begins the act of building libstdc++, and is started via:
configure
The configure
file is a script generated (via
autoconf) from the file
configure.ac
.
After the configure process is complete,
make all
in the build directory starts the build process. The all
target comes from the Makefile
file, which is generated via configure from the Makefile.in
file, which is in turn generated (via
automake) from the file
Makefile.am
.
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.
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 ancillary
.m4
files should.
About the only comments which should not
use #
, but use dnl
instead,
are comments outside our own macros in the ancillary
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 ancillary 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 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_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.
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.
The libstdc++.so
shared library must
be carefully managed to maintain binary compatible with older versions
of the library. This ensures a new version of the library is still usable by
programs that were linked against an older version.
Dependent on the target supporting it, the library uses ELF symbol versioning for all exported symbols. The symbol versions are defined by a linker script that assigns a version to every symbol. The set of symbols in each version is fixed when a GCC release is made, and must not change after that.
When new symbols are added to the library they must be added to a new symbol version, which must be created the first time new symbols are added after a release. Adding a new symbol version involves the following steps:
Edit acinclude.m4
to update the "revision" value of
libtool_VERSION
, e.g. from 6:22:0
to 6:23:0
, which will cause the shared library to be
built as libstdc++.so.6.0.23
.
Regenerate the configure
script by running the
autoreconf tool from the correct version of the Autoconf
package (as dictated by the GCC
prerequisites).
Edit the file config/abi/pre/gnu.ver
to
add a new version node after the last new node. The node name should be
GLIBCXX_3.4.X
where X
is the new
revision set in acinclude.m4
, and the node should
depend on the previous version e.g.
GLIBCXX_3.4.23 { } GLIBCXX_3.4.22;
For symbols in the ABI runtime, libsupc++, the symbol version naming uses
CXXABI_1.3.Y
where Y
increases
monotonically with each new version. Again, the new node must depend on the
previous version node e.g.
CXXABI_1.3.11 { } CXXABI_1.3.10;
In order for the check-abi test
target to pass the testsuite must be updated to know about the new symbol
version(s). Edit the file testsuite/util/testsuite_abi.cc
file to add the new versions to the known_versions
list,
and update the checks for the latest versions that set the
latestp
variable).
Add the library (libstdc++.so.6.0.X
)
and symbols versions
(GLIBCXX_3.4.X
and CXXABI_1.3.Y
)
to the History section in
doc/xml/manual/abi.xml
at the relevant places.
Once the new symbol version has been added you can add the names of your new symbols in the new version node:
GLIBCXX_3.4.23 { # basic_string<C, T, A>::_Alloc_hider::_Alloc_hider(C*, A&&) _ZNSt7__cxx1112basic_stringI[cw]St11char_traitsI[cw]ESaI[cw]EE12_Alloc_hiderC[12]EP[cw]OS3_; } GLIBCXX_3.4.22;
You can either use mangled names, or demangled names inside an
extern "C++"
block. You might find that the new symbol
matches an existing pattern in an old symbol version (causing the
check-abi
test target to fail). If that happens then the
existing pattern must be adjusted to be more specific so that it doesn't
match the new symbol.
For an example of these steps, including adjusting old patterns to be less greedy, see https://gcc.gnu.org/ml/gcc-patches/2016-07/msg01926.html and the attached patch.
If it wasn't done for the last release, you might also need to regenerate
the baseline_symbols.txt
file that defines the set
of expected symbols for old symbol versions. A new baseline file can be
generated by running make new-abi-baseline
in the
directory. Be sure to generate the baseline from a clean build using
unmodified sources, or you will incorporate your local changes into the
baseline file.
libbuilddir
/testsuite
The build process has to make all of object files needed for static or shared libraries, but first it has to generate some include files. The general order is as follows:
make include files, make pre-compiled headers
make libsupc++
Generates a libtool convenience library,
libsupc++convenience
with language-support
routines. Also generates a freestanding static library,
libsupc++.a
.
make src
Generates two convenience libraries, one for C++98 and one for C++11, various compatibility files for shared and static libraries, and then collects all the generated bits and creates the final libstdc++ libraries.
make src/c++98
Generates a libtool convenience library,
libc++98convenience
with language-support
routines. Uses the -std=gnu++98
dialect.
make src/c++11
Generates a libtool convenience library,
libc++11convenience
with language-support
routines. Uses the -std=gnu++11
dialect.
make src
Generates needed compatibility objects for shared and static
libraries. Shared-only code is seggregated at compile-time via
the macro _GLIBCXX_SHARED
.
Then, collects all the generated convenience libraries, adds in
any required compatibility objects, and creates the final shared
and static libraries: libstdc++.so
and
libstdc++.a
.