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/ABI/TestContent.md

@@ -0,0 +1,178 @@
+# Runtime-discoverable test content
+
+<!--
+This source file is part of the Swift.org open source project
+
+Copyright (c) 2024 Apple Inc. and the Swift project authors
+Licensed under Apache License v2.0 with Runtime Library Exception
+
+See https://swift.org/LICENSE.txt for license information
+See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+-->
+
+This document describes the format and location of test content that the testing
+library emits at compile time and can discover at runtime.
+
+> [!WARNING]
+> The content of this document is subject to change pending efforts to define a
+> Swift-wide standard mechanism for runtime metadata emission and discovery.
+> Treat the information in this document as experimental.
+
+## Basic format
+
+Swift Testing stores test content records in a dedicated platform-specific
+section in built test products:
+
+| Platform | Binary Format | Section Name |
+|-|:-:|-|
+| macOS, iOS, watchOS, tvOS, visionOS | Mach-O | `__DATA_CONST,__swift5_tests` |
+| Linux, FreeBSD, Android | ELF | `swift5_tests` |
+| WASI | Statically Linked | `swift5_tests`[^1] |
+| Windows | PE/COFF | `.sw5test`[^2] |
+
+[^1]: SwiftWasm effectively uses the ELF format for its images, however it is
+      currently always statically linked and runtime discovery is performed
+      using a different mechanism than what we use on other ELF-based platforms.
+[^2]: On Windows, the Swift compiler [emits](https://github.com/swiftlang/swift/blob/main/stdlib/public/runtime/SwiftRT-COFF.cpp)
+      leading and trailing padding into this section, both zeroed and of size
+      `MemoryLayout<UInt>.stride`. Code that walks this section can safely skip
+      over this padding.
+
+### Record headers
+
+Regardless of platform, all test content records created and discoverable by the
+testing library have the following layout:
+
+```swift
+typealias TestContentRecord = (
+  kind: UInt32,
+  version: UInt16,
+  reserved1: UInt16,
+  accessor: (@convention(c) (_ outValue: UnsafeMutableRawPointer, _ hint: UnsafeRawPointer?) -> CBool)?,
+  context: UInt,
+  reserved2: UInt
+)
+```
+
+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
+struct SWTTestContentRecord {
+  uint32_t kind;
+  uint16_t version;
+  uint16_t reserved1;
+  bool (* _Nullable accessor)(void *outValue, const void *_Null_unspecified hint);
+  uintptr_t context;
+  uintptr_t reserved2;
+};
+```
+
+### Record contents
+
+#### The kind field
+
+Each record's _kind_ determines how the record will be interpreted at runtime. A
+record's kind is a 32-bit unsigned value. The following kinds are defined:
+
+| As Hexadecimal | As [FourCC](https://en.wikipedia.org/wiki/FourCC) | Interpretation |
+|-:|:-:|-|
+| `0x00000000` | &ndash; | Reserved (**do not use**) |
+| `0x74657374` | `'test'` | Test or suite declaration |
+| `0x65786974` | `'exit'` | Exit test |
+
+<!-- When adding cases to this enumeration, be sure to also update the
+corresponding enumeration in TestContentGeneration.swift. -->
+
+#### The version field
+
+This field is currently always `0`. Implementations should ignore structures
+with other version values.
+
+#### The accessor field
+
+The function `accessor` is a C function. When called, it initializes the memory
+at its argument `outValue` to an instance of some Swift type and returns `true`,
+or returns `false` if it could not generate the relevant content. On successful
+return, the caller is responsible for deinitializing the memory at `outValue`
+when done with it.
+
+`accessor` is optional. If it is `nil`, the test content record is ignored. The
+testing library may, in the future, define record kinds that do not provide an
+accessor function (that is, they represent pure compile-time information only.)
+
+The second argument to this function, `hint`, is an optional input that can be
+passed to help the accessor function determine if its corresponding test content
+record matches what the caller is looking for. If the caller passes `nil` as the
+`hint` argument, the accessor behaves as if it matched (that is, no additional
+filtering is performed.)
+
+The concrete Swift type of the value written to `outValue` and the value pointed
+to by `hint` depend on the kind of record:
+
+- For test or suite declarations (kind `0x74657374`), the accessor produces an
+  asynchronous Swift function that returns an instance of `Test`:
+
+  ```swift
+  @Sendable () async -> Test
+  ```
+
+  This signature is not the signature of `accessor`, but of the Swift function
+  reference it writes to `outValue`. This level of indirection is necessary
+  because loading a test or suite declaration is an asynchronous operation, but
+  C functions cannot be `async`.
+
+  Test content records of this kind do not specify a type for `hint`. Always
+  pass `nil`.
+
+- For exit test declarations (kind `0x65786974`), the accessor produces a
+  structure describing the exit test (of type `__ExitTest`.)
+
+  Test content records of this kind accept a `hint` of type `SourceLocation`.
+  They only produce a result if they represent an exit test declared at the same
+  source location (or if the hint is `nil`.)
+
+#### The context field
+
+This field can be used by test content to store additional context for a test
+content record that needs to be made available before the accessor is called:
+
+- For test or suite declarations (kind `0x74657374`), this field contains a bit
+  mask with the following flags currently defined:
+
+  | Bit | Description |
+  |-:|-|
+  | `1 << 0` | This record contains a suite declaration |
+  | `1 << 1` | This record contains a parameterized test function declaration |
+
+  Other bits are currently always set to `0`, but may be used in the future.
+
+- For exit test declarations (kind `0x65786974`), this field is not used and
+  should be set to `0`.
+
+#### The reserved1 and reserved2 fields
+
+These fields are reserved for future use. Always set them to `0`.
+
+## Third-party test content
+
+Testing tools may make use of the same storage and discovery mechanisms by
+emitting their own test content records into the test record content section.
+
+Third-party test content should set the `kind` field to a unique value only used
+by that tool, or used by that tool in collaboration with other compatible tools.
+At runtime, Swift Testing ignores test content records with unrecognized `kind`
+values. To reserve a new unique `kind` value, open a [GitHub issue](https://github.com/swiftlang/swift-testing/issues/new/choose)
+against Swift Testing.
+
+The layout of third-party test content records must be compatible with that of
+`TestContentRecord` as specified above. Third-party tools are ultimately
+responsible for ensuring the values they emit into the test content section are
+correctly aligned and have sufficient padding; failure to do so may render
+downstream test code unusable.
+
+<!--
+TODO: elaborate further, give examples
+TODO: standardize a mechanism for third parties to produce `Test` instances
+      since we don't have a public initializer for the `Test` type.
+-->

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,106 @@ 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
+> [!NOTE]
+> You do not need to provide an implementation for the function
+> `enumerateTypeMetadataSections()` in `Discovery+Old.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. That implementation calls `dl_iterate_phdr()`
+in the GNU C Library to enumerate available metadata.
+
+If you are porting Swift Testing to Classic, `dl_iterate_phdr()` 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)
+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(macintosh)
++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 +241,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

@@ -152,6 +152,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/CMakeLists.txt

@@ -81,10 +81,13 @@ add_library(Testing
   Support/Locked.swift
   Support/SystemError.swift
   Support/Versions.swift
+  Discovery.swift
+  Discovery+Platform.swift
   Test.ID.Selection.swift
   Test.ID.swift
   Test.swift
   Test+Discovery.swift
+  Test+Discovery+Old.swift
   Test+Macro.swift
   Traits/Bug.swift
   Traits/Comment.swift