C++ interop overlay

Active contributors: zoecarver, gribozavr, hborla, egorzhdan

Purpose

stdlib/public/Cxx/ is the Swift overlay for C++ interop. It pairs with the work in ClangImporter to make C++ types and functions usable from Swift. The overlay provides:

• The conversion conformances (String <-> std::string, Array <-> std::vector).
• The CxxSequence, CxxRandomAccessCollection, CxxConvertibleToCollection protocols that imported C++ container types conform to.
• Helper types and protocols for moving between Swift and C++ memory and lifetime models.

The user-facing documentation lives in docs/CppInteroperability/. Most code lives in this directory plus lib/ClangImporter/ and test/Interop/Cxx/.

Directory layout

stdlib/public/Cxx/
├── Cxx.swift, CxxConvertibleToBool.swift, CxxConvertibleToCollection.swift
├── CxxDictionary.swift, CxxOptional.swift, CxxPair.swift, CxxSet.swift, CxxSpan.swift
├── CxxIterator.swift, CxxRandomAccessCollection.swift, CxxSequence.swift, CxxStdString.swift
├── CxxStdlib.swift                     # umbrella module
├── CxxStdlibShim/                      # bridging shim headers
└── ...

There is also a stdlib/public/Cxx/std/ style modulemap that exposes pieces of the C++ standard library to Swift.

Key abstractions

Type / protocol	File	Description
CxxSequence	stdlib/public/Cxx/CxxSequence.swift	Imported C++ container conforms to give Swift Sequence.
CxxRandomAccessCollection	stdlib/public/Cxx/CxxRandomAccessCollection.swift	For std::vector and friends.
CxxConvertibleToBool	stdlib/public/Cxx/CxxConvertibleToBool.swift	Imported types with an operator bool() conform.
CxxStdString	stdlib/public/Cxx/CxxStdString.swift	std::string ↔ Swift.String bridging.
CxxOptional	stdlib/public/Cxx/CxxOptional.swift	std::optional<T> mapping.
CxxPair	stdlib/public/Cxx/CxxPair.swift	std::pair<A, B> mapping.
CxxSpan	stdlib/public/Cxx/CxxSpan.swift	std::span ↔ Swift.Span (and unsafe variants).

How it works

graph TD
    CppHeader["C++ header"] --> Clang
    Clang -->|"AST"| ClangImporter
    ClangImporter -->|"creates Swift Decls"| ImportedType[Imported Swift type]
    ImportedType -->|"conforms to"| CxxOverlay["protocols in stdlib/public/Cxx/"]
    UserCode["Swift code uses imported type"] --> ImportedType

ClangImporter translates a C++ class to a Swift struct. The Cxx overlay then conditionally conforms imported types to the appropriate Swift protocols based on what the C++ class supports:

• A class with begin() / end() and an iterator gets CxxSequence (and possibly CxxRandomAccessCollection).
• A class with operator bool() gets CxxConvertibleToBool.
• A class with appropriate constructors gets the conversion to/from the Swift counterpart.

These conformances are typically added via API-notes-style annotations (SWIFT_*_CONFORMS_TO, SWIFT_NAME, etc.) on the C++ side -- see docs/CppInteroperability/CxxInteroperabilityManifesto.md.

Reference vs value semantics

C++ types are by default imported as Swift structs (value semantics with copy). Reference-typed C++ classes (those with SWIFT_SHARED_REFERENCE_TYPE annotations or matching heuristics in lib/ClangImporter/) are imported as Swift classes with manual lifetime management. The choice strongly affects what's safe in Swift.

Memory model

C++ raw pointers, references, and smart pointers all map to Swift UnsafePointer / UnsafeMutablePointer variants. There is no automatic ownership transfer -- the programmer must respect the C++ object's expected lifetime.

Integration points

• ClangImporter -- the source of imported C++ types.
• Standard library -- String, Array, etc. provide explicit conversion APIs to/from C++ counterparts.
• Tests -- test/Interop/Cxx/ is the largest test subdirectory in the repo (1,690 commits in the last year alone).

Entry points for modification

• Adding a new C++ stdlib bridging: drop a .swift file under stdlib/public/Cxx/, declare the conformance, add tests under test/Interop/Cxx/stdlib/.
• Improving import behavior: the heuristics live in lib/ClangImporter/ImportDecl.cpp and ImportType.cpp. Many overrides come from .apinotes files.
• Investigating an interop bug: most are reproduced as a small .cpp header plus a 5-line .swift test under test/Interop/Cxx/.

Related pages

• ClangImporter -- how C++ types are translated.
• Standard library -- the Swift counterpart types.
• docs/CppInteroperability/ -- the user-facing manuals.