Skip to content

Commit 72afbb4

Browse files
authored
Documentation: Update CMake.md to use the ABI entry point (#828)
The SwiftPM entry point is unstable and the new ABIv0 entry point has already been added to the library. ### Motivation: Using the SwiftPM entry point when building tests from a CMake project as recommended in the documentation is outdated and unwise. ### Modifications: Replace the example with one using the new ABIv0 entry point. ### Result: CMake projects should stop relying on the SwiftPM entry point. ### Checklist: - [x] Code and documentation should follow the style of the [Style Guide](https://github.com/apple/swift-testing/blob/main/Documentation/StyleGuide.md). - [x] If public symbols are renamed or modified, DocC references should be updated.
1 parent 1932a1b commit 72afbb4

File tree

1 file changed

+24
-7
lines changed

1 file changed

+24
-7
lines changed

Documentation/CMake.md

Lines changed: 24 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -59,21 +59,38 @@ endif()
5959
## Add an entry point
6060

6161
You must include a source file in your test executable target with a
62-
`@main` entry point. The following example uses the SwiftPM entry point:
62+
`@main` entry point. The example main below requires the experimental
63+
`Extern` feature. The function `swt_abiv0_getEntryPoint` is exported
64+
from the swift-testing dylib. As such, its declaration could instead
65+
be written in a C header file with its own `module.modulemap`, or
66+
the runtime address could be obtained via
67+
[`dlsym()`](https://pubs.opengroup.org/onlinepubs/9799919799/functions/dlsym.html) or
68+
[`GetProcAddress()`](https://learn.microsoft.com/en-us/windows/win32/api/libloaderapi/nf-libloaderapi-getprocaddress).
6369

6470
```swift
65-
import Testing
71+
typealias EntryPoint = @convention(thin) @Sendable (_ configurationJSON: UnsafeRawBufferPointer?, _ recordHandler: @escaping @Sendable (_ recordJSON: UnsafeRawBufferPointer) -> Void) async throws -> Bool
72+
73+
@_extern(c, "swt_abiv0_getEntryPoint")
74+
func swt_abiv0_getEntryPoint() -> UnsafeRawPointer
6675

6776
@main struct Runner {
68-
static func main() async {
69-
await Testing.__swiftPMEntryPoint() as Never
77+
static func main() async throws {
78+
nonisolated(unsafe) let configurationJSON: UnsafeRawBufferPointer? = nil
79+
let recordHandler: @Sendable (UnsafeRawBufferPointer) -> Void = { _ in }
80+
81+
let entryPoint = unsafeBitCast(swt_abiv0_getEntryPoint(), to: EntryPoint.self)
82+
83+
if try await entryPoint(configurationJSON, recordHandler) {
84+
exit(EXIT_SUCCESS)
85+
} else {
86+
exit(EXIT_FAILURE)
87+
}
7088
}
7189
}
7290
```
7391

74-
> [!WARNING]
75-
> The entry point is expected to change to an entry point designed for other
76-
> build systems prior to the initial stable release of Swift Testing.
92+
For more information on the input configuration and output records of the ABI entry
93+
point, refer to the [ABI documentation](ABI/JSON.md).
7794

7895
## Integrate with CTest
7996

0 commit comments

Comments
 (0)