Merge pull request #67523 from hyp/eng/compat-version

[cxx-interop] add 'upcoming-swift' C++ interop compat version

Author: hyp

docs/CppInteroperability/CppInteroperabilityContributorGuide.md

@@ -0,0 +1,101 @@
+# 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 `LangOptoins` 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.

include/swift/Basic/LangOptions.h

@@ -310,6 +310,10 @@ namespace swift {
     /// disabled because it is not complete.
     bool EnableCXXInterop = false;
 
+    /// The C++ interoperability source compatibility version. Defaults
+    /// to the Swift language version.
+    version::Version cxxInteropCompatVersion;
+
     bool CForeignReferenceTypes = false;
 
     /// Imports getters and setters as computed properties.
@@ -655,6 +659,13 @@ namespace swift {
       return EffectiveLanguageVersion.isVersionAtLeast(major, minor);
     }
 
+    /// Whether the C++ interoperability compatibility version is at least
+    /// 'major'.
+    bool isCxxInteropCompatVersionAtLeast(unsigned major,
+                                          unsigned minor = 0) const {
+      return cxxInteropCompatVersion.isVersionAtLeast(major, minor);
+    }
+
     /// Determine whether the given feature is enabled.
     bool hasFeature(Feature feature) const;
 

include/swift/Basic/Version.h

@@ -175,6 +175,11 @@ StringRef getCurrentCompilerTag();
 /// depending on the vendor.
 StringRef getCurrentCompilerSerializationTag();
 
+/// Retrieves the value of the upcoming C++ interoperability compatibility
+/// version that's going to be presented as some new concrete version to the
+/// users.
+unsigned getUpcomingCxxInteropCompatVersion();
+
 } // end namespace version
 } // end namespace swift
 

lib/Basic/Version.cpp

@@ -306,5 +306,9 @@ StringRef getCurrentCompilerSerializationTag() {
 #endif
 }
 
+unsigned getUpcomingCxxInteropCompatVersion() {
+  return SWIFT_VERSION_MAJOR + 1;
+}
+
 } // end namespace version
 } // end namespace swift

lib/ClangImporter/ImporterImpl.h

@@ -589,6 +589,17 @@ class LLVM_LIBRARY_VISIBILITY ClangImporter::Implementation
     return Instance.get();
   }
 
+  /// Whether the C++ interoperability compatibility version is at least
+  /// 'major'.
+  ///
+  /// Use the
+  /// `isCxxInteropCompatVersionAtLeast(version::getUpcomingCxxInteropCompatVersion())`
+  /// check when making a source breaking C++ interop change.
+  bool isCxxInteropCompatVersionAtLeast(unsigned major,
+                                        unsigned minor = 0) const {
+    return SwiftContext.LangOpts.isCxxInteropCompatVersionAtLeast(major, minor);
+  }
+
 private:
   /// The Importer may be configured to load modules of a different OS Version
   /// than the underlying Swift compilation. This is the `TargetOptions`

lib/Frontend/CompilerInvocation.cpp

@@ -486,15 +486,20 @@ enum class CxxCompatMode {
   off
 };
 
-static CxxCompatMode validateCxxInteropCompatibilityMode(StringRef mode) {
+static std::pair<CxxCompatMode, version::Version>
+validateCxxInteropCompatibilityMode(StringRef mode) {
   if (mode == "off")
-    return CxxCompatMode::off;
+    return {CxxCompatMode::off, {}};
   if (mode == "default")
-    return CxxCompatMode::enabled;
-  // FIXME: Drop swift-5.9.
+    return {CxxCompatMode::enabled, {}};
+  if (mode == "upcoming-swift")
+    return {CxxCompatMode::enabled,
+            version::Version({version::getUpcomingCxxInteropCompatVersion()})};
+  // Swift-5.9 corresponds to the Swift 5 language mode when
+  // Swift 5 is the default language version.
   if (mode == "swift-5.9")
-    return CxxCompatMode::enabled;
-  return CxxCompatMode::invalid;
+    return {CxxCompatMode::enabled, version::Version({5})};
+  return {CxxCompatMode::invalid, {}};
 }
 
 static void diagnoseCxxInteropCompatMode(Arg *verArg, ArgList &Args,
@@ -1066,16 +1071,29 @@ static bool ParseLangArgs(LangOptions &Opts, ArgList &Args,
     }
 
     auto interopCompatMode = validateCxxInteropCompatibilityMode(A->getValue());
-    Opts.EnableCXXInterop |= (interopCompatMode == CxxCompatMode::enabled);
+    Opts.EnableCXXInterop |=
+        (interopCompatMode.first == CxxCompatMode::enabled);
+    if (Opts.EnableCXXInterop) {
+      Opts.cxxInteropCompatVersion = interopCompatMode.second;
+      // The default is tied to the current language version.
+      if (Opts.cxxInteropCompatVersion.empty())
+        Opts.cxxInteropCompatVersion =
+            Opts.EffectiveLanguageVersion.asMajorVersion();
+    }
 
-    if (interopCompatMode == CxxCompatMode::invalid)
+    if (interopCompatMode.first == CxxCompatMode::invalid)
       diagnoseCxxInteropCompatMode(A, Args, Diags);
   }
-  
+
   if (Args.hasArg(OPT_enable_experimental_cxx_interop)) {
     Diags.diagnose(SourceLoc(), diag::enable_interop_flag_deprecated);
     Diags.diagnose(SourceLoc(), diag::swift_will_maintain_compat);
     Opts.EnableCXXInterop |= true;
+    // Using the deprecated option only forces the 'swift-5.9' compat
+    // mode.
+    if (Opts.cxxInteropCompatVersion.empty())
+      Opts.cxxInteropCompatVersion =
+          validateCxxInteropCompatibilityMode("swift-5.9").second;
   }
 
   Opts.EnableObjCInterop =

test/Interop/Cxx/driver/invalid-interop-compat-mode.swift

@@ -2,8 +2,8 @@
 // RUN: split-file %s %t
 // RUN: not %target-swift-frontend -typecheck -I %t/Inputs  %t/test.swift  -cxx-interoperability-mode=swift-5.8 2>&1 | %FileCheck %s
 
-// Note: swift-5.9 is still supported, but will be removed.
 // RUN: %target-swift-frontend -typecheck -I %t/Inputs  %t/test.swift  -cxx-interoperability-mode=swift-5.9
+// RUN: %target-swift-frontend -typecheck -I %t/Inputs  %t/test.swift  -cxx-interoperability-mode=upcoming-swift
 
 //--- Inputs/module.modulemap
 module Test {