Swift and C++ interop: Guide for Swift contributors

This document describes how to contribute changes to Swift and C++ interoperability support in the Swift compiler. The recommended way to contribute touches on topics like source stability of C++ interop, making breaking changes, and compatibility testing.

Here's a short summary of how you should contribute to Swift and C++ interop:

Treat every change as potentially source breaking, unless proven otherwise.
Guard any potentially source breaking change with appropriate interop compat version checks.
Explicitly specify the interop compat version in your test when adding breaking changes.
Ensure that your GitHub PR is approved by one of the code owners before merging.

Changing Swift and C++ interop

The initial support for Swift and C++ interop in Swift 5.9 is considered to be source stable, as in a future compiler like Swift 5.10 must build any Swift code that uses C++ interop and was previously built with Swift 5.9 compiler without forcing the user to make any changes to their code. Because of that promise that we're making to our users, we need to be very diligent when it comes to making changes to how Swift and C++ interop work, as they could potentially violate this promise. Thus it's recommended that you treat every change as source breaking, unless proven otherwise.

What is C++ Interop Compat Version

C++ interop compat version is the Swift version value given to the -cxx-interoperability-mode= Swift command line option.

It supports values like:

default. Corresponds to the currently used Swift language version. For instance, by default for Swift 5 compiler the C++ interop compat version will be 5 when -cxx-interoperability-mode=default is passed. However, if you pass -cxx-interoperability-mode=default and -swift-version 6, then the C++ interop compat version becomes 6.
swift-X.Y. A specific version like Swift 5.9.
upcoming-swift. Corresponds to the C++ interop compat version that represents the development unreleased version of Swift and C++ interoperability. All new source breaking changes must be guarded by this version first before they migrate to a specific released version of Swift and C++ interoperability.

Guarding Source Breaking Changes in Compiler Implementation

Any source breaking change must be guarded with an appropriate interop compat version check. Swift's LangOptions have a cxxInteropCompatVersion member that is the interop compat version.

You can use the isCxxInteropCompatVersionAtLeast check to validate that you're building for the upcoming version of C++ and Swift interop. For example, in the clang importer, you can call this check method on the Impl:

// Inside of Clang Importer (Impl is `ClangImporter::Impl`)
if (Impl.isCxxInteropCompatVersionAtLeast(version::getUpcomingCxxInteropCompatVersion())) {
  // ... breaking change ...
}

Elsewhere, this method can be called on the LangOptions themselves:

if (SwiftContext.LangOpts.isCxxInteropCompatVersionAtLeast(version::getUpcomingCxxInteropCompatVersion())) {
  // ... breaking change ...
}

Testing the change

Please add new tests under test/Interop/Cxx, or modify existing tests there.

Any tests for source breaking changes should invoke the Swift compiler with the -cxx-interoperability-mode=upcoming-swift option.

Submitting the Change as PR on GitHub

GitHub PR checklist for C++ interop related changes:

Please tag your PR with 'C++ Interop' tag.
Code owners should be added for review automatically.
Please ensure that one of the current code owners reviews and approves the PR before merging.

Releasing a new Swift and C++ Interop Compat Version

You need to update all Swift sources to migrate these checks isCxxInteropCompatVersionAtLeast(version::getUpcomingCxxInteropCompatVersion()) to the concrete version you're now releasing, for instance isCxxInteropCompatVersionAtLeast(5, 10).

There are more things we'll need to do but we haven't released a new interop compat version yet, so this document will be updated once we do so.