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

Documentation/Porting.md

@@ -66,7 +66,7 @@ platform-specific attention.
 > These errors are produced when the configuration you're trying to build has
 > conflicting requirements (for example, attempting to enable support for pipes
 > without also enabling support for file I/O.) You should be able to resolve
-> these issues by updating Package.swift and/or CompilerSettings.cmake.
+> these issues by updating `Package.swift` and/or `CompilerSettings.cmake`.
 
 Most platform dependencies can be resolved through the use of platform-specific
 API. For example, Swift Testing uses the C11 standard [`timespec`](https://en.cppreference.com/w/c/chrono/timespec)
@@ -123,69 +123,105 @@ Once the header is included, we can call `GetDateTime()` from `Clock.swift`:
 ## Runtime test discovery
 
 When porting to a new platform, you may need to provide a new implementation for
-`enumerateTypeMetadataSections()` in `Discovery.cpp`. Test discovery is
+`_testContentSectionBounds()` in `Discovery+Platform.swift`. Test discovery is
 dependent on Swift metadata discovery which is an inherently platform-specific
 operation.
 
-_Most_ platforms will be able to reuse the implementation used by Linux and
-Windows that calls an internal Swift runtime function to enumerate available
-metadata. If you are porting Swift Testing to Classic, this function won't be
-available, so you'll need to write a custom implementation instead. Assuming
-that the Swift compiler emits section information into the resource fork on
-Classic, you could use the [Resource Manager](https://developer.apple.com/library/archive/documentation/mac/pdf/MoreMacintoshToolbox.pdf)
+> [!NOTE]
+> You do not need to provide an implementation for the function
+> `enumerateTypeMetadataSections()` in `Discovery+Legacy.cpp`: it is present for
+> backwards compatibility with Swift 6.0 toolchains and will be removed in a
+> future release.
+
+_Most_ platforms in use today use the ELF image format and will be able to reuse
+the implementation used by Linux.
+
+Classic does not use the ELF image format, so you'll need to write a custom
+implementation of `_testContentSectionBounds()` instead. Assuming that the Swift
+compiler emits section information into the resource fork on Classic, you would
+use the [Resource Manager](https://developer.apple.com/library/archive/documentation/mac/pdf/MoreMacintoshToolbox.pdf)
 to load that information:
 
 ```diff
---- a/Sources/_TestingInternals/Discovery.cpp
-+++ b/Sources/_TestingInternals/Discovery.cpp
+--- a/Sources/Testing/Discovery+Platform.swift
++++ b/Sources/Testing/Discovery+Platform.swift
 
  // ...
-+#elif defined(macintosh)
-+template <typename SectionEnumerator>
-+static void enumerateTypeMetadataSections(const SectionEnumerator& body) {
-+  ResFileRefNum refNum;
-+  if (noErr == GetTopResourceFile(&refNum)) {
-+    ResFileRefNum oldRefNum = refNum;
-+    do {
-+      UseResFile(refNum);
-+      Handle handle = Get1NamedResource('swft', "\p__swift5_types");
-+      if (handle && *handle) {
-+        auto imageAddress = reinterpret_cast<const void *>(static_cast<uintptr_t>(refNum));
-+        SWTSectionBounds sb = { imageAddress, *handle, GetHandleSize(handle) };
-+        bool stop = false;
-+        body(sb, &stop);
-+        if (stop) {
-+          break;
-+        }
-+      }
-+    } while (noErr == GetNextResourceFile(refNum, &refNum));
-+    UseResFile(oldRefNum);
++#elseif os(Classic)
++private func _testContentSectionBounds() -> [SectionBounds] {
++  let oldRefNum = CurResFile()
++  defer {
++    UseResFile(oldRefNum)
 +  }
++
++  var refNum = ResFileRefNum(0)
++  guard noErr == GetTopResourceFile(&refNum) else {
++    return []
++  }
++
++  var result = [SectionBounds]()
++  repeat {
++    UseResFile(refNum)
++    guard let handle = Get1NamedResource(ResType("swft"), Str255("__swift5_tests")) else {
++      continue
++    }
++    let sb = SectionBounds(
++      imageAddress: UnsafeRawPointer(bitPattern: UInt(refNum)),
++      start: handle.pointee!,
++      size: GetHandleSize(handle)
++    )
++    result.append(sb)
++  } while noErr == GetNextResourceFile(refNum, &refNum))
++  return result
 +}
  #else
- #warning Platform-specific implementation missing: Runtime test discovery unavailable (dynamic)
- template <typename SectionEnumerator>
- static void enumerateTypeMetadataSections(const SectionEnumerator& body) {}
+ private func _testContentSectionBounds() -> [SectionBounds] {
+   #warning("Platform-specific implementation missing: Runtime test discovery unavailable (dynamic)")
+   return []
+ }
  #endif
 ```
 
+You will also need to update the `makeTestContentRecordDecl()` function in the
+`TestingMacros` target to emit the correct `@_section` attribute for your
+platform. If your platform uses the ELF image format and supports the
+`dl_iterate_phdr()` function, add it to the existing `#elseif os(Linux) || ...`
+case. Otherwise, add a new case for your platform:
+
+```diff
+--- a/Sources/TestingMacros/Support/TestContentGeneration.swift
++++ b/Sources/TestingMacros/Support/TestContentGeneration.swift
+   // ...
++  #elseif os(Classic)
++  @_section(".rsrc,swft,__swift5_tests")
+   #else
+   @__testing(warning: "Platform-specific implementation missing: test content section name unavailable")
+   #endif
+```
+
+Keep in mind that this code is emitted by the `@Test` and `@Suite` macros
+directly into test authors' test targets, so you will not be able to use
+compiler conditionals defined in the Swift Testing package (including those that
+start with `"SWT_"`).
+
 ## Runtime test discovery with static linkage
 
 If your platform does not support dynamic linking and loading, you will need to
 use static linkage instead. Define the `"SWT_NO_DYNAMIC_LINKING"` compiler
-conditional for your platform in both Package.swift and CompilerSettings.cmake,
-then define the `sectionBegin` and `sectionEnd` symbols in Discovery.cpp:
+conditional for your platform in both `Package.swift` and
+`CompilerSettings.cmake`, then define the `testContentSectionBegin` and
+`testContentSectionEnd` symbols in `Discovery.cpp`:
 
 ```diff
 diff --git a/Sources/_TestingInternals/Discovery.cpp b/Sources/_TestingInternals/Discovery.cpp
  // ...
 +#elif defined(macintosh)
-+extern "C" const char sectionBegin __asm__("...");
-+extern "C" const char sectionEnd __asm__("...");
++extern "C" const char testContentSectionBegin __asm__("...");
++extern "C" const char testContentSectionEnd __asm__("...");
  #else
  #warning Platform-specific implementation missing: Runtime test discovery unavailable (static)
- static const char sectionBegin = 0;
- static const char& sectionEnd = sectionBegin;
+ static const char testContentSectionBegin = 0;
+ static const char& testContentSectionEnd = testContentSectionBegin;
  #endif
 ```
 
@@ -204,12 +240,12 @@ diff --git a/Sources/_TestingInternals/Discovery.cpp b/Sources/_TestingInternals
 +#elif defined(macintosh)
 +extern "C" const char __linker_defined_begin_symbol;
 +extern "C" const char __linker_defined_end_symbol;
-+static const auto& sectionBegin = __linker_defined_begin_symbol;
-+static const auto& sectionEnd = __linker_defined_end_symbol;
++static const auto& testContentSectionBegin = __linker_defined_begin_symbol;
++static const auto& testContentSectionEnd = __linker_defined_end_symbol;
  #else
  #warning Platform-specific implementation missing: Runtime test discovery unavailable (static)
- static const char sectionBegin = 0;
- static const char& sectionEnd = sectionBegin;
+ static const char testContentSectionBegin = 0;
+ static const char& testContentSectionEnd = testContentSectionBegin;
  #endif
 ```
 

Package.swift

@@ -155,6 +155,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/ExitTests/ExitTest.swift

@@ -248,6 +248,7 @@ extension ExitTest {
       }
     }
 
+#if !SWT_NO_LEGACY_TEST_DISCOVERY
     if result == nil {
       // Call the legacy lookup function that discovers tests embedded in types.
       enumerateTypes(withNamesContaining: exitTestContainerTypeNameMagic) { _, type, stop in
@@ -264,6 +265,7 @@ extension ExitTest {
         }
       }
     }
+#endif
 
     return result
   }

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
@@ -79,3 +80,4 @@ func enumerateTypes(withNamesContaining nameSubstring: String, _ typeEnumerator:
     }
   }
 }
+#endif

Sources/Testing/Test+Discovery.swift

@@ -55,6 +55,7 @@ extension Test: TestContent {
         }
       }
 
+#if !SWT_NO_LEGACY_TEST_DISCOVERY
       if discoveryMode != .newOnly && generators.isEmpty {
         enumerateTypes(withNamesContaining: testContainerTypeNameMagic) { imageAddress, type, _ in
           guard let type = type as? any __TestContainer.Type else {
@@ -65,6 +66,7 @@ extension Test: TestContent {
           }
         }
       }
+#endif
 
       // *Now* we call all the generators and return their results.
       // Reduce into a set rather than an array to deduplicate tests that were

Sources/Testing/Test+Macro.swift

@@ -505,6 +505,18 @@ extension Test {
   semantics arguments: _const String...
 ) = #externalMacro(module: "TestingMacros", type: "PragmaMacro")
 
+/// A macro used similarly to `#warning()` but in a position where only an
+/// attribute is valid.
+///
+/// - Parameters:
+///   - message: A string to emit as a warning.
+///
+/// - Warning: This macro is used to implement other macros declared by the
+///   testing library. Do not use it directly.
+@attached(peer) public macro __testing(
+  warning message: _const String
+) = #externalMacro(module: "TestingMacros", type: "PragmaMacro")
+
 // MARK: - Helper functions
 
 /// A function that abstracts away whether or not the `try` keyword is needed on

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

@@ -431,11 +431,58 @@ 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 accessorName = context.makeUniqueName("")
+    let outValueArgumentName = context.makeUniqueName("outValue")
+    let hintArgumentName = context.makeUniqueName("hint")
+    let sourceLocationLocalName = context.makeUniqueName("sourceLocation")
+    decls.append(
+      """
+      #if hasFeature(SymbolLinkageMarkers)
+      func \(accessorName)(_ \(outValueArgumentName): UnsafeMutableRawPointer, _ \(hintArgumentName): UnsafeRawPointer?) -> Bool {
+        let \(sourceLocationLocalName) = \(createSourceLocationExpr(of: macro, context: context))
+        if let \(hintArgumentName) = \(hintArgumentName)?.load(as: Testing.SourceLocation.self),
+          \(hintArgumentName) != \(sourceLocationLocalName) {
+          return false
+        }
+        \(outValueArgumentName).initializeMemory(
+          as: Testing.__ExitTest.self,
+          to: .init(
+            __expectedExitCondition: \(arguments[expectedExitConditionIndex].expression.trimmed),
+            sourceLocation: \(sourceLocationLocalName),
+            body: \(bodyThunkName)
+          )
+        )
+        return true
+      }
+      #endif
+      """
+    )
+
+    let enumName = context.makeUniqueName("")
+    let sectionContent = makeTestContentRecordDecl(
+      named: .identifier("__sectionContent"),
+      in: TypeSyntax(IdentifierTypeSyntax(name: enumName)),
+      ofKind: .exitTest,
+      accessingWith: accessorName
+    )
+    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) {
+        \(sectionContent)
+      }
+      #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 __sourceLocation: Testing.SourceLocation {
           \(createSourceLocationExpr(of: macro, context: context))
         }
@@ -448,6 +495,7 @@ extension ExitTestConditionMacro {
       }
       """
     )
+#endif
 
     arguments[trailingClosureIndex].expression = ExprSyntax(
       ClosureExprSyntax {

Sources/TestingMacros/PragmaMacro.swift

@@ -17,7 +17,9 @@ public import SwiftSyntaxMacros
 ///
 /// - `@__testing(semantics: "nomacrowarnings")`: suppress warning diagnostics
 ///   generated by macros. (The implementation of this use case is held in trust
-///   at ``MacroExpansionContext/areWarningsSuppressed``.
+///   at ``MacroExpansionContext/areWarningsSuppressed``.)
+/// - `@__testing(warning: "...")`: emits `"..."` as a diagnostic message
+///   attributed to the node to which the attribute is attached.
 ///
 /// This type is used to implement the `@__testing` attribute macro. Do not use
 /// it directly.
@@ -27,6 +29,17 @@ public struct PragmaMacro: PeerMacro, Sendable {
     providingPeersOf declaration: some DeclSyntaxProtocol,
     in context: some MacroExpansionContext
   ) throws -> [DeclSyntax] {
+    if case let .argumentList(arguments) = node.arguments,
+       arguments.first?.label?.textWithoutBackticks == "warning" {
+      let targetNode = Syntax(declaration)
+      let messages = arguments
+        .map(\.expression)
+        .compactMap { $0.as(StringLiteralExprSyntax.self) }
+        .compactMap(\.representedLiteralValue)
+        .map { DiagnosticMessage(syntax: targetNode, message: $0, severity: .warning) }
+      context.diagnose(messages)
+    }
+
     return []
   }