A clean-room C++26 standard library

A standard library that a program selects explicitly, in place of the toolchain’s libstdc++ or libc++, for the latest GCC and Clang on Linux and macOS.

libycxx is layered. A freestanding core needs no operating system, no C library and no heap unless one is supplied. The hosted library adds everything that needs the environment — streams, files, threads, clocks, locales — and reaches the system only through a small C-linkage platform abstraction layer. Underneath sits libycxx’s own Itanium C++ ABI runtime, so a program built with it depends on neither libsupc++ nor libc++abi.

Standard

C++26 (the current working draft), C++26 only

Compilers

the latest GCC and Clang (matrix)

Platforms

Linux and macOS; bare-metal targets freestanding (matrix)

Layers

freestanding core · hosted library · platform abstraction layer

ABI runtime

its own: exceptions, RTTI, dynamic_cast, guards

Modules

import std; and import std.compat;

Version

0.1.0 — no stable ABI yet

Source

github.com/yrashk/libycxx

Every header of the C++26 library is provided, with the deprecated features the draft still specifies (Annex D, marked [[deprecated]]) and without the ones it has removed.

• Language support & utilities

  <type_traits>, <expected>, <optional>, <variant>, the function wrappers including function_ref, indirect and polymorphic, constexpr exceptions on GCC.

• Containers & ranges

  Every container, constexpr, including <hive>, <inplace_vector>, <flat_map> and <mdspan>; every range factory and adaptor; every std:: and ranges:: algorithm.

• Text

  <format> and <print> in full, <charconv> with shortest round-trip floating point, <regex> with all six grammars, <text_encoding> with the IANA registry.

• Numerics

  <random> with philox_engine and all 20 distributions, <simd>, <linalg>, <cmath>, <complex>, <valarray>.

• Time

  <chrono> in full: the calendar, utc/tai/gps clocks with leap seconds, the time zone database on the system’s zoneinfo, every formatter and parser.

• Concurrency

  Threads, atomics, latches, barriers and semaphores, <rcu>, <hazard_pointer>, and senders and receivers in <execution> with parallel_scheduler.

• I/O & locales

  Iostreams, <spanstream>, <syncstream>, <filesystem>, every standard facet, and named locales from the C library.

• Diagnostics

  <stacktrace> with ELF/DWARF symbolization and its own demangler, <debugging>, <contracts> and <meta> (reflection) where GCC supports them.

Freestanding, hosted and modules

Every core header, every header with a freestanding subset and every header of the draft’s freestanding table compiles with -ffreestanding -nostdlib -nostdinc -fno-exceptions -fno-rtti; a smoke test links for x86_64-unknown-none-elf and riscv64-unknown-elf. An optional runtime archive, ycxx::freestanding, supplies allocation, floating-point <charconv> and the atomic wait tables to programs without an operating system.

The standard library modules std and std.compat are generated from the headers and built per project with the project’s own flags, from CMake (ycxx::modules) or with tools/ycxx-modules.

Audited against the draft

Three audits walk the synopses of the working draft and generate a check for every declaration, on both compilers (docs/SPEC_COVERAGE.md):

What remains open is compiler-blocked: Clang 23 has no reflection or contracts and cannot throw during constant evaluation; GCC 16 lacks is_within_lifetime.

A handful of rules, written down in DECISIONS.md with their reasons and the alternatives that were rejected.

Deliberate divergences

Where the draft and the established libraries disagree, libycxx follows the draft and says so; where the letter of the draft would break portable code, it follows practice and says that too. The full list is in STATUS.md (“Deliberate divergences”):

• to_chars without a precision follows P3505 and the draft’s “smallest number of characters”, where older tests encode the C++17 rule.
• Floating-point from_chars leaves the value unmodified on result_out_of_range, as the draft says.
• <regex>’s ECMAScript grammar follows ECMA-262 (\a is an identity escape; a back-reference may precede its group).
• regex_traits::transform_primary in the classic locale returns the whole sort key, so [[=a=]] keeps working there, as portable code expects.
• expected’s operator== with a value deduces its left operand, to avoid a constraint recursion the literal signature causes.

Against the specification, by several independent oracles, in every configuration a user can select — and every run explains itself.

Its own suite, written from the draft

2,824 tests in tests/ycxx, written by an author who may read only the working draft and cppreference — never libc++’s or libstdc++’s tests, nor any implementation, libycxx’s included. A failing test is a library bug until the draft shows otherwise; tests are never weakened to fit. Tests that must not compile name the diagnostic they expect, and hardened preconditions have death tests. Running the suite against libstdc++ validates the tests themselves: every difference is listed and triaged.

libc++ and libstdc++ conformance suites

Both suites run unmodified from pinned releases (LLVM 23.1.2’s libcxx/test/std, GCC 16.2.0’s libstdc++ testsuite), fetched on demand and never vendored.

Every failure is categorised in tests/libcxx/TRIAGE.md and tests/libstdcxx/TRIAGE.md. Most are tests that rely on headers libstdc++ and libc++ include from one another, on their own specifics or pre-C++26 values, or on not running as root. Skipped tests carry a category and a reason and name the libycxx test that covers the subject. ^*Projected from the full run with the final lists.

Sanitizers, hardening and library modes

All three suites run under AddressSanitizer, UndefinedBehaviorSanitizer and ThreadSanitizer, linked with a libycxx built with the same sanitizers — an uninstrumented library would hide every hand-off through its own mutexes and reference counts. The own suite also runs hardened, with -fno-exceptions and at -O2, each with its own report.

Nineteen real-world projects

tools/realworld builds open-source projects against libycxx with both compilers and runs their own test suites; then it proves the build was libycxx’s alone: every translation unit’s command, every object’s headers, every image’s needed libraries and symbols, and libycxx’s allocation table in every image. A self-test built with the toolchain’s library is rejected on every count.

^†One CTest test runs the project’s whole suite. All 19 also pass under AddressSanitizer, and five under ThreadSanitizer; neither reported anything in libycxx. The projects found three libycxx bugs (each fixed with a test) and four compiler bugs; their patches are to their own non-standard code, each with a category and reason.

Continuous integration, without baselines

Every push runs the policy checks, both library builds, the freestanding check, the CMake package test and the own suite on Linux (the gcc:16 container, Clang 23 from apt.llvm.org) and macOS (Apple Silicon, Homebrew’s GCC 16, Clang 23), and on Linux a sample of both external suites. Nightly, the whole external suites run on both compilers and both platforms, with the sanitizer, hardened, no-exceptions and -O2 configurations and the real-world projects. The platform and compiler matrix lists what each combination has passed.

There is no list of tolerated failures. A test reported FAIL fails the run, and every failure is resolved where its cause is decided: a libycxx bug is fixed; a test that does not apply is skipped with its category and reason; a cause outside the test and the library — a compiler bug, an ABI limit, a draft defect — is an expected failure with its reason, and an unexpected pass fails the run so the mark goes when the cause does.

Every test, passing ones included, records its commands, exit statuses and output; each run writes an HTML report with its provenance, and a Markdown copy ready to paste to a person or an assistant.

Exactly what has been confirmed, where, and with which compiler. A ✓ means a CI run or a run recorded in STATUS.md passed with no unexpected failure; anything less is said in words.

Linux on aarch64 and other architectures: not built or tested. — means not run.

1. ^a CI run of 2026-10-07 (commit d48ba32), 2,824 tests; no failures. Expected failures carry their cause in the test (compiler gaps, ABI limits, a draft defect); the rest are unsupported in that configuration.
2. ^b Full runs of 2026-10-05/06 recorded in STATUS.md: 211 and 215 libc++ failures, 13 libstdc++ failures per compiler, each categorised in the suites’ TRIAGE.md. The Clang libstdc++ figure is projected from the full run with the final skip lists. The CI sample (selected directories) passes on every push.
3. ^c Own suite, runs of 2026-10-05 recorded in STATUS.md: hardened 2,425 / 2,418 pass and -fno-exceptions 1,941 pass, no failures. The nightly also runs -O2, for which STATUS.md records no result.
4. ^d Runs of 2026-10-07 recorded in STATUS.md, with the linkage proof for every project.
5. ^e ASan and TSan: whole own suite, 2026-10-06, no failures (GCC TSan with a GCC built with libsanitizer). The nightly ASan job also enables UBSan; STATUS.md records the ASan run.
6. ^f The nightly workflow runs both external suites on macOS; STATUS.md records no macOS result yet, and named locales and <stacktrace> symbolization are less exercised there.
7. ^g examples/hosted-layers, run by the CMake package test on Linux.

Build libycxx once per compiler, install it, and point a project at the installation. docs/BUILDING_PROJECTS.md covers CMake, Meson, make, autotools, Bazel, Conan and vcpkg.

1. Toolchains

tools/toolchain/provision finds GCC 16.2 and Clang 23.1 or installs them; activation puts them on PATH.

git clone https://github.com/yrashk/libycxx && cd libycxx
# finds GCC 16.2 and Clang 23.1, or downloads/builds what is missing
source tools/toolchain/activate.sh --provision

2. Build and install

cmake -S . -B build/gcc -G Ninja \
      -DCMAKE_C_COMPILER=$YCXX_GCC -DCMAKE_CXX_COMPILER=$YCXX_GXX
cmake --build build/gcc
cmake --install build/gcc --prefix /opt/libycxx-gcc

3. Use it

A project of your own links ycxx::ycxx, which compiles against libycxx’s headers and links its archives and ABI runtime instead of libstdc++ or libc++:

find_package(libycxx CONFIG REQUIRED)
add_executable(app main.cpp)
# ycxx::modules instead, for import std;
target_link_libraries(app PRIVATE ycxx::ycxx)

An existing project that knows nothing about libycxx is built with the installed toolchain file, the compiler wrappers, a Meson native file, or pkg-config (with PKG_CONFIG_PATH set to the installation’s lib/pkgconfig):

P=/opt/libycxx-gcc
cmake -S proj -B build -DCMAKE_TOOLCHAIN_FILE=$P/lib/cmake/libycxx/toolchain.cmake
make CXX=$P/bin/ycxx-c++ CC=$P/bin/ycxx-cc
meson setup build --native-file $P/share/libycxx/meson-native.ini
g++-16 $(pkg-config --cflags libycxx) main.cpp $(pkg-config --libs libycxx)

ycxx-c++ is the compiler libycxx was built with, plus its headers, C++26 and its archives. Each C++ dependency must be built from source the same way: libycxx has its own ABI, so a distribution’s prebuilt C++ libraries cannot be linked in. C libraries are fine.

4. Check the result

# was everything built against libycxx, and nothing else?
/opt/libycxx-gcc/bin/ycxx-check-binary build
# libycxx's own gate: policy checks, builds, freestanding, own suite
tools/test

Every header of C++26 is in place and the own suite passes on both compilers, on Linux and macOS. What libycxx is not yet, plainly:

• Young, without a stable ABI

  Version 0.1.0. Type layouts change between commits: rebuild everything, dependencies included, when libycxx changes, and keep one installation per compiler.

• C++26 only

  Older -std= modes are raised to C++26, so features C++26 removed (auto_ptr, <strstream>, …) and libstdc++/libc++ extensions do not compile. Code relying on headers those libraries include from one another needs a few #includes.

• One runtime per image

  libycxx links statically and hides its symbols, so each shared library has its own runtime state: terminate and new handlers, throw; and current_exception do not cross shared-library boundaries.

• Compiler gaps

  <meta> needs GCC with -freflection and <contracts> GCC’s -fcontracts; Clang 23 has neither and cannot throw during constant evaluation. GCC 16 cannot mix #include and import std; in one translation unit.

• macOS is newer

  The macOS job runs the gate on every push, but parts written for Darwin are less exercised: named locales there, and <stacktrace> symbolization, which reads ELF and DWARF only. Modules are tested on Linux only.

• Open work

  Remaining external-suite failures are triaged; two libycxx bugs are open among them. <filesystem> and the time zone database have no hosted-layer primitives yet. About ten benchmarks remain over 1.5× slower than libstdc++.

STATUS.md is the full record: per-area results, known compiler gaps, the draft defects noticed along the way, and what comes next.