libcxx

libcxx/ is libc++ — the LLVM project's implementation of the C++ standard library. It pairs with libc++abi (the C++ ABI runtime) and libunwind (stack unwinder) to form a complete, modular C++ runtime that ships independently from any particular system libc.

Purpose

libc++ is the default standard library on Apple platforms, on FreeBSD, and (increasingly) on Linux distributions that ship Clang. It targets correctness, conformance with the latest published C++ standard, and a high-quality test suite that doubles as a conformance reference.

Directory layout

libcxx/
├── include/         # Public C++ headers
│   ├── __algorithm/, __ranges/, __chrono/, __concepts/, __coroutine/,
│   │  __format/, __filesystem/, __functional/, __iterator/, __memory/,
│   │  __mutex/, __numeric/, __random/, __string/, __thread/, __type_traits/,
│   │  __utility/, __vector/, __variant/, __math/, __locale/, __atomic/, ...
│   └── (one detail directory per logical area; the user-facing headers like
│        <vector>, <algorithm>, <ranges> live at this level)
├── src/             # Compiled parts — only the bits that aren't header-only
├── modules/         # C++20 module map
├── test/            # The libc++ test suite (lit-driven, tens of thousands of files)
├── benchmarks/
├── cmake/
├── docs/            # Sphinx documentation
├── lib/             # Linker scripts and ABI version flags
├── utils/           # Test helpers, gdb pretty printers, ci scripts
└── CMakeLists.txt

The __* directories under include/ are the implementation; the user-facing <vector>, <algorithm>, <format>, etc. headers pull from them. This split keeps include-time costs down and lets internal refactors avoid touching the user-visible header text.

What's compiled vs. header-only

Most of libc++ is header-only templates. The compiled portion under libcxx/src/ covers things that can't be templates: locale data tables, <ios> / <iostream> virtuals, random-device platform calls, filesystem syscalls, exception types declared by libc++abi.

How it works

A C++ program compiled with -stdlib=libc++ (Clang) gets:

graph LR
    user[User code] -->|"#include <vector>"| public[libc++ public header]
    public -->|"#include <__vector/...>"| impl[libc++ detail header]
    impl --> templates[Template instantiations]
    user -->|some symbols| compiled["libc++ compiled (libc++.so / .a)"]
    compiled -->|throws / typeinfo| cxxabi[libc++abi]
    cxxabi -->|unwinding| unwind[libunwind]

ABI compatibility is governed by the _LIBCPP_ABI_* set of macros and by the carefully tracked symbols in libcxx/lib/abi/. The project follows a strict ABI-stability policy except in major-version transitions clearly flagged in release notes.

Testing

The libc++ test suite is one of the most comprehensive C++ standard-library test suites in existence. Tests live under libcxx/test/ organized by the C++ standard's structure (std/, libcxx/, ...). The check-cxx target runs them.

Tests use libc++'s lit configuration, which knows how to pick up the just-built library, discover ABI configuration, and run with the right C++ language version.

Modules

libc++ ships a C++20 module map in libcxx/modules/. The std and std.compat modules can be built and consumed by Clang-with-modules. This is the project's reference implementation of the import std; feature.

Integration points

• libc++abi (libcxxabi) — paired ABI runtime. libc++ throws and catches exceptions through libc++abi.
• libunwind (libunwind) — the unwinder libc++abi calls into.
• Clang — the production compiler. GCC works, but libc++'s build/test matrix focuses on Clang.
• compiler-rt (compiler-rt) — sanitizer integration; libc++ has special-cased annotations for ASan, MSan, and TSan.

Entry points for modification

• Adding an algorithm or container method: extend the relevant __<area>/ detail header. Add a test under libcxx/test/std/<chapter>/.
• Implementing a new C++ standard feature: track the feature on the libc++ status page, wire the feature-test macro through __config, implement, test against the standard's specification.
• Adding a target: most platform glue is under libcxx/src/ per-syscall, plus the build matrix in libcxx/cmake/caches/.

Reference

• libc++ documentation
• Standards-conformance status
• Contributing to libc++