Keywords: ISO C++, library

Appendix B. Porting and Maintenance
Prev | Part IV. Appendices | Next

# Porting and Maintenance

## Configure and Build Hacking

### Prerequisites

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.

### Overview

#### General Process

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`.

#### What Comes from Where

Figure B.1. Configure and Build File Dependencies

Regenerate all generated files by using the command autoreconf at the top level of the libstdc++ source directory.

### Configure

#### Storing Information in non-AC files (like configure.host)

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.

#### Coding and Commenting Conventions

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 acinclude.m4 layout

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.

#### `GLIBCXX_ENABLE`, the `--enable` maker

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:

1. Builds the call to the `AC_ARG_ENABLE` macro, with `--help` text properly quoted and aligned. (Death to changequote!)

2. 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.

#### Shared Library Versioning

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 ``libbuilddir`/testsuite` 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.

### Make

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:

1. make include files, make pre-compiled headers

2. make libsupc++

   Generates a libtool convenience library, `libsupc++convenience` with language-support routines. Also generates a freestanding static library, `libsupc++.a`.

3. make src

   Generates several convenience libraries, various compatibility files for shared and static libraries, and then collects all the generated bits and creates the final libstdc++ libraries.

   1. make src/c++98

      Generates a libtool convenience library, `libc++98convenience` with the library components defined by C++98. Uses the `-std=gnu++98` dialect.

   2. make src/c++11

      Generates a libtool convenience library, `libc++11convenience` with the library components that were added or changed in C++11. Uses the `-std=gnu++11` dialect.

   3. make src/c++17

      Generates a libtool convenience library, `libc++17convenience` with the library components that were added or changed in C++17. Uses the `-std=gnu++17` dialect.

   4. make src/c++20

      Generates a libtool convenience library, `libc++20convenience` with the library components that were added or changed in C++20. Uses the `-std=gnu++20` dialect.

   5. make src/c++23

      Generates a libtool convenience library, `libc++23convenience` with the library components that were added or changed in C++23. At the time of writing (GCC 14) this convenience library is included in `libstdc++exp.a` and not in the final `libstdc++` libraries. Uses the `-std=gnu++23` dialect.

   6. make src/filesystem

      Generates a libtool convenience library, `libstdc++fsconvenience`, and a standalone static library, `libstdc++fs.a`. These contain definitions of the Filesystem TS extensions. Uses the `-std=gnu++17` dialect.

   7. make src/libbacktrace

      Generates a libtool convenience library, `libstdc++_libbacktrace`, containing the libbacktrace definitions used by the C++23 `std::stacktrace` feature.

   8. make src/experimental

      Generates a standalone static library, `libstdc++exp.a`, containing the symbol definitions for experimental features and extensions. This collects the convenience libraries `libstdc++fsconvenience`, `libstdc++_libbacktrace`, and (at the time of writing) `libc++23convenience` and combines them into one. Uses the `-std=gnu++17` dialect.

   9. 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 that weren't added to `libstdc++exp.a`, adds in any required compatibility objects, and creates the final shared and static libraries: `libstdc++.so` and `libstdc++.a`.

### Generated files

Some files in the libstdc++ source tree are auto-generated from other files. In general, these are not regenerated automatically, so it must be done manually when the files they depend on are updated.

- The header file `include/bits/version.h` is generated from `version.def` and `version.tpl` in the same directory. After editing those files, either run autogen version.def in the `include` directory of the source tree, or run make update-version in the `include` directory of the build tree.

- The header file `include/bits/unicode-data.h` is generated by the Python script `../contrib/unicode/gen_libstdcxx_unicode_data.py` using data files in the same directory. The script contains information on which data files it uses and how to update them.

- The header file `include/bits/text_encoding-data.h` is generated by the Python script `scripts/gen_text_encoding_data.py` using the CSV file https://www.iana.org/assignments/character-sets/character-sets-1.csv from the IANA Character Sets registry.

- The data file `src/c++20/tzdata.zi` is copied verbatim from the IANA Time Zone Database (the latest version can be downloaded from https://data.iana.org/time-zones/tzdb/tzdata.zi). Libstdc++ uses this data file to populate a `std::chrono::tzdb` object in case the system does not provide a copy of the file. See Configuring for the `--with-libstdcxx-zoneinfo` option that determines whether this file is used.

- The header file `src/c++20/windows_zones-map.h` is generated by the Python script `scripts/gen_windows_zones_map.py` using the XML file https://github.com/unicode-org/cldr/blob/main/common/supplemental/windowsZones.xml from the Unicode CLDR Project.

Prev | Up | Next
Design Notes | Home | Writing and Generating Documentation