Store test content in a custom metadata section.

This PR uses the experimental symbol linkage margers feature in the Swift
compiler to emit metadata about tests (and exit tests) into a dedicated section
of the test executable being built. At runtime, we discover that section and
read out the tests from it.

This has several benefits over our current model, which involves walking Swift's
type metadata table looking for types that conform to a protocol:

1. We don't need to define that protocol as public API in Swift Testing,
1. We don't need to emit type metadata (much larger than what we really need)
   for every test function,
1. We don't need to duplicate a large chunk of the Swift ABI sources in order to
   walk the type metadata table correctly, and
1. Almost all the new code is written in Swift, whereas the code it is intended
   to replace could not be fully represented in Swift and needed to be written
   in C++.

The change also opens up the possibility of supporting generic types in the
future because we can emit metadata without needing to emit a nested type (which
is not always valid in a generic context.) That's a "future direction" and not
covered by this PR specifically.

I've defined a layout for entries in the new `swift5_tests` section that should
be flexible enough for us in the short-to-medium term and which lets us define
additional arbitrary test content record types. The layout of this section is
covered in depth in the new [TestContent.md](Documentation/ABI/TestContent.md)
article.

This functionality is only available if a test target enables the experimental
`"SymbolLinkageMarkers"` feature. We continue to emit protocol-conforming types
for now—that code will be removed if and when the experimental feature is
properly supported (modulo us adopting relevant changes to the feature's API.)

#735
swiftlang/swift#76698
swiftlang/swift#78411

Author: grynspan

Documentation/ABI/TestContent.md

@@ -41,10 +41,15 @@ Regardless of platform, all test content records created and discoverable by the
 testing library have the following layout:
 
 ```swift
+typealias Accessor = @convention(c) (
+  _ outValue: UnsafeMutableRawPointer,
+  _ hint: UnsafeRawPointer?
+) -> CBool
+
 typealias TestContentRecord = (
   kind: UInt32,
   reserved1: UInt32,
-  accessor: (@convention(c) (_ outValue: UnsafeMutableRawPointer, _ hint: UnsafeRawPointer?) -> CBool)?,
+  accessor: Accessor?,
   context: UInt,
   reserved2: UInt
 )
@@ -54,25 +59,30 @@ This type has natural size, stride, and alignment. Its fields are native-endian.
 If needed, this type can be represented in C as a structure:
 
 ```c
+typedef bool (* SWTAccessor)(
+  void *outValue,
+  const void *_Null_unspecified hint
+);
+
 struct SWTTestContentRecord {
   uint32_t kind;
   uint32_t reserved1;
-  bool (* _Nullable accessor)(void *outValue, const void *_Null_unspecified hint);
+  SWTAccessor _Nullable accessor;
   uintptr_t context;
   uintptr_t reserved2;
 };
 ```
 
-Do not use the `__TestContentRecord` typealias defined in the testing library.
-This type exists to support the testing library's macros and may change in the
-future (e.g. to accomodate a generic argument or to make use of one of the
-reserved fields.)
+Do not use the `__TestContentRecord` or `__TestContentRecordAccessor` type
+aliases defined in the testing library. These types exist to support the testing
+library's macros and may change in the future (e.g. to accomodate a generic
+argument or to make use of a reserved field.)
 
-Instead, define your own copy of this type where needed—you can copy the
-definition above _verbatim_. If your test record type's `context` field (as
+Instead, define your own copy of these types where needed—you can copy the
+definitions above _verbatim_. If your test record type's `context` field (as
 described below) is a pointer type, make sure to change its type in your version
 of `TestContentRecord` accordingly so that, on systems with pointer
-authentication enabled, the pointer is correctly resigned at load time.
+authentication enabled, the pointer is correctly re-signed at load time.
 
 ### Record content
 

Documentation/Porting.md

@@ -145,8 +145,10 @@ to load that information:
 +  let resourceName: Str255 = switch kind {
 +  case .testContent:
 +    "__swift5_tests"
++#if !SWT_NO_LEGACY_TEST_DISCOVERY
 +  case .typeMetadata:
 +    "__swift5_types"
++#endif
 +  }
 +
 +  let oldRefNum = CurResFile()
@@ -219,15 +221,19 @@ diff --git a/Sources/_TestingInternals/Discovery.cpp b/Sources/_TestingInternals
 +#elif defined(macintosh)
 +extern "C" const char testContentSectionBegin __asm__("...");
 +extern "C" const char testContentSectionEnd __asm__("...");
++#if !defined(SWT_NO_LEGACY_TEST_DISCOVERY)
 +extern "C" const char typeMetadataSectionBegin __asm__("...");
 +extern "C" const char typeMetadataSectionEnd __asm__("...");
++#endif
  #else
  #warning Platform-specific implementation missing: Runtime test discovery unavailable (static)
  static const char testContentSectionBegin = 0;
  static const char& testContentSectionEnd = testContentSectionBegin;
+ #if !defined(SWT_NO_LEGACY_TEST_DISCOVERY)
  static const char typeMetadataSectionBegin = 0;
  static const char& typeMetadataSectionEnd = testContentSectionBegin;
  #endif
+ #endif
 ```
 
 These symbols must have unique addresses corresponding to the first byte of the

Package.swift

@@ -156,6 +156,8 @@ extension Array where Element == PackageDescription.SwiftSetting {
       .enableExperimentalFeature("AccessLevelOnImport"),
       .enableUpcomingFeature("InternalImportsByDefault"),
 
+      .enableExperimentalFeature("SymbolLinkageMarkers"),
+
       .define("SWT_TARGET_OS_APPLE", .when(platforms: [.macOS, .iOS, .macCatalyst, .watchOS, .tvOS, .visionOS])),
 
       .define("SWT_NO_EXIT_TESTS", .when(platforms: [.iOS, .watchOS, .tvOS, .visionOS, .wasi, .android])),

Sources/Testing/Discovery+Platform.swift

@@ -27,8 +27,10 @@ struct SectionBounds: Sendable {
     /// The test content metadata section.
     case testContent
 
+#if !SWT_NO_LEGACY_TEST_DISCOVERY
     /// The type metadata section.
     case typeMetadata
+#endif
   }
 
   /// All section bounds of the given kind found in the current process.
@@ -60,8 +62,10 @@ extension SectionBounds.Kind {
     switch self {
     case .testContent:
       ("__DATA_CONST", "__swift5_tests")
+#if !SWT_NO_LEGACY_TEST_DISCOVERY
     case .typeMetadata:
       ("__TEXT", "__swift5_types")
+#endif
     }
   }
 }
@@ -101,9 +105,8 @@ private let _startCollectingSectionBounds: Void = {
       var size = CUnsignedLong(0)
       if let start = getsectiondata(mh, segmentName.utf8Start, sectionName.utf8Start, &size), size > 0 {
         let buffer = UnsafeRawBufferPointer(start: start, count: Int(clamping: size))
-        let sb = SectionBounds(imageAddress: mh, buffer: buffer)
         _sectionBounds.withLock { sectionBounds in
-          sectionBounds[kind]!.append(sb)
+          sectionBounds[kind]!.append(SectionBounds(imageAddress: mh, buffer: buffer))
         }
       }
     }
@@ -165,8 +168,10 @@ private func _sectionBounds(_ kind: SectionBounds.Kind) -> [SectionBounds] {
       let range = switch context.pointee.kind {
       case .testContent:
         sections.swift5_tests
+#if !SWT_NO_LEGACY_TEST_DISCOVERY
       case .typeMetadata:
         sections.swift5_type_metadata
+#endif
       }
       let start = UnsafeRawPointer(bitPattern: range.start)
       let size = Int(clamping: range.length)
@@ -255,8 +260,10 @@ private func _sectionBounds(_ kind: SectionBounds.Kind) -> some Sequence<Section
   let sectionName = switch kind {
   case .testContent:
     ".sw5test"
+#if !SWT_NO_LEGACY_TEST_DISCOVERY
   case .typeMetadata:
     ".sw5tymd"
+#endif
   }
   return HMODULE.all.lazy.compactMap { _findSection(named: sectionName, in: $0) }
 }
@@ -288,8 +295,10 @@ private func _sectionBounds(_ kind: SectionBounds.Kind) -> CollectionOfOne<Secti
   let (sectionBegin, sectionEnd) = switch kind {
   case .testContent:
     SWTTestContentSectionBounds
+#if !SWT_NO_LEGACY_TEST_DISCOVERY
   case .typeMetadata:
     SWTTypeMetadataSectionBounds
+#endif
   }
   let buffer = UnsafeRawBufferPointer(start: sectionBegin, count: max(0, sectionEnd - sectionBegin))
   let sb = SectionBounds(imageAddress: nil, buffer: buffer)

Sources/Testing/Discovery.swift

@@ -10,6 +10,23 @@
 
 private import _TestingInternals
 
+/// The type of the accessor function used to access a test content record.
+///
+/// - Parameters:
+///   - outValue: A pointer to uninitialized memory large enough to contain the
+///     corresponding test content record's value.
+///   - hint: An optional pointer to a hint value.
+///
+/// - Returns: Whether or not `outValue` was initialized. The caller is
+///   responsible for deinitializing `outValue` if it was initialized.
+///
+/// - Warning: This type is used to implement the `@Test` macro. Do not use it
+///   directly.
+public typealias __TestContentRecordAccessor = @convention(c) (
+  _ outValue: UnsafeMutableRawPointer,
+  _ hint: UnsafeRawPointer?
+) -> CBool
+
 /// The content of a test content record.
 ///
 /// - Parameters:
@@ -24,7 +41,7 @@ private import _TestingInternals
 public typealias __TestContentRecord = (
   kind: UInt32,
   reserved1: UInt32,
-  accessor: (@convention(c) (_ outValue: UnsafeMutableRawPointer, _ hint: UnsafeRawPointer?) -> CBool)?,
+  accessor: __TestContentRecordAccessor?,
   context: UInt,
   reserved2: UInt
 )

Sources/Testing/ExitTests/ExitTest.swift

@@ -247,11 +247,15 @@ extension ExitTest {
       }
     }
 
+#if !SWT_NO_LEGACY_TEST_DISCOVERY
     // Call the legacy lookup function that discovers tests embedded in types.
     return types(withNamesContaining: exitTestContainerTypeNameMagic).lazy
       .compactMap { $0 as? any __ExitTestContainer.Type }
       .first { $0.__id == id }
       .map { ExitTest(__identifiedBy: $0.__id, body: $0.__body) }
+#else
+    return nil
+#endif
   }
 }
 

Sources/Testing/Test+Discovery+Legacy.swift

@@ -10,6 +10,7 @@
 
 private import _TestingInternals
 
+#if !SWT_NO_LEGACY_TEST_DISCOVERY
 /// A protocol describing a type that contains tests.
 ///
 /// - Warning: This protocol is used to implement the `@Test` macro. Do not use
@@ -60,3 +61,4 @@ func types(withNamesContaining nameSubstring: String) -> some Sequence<Any.Type>
       .map { unsafeBitCast($0, to: Any.Type.self) }
   }
 }
+#endif

Sources/Testing/Test+Discovery.swift

@@ -46,6 +46,7 @@ extension Test {
       // the legacy and new mechanisms, but we can set an environment variable
       // to explicitly select one or the other. When we remove legacy support,
       // we can also remove this enumeration and environment variable check.
+#if !SWT_NO_LEGACY_TEST_DISCOVERY
       let (useNewMode, useLegacyMode) = switch Environment.flag(named: "SWT_USE_LEGACY_TEST_DISCOVERY") {
       case .none:
         (true, true)
@@ -54,6 +55,9 @@ extension Test {
       case .some(false):
         (true, false)
       }
+#else
+      let useNewMode = true
+#endif
 
       // Walk all test content and gather generator functions, then call them in
       // a task group and collate their results.
@@ -72,6 +76,7 @@ extension Test {
         }
       }
 
+#if !SWT_NO_LEGACY_TEST_DISCOVERY
       // Perform legacy test discovery if needed.
       if useLegacyMode && result.isEmpty {
         let types = types(withNamesContaining: testContainerTypeNameMagic).lazy
@@ -85,6 +90,7 @@ extension Test {
           result = await taskGroup.reduce(into: result) { $0.formUnion($1) }
         }
       }
+#endif
 
       return result
     }

Sources/TestingMacros/CMakeLists.txt

@@ -87,6 +87,7 @@ target_sources(TestingMacros PRIVATE
   Support/Additions/DeclGroupSyntaxAdditions.swift
   Support/Additions/EditorPlaceholderExprSyntaxAdditions.swift
   Support/Additions/FunctionDeclSyntaxAdditions.swift
+  Support/Additions/IntegerLiteralExprSyntaxAdditions.swift
   Support/Additions/MacroExpansionContextAdditions.swift
   Support/Additions/TokenSyntaxAdditions.swift
   Support/Additions/TriviaPieceAdditions.swift
@@ -103,6 +104,7 @@ target_sources(TestingMacros PRIVATE
   Support/DiagnosticMessage+Diagnosing.swift
   Support/SourceCodeCapturing.swift
   Support/SourceLocationGeneration.swift
+  Support/TestContentGeneration.swift
   TagMacro.swift
   TestDeclarationMacro.swift
   TestingMacrosMain.swift)

Sources/TestingMacros/ConditionMacro.swift

@@ -435,11 +435,41 @@ extension ExitTestConditionMacro {
 
     // Create a local type that can be discovered at runtime and which contains
     // the exit test body.
-    let enumName = context.makeUniqueName("__🟠$exit_test_body__")
+    let enumName = context.makeUniqueName("")
+    let testContentRecordDecl = makeTestContentRecordDecl(
+      named: .identifier("testContentRecord"),
+      in: TypeSyntax(IdentifierTypeSyntax(name: enumName)),
+      ofKind: .exitTest,
+      accessingWith: .identifier("accessor")
+    )
+    decls.append(
+      """
+      #if hasFeature(SymbolLinkageMarkers)
+      @available(*, deprecated, message: "This type is an implementation detail of the testing library. Do not use it directly.")
+      enum \(enumName) {
+        private static let accessor: Testing.__TestContentRecordAccessor = { outValue, hint in
+          let id = \(exitTestIDExpr)
+          if let hintedID = hint?.load(as: Testing.__ExitTest.ID.self), hintedID != id {
+            return false
+          }
+          let outValue = outValue.assumingMemoryBound(to: Testing.__ExitTest.self)
+          outValue.initialize(to: .init(__identifiedBy: id, body: \(bodyThunkName)))
+          return true
+        }
+
+        \(testContentRecordDecl)
+      }
+      #endif
+      """
+    )
+
+#if !SWT_NO_LEGACY_TEST_DISCOVERY
+    // Emit a legacy type declaration if SymbolLinkageMarkers is off.
+    let legacyEnumName = context.makeUniqueName("__🟠$exit_test_body__")
     decls.append(
       """
       @available(*, deprecated, message: "This type is an implementation detail of the testing library. Do not use it directly.")
-      enum \(enumName): Testing.__ExitTestContainer, Sendable {
+      enum \(legacyEnumName): Testing.__ExitTestContainer, Sendable {
         static var __id: Testing.__ExitTest.ID {
           \(exitTestIDExpr)
         }
@@ -449,12 +479,16 @@ extension ExitTestConditionMacro {
       }
       """
     )
+#endif
 
     arguments[trailingClosureIndex].expression = ExprSyntax(
       ClosureExprSyntax {
         for decl in decls {
-          CodeBlockItemSyntax(item: .decl(decl))
-            .with(\.trailingTrivia, .newline)
+          CodeBlockItemSyntax(
+            leadingTrivia: .newline,
+            item: .decl(decl),
+            trailingTrivia: .newline
+          )
         }
       }
     )