Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation: Update CMake.md to use the ABI entry point #828

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Documentation: Update CMake.md to use the ABI entry point #828

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5cd77e7
Documentation: Update CMake.md to use the ABI entry point
ADKaster Nov 17, 2024
c45c801
Documentation: Update custom entry point to not use SPI symbols
ADKaster Dec 10, 2024
c6af86b
Don't forget to import Foundation for exit()
ADKaster Dec 10, 2024
5dfdad4
Revert "Don't forget to import Foundation for exit()"
ADKaster Dec 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 22 additions & 7 deletions Documentation/CMake.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,21 +59,36 @@ endif()
## Add an entry point

You must include a source file in your test executable target with a
`@main` entry point. The following example uses the SwiftPM entry point:
`@main` entry point. The example main below requires the experimental
`Extern` feature. The declaration of `swt_abiv0_getEntryPoint` could
also be written in a C header file with its own `module.modulemap`.

```swift
import Testing
import Foundation
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't need this import for the barebones implementation below. Only needed if you want to use JSONEncoder/JSONDecoder.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it not needed for exit(EXIT_SUCCESS)? Or is there a non-foundation way to do the standard Unix process exit dance.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

exit() and EXIT_SUCCESS are defined in the system's C module, which may be Darwin, Glibc, ucrt… uh… Musl?

Foundation reexports the C module for the current system. It seems wrong to me (but I can be convinced otherwise) to tell developers to include a full Foundation dependency just for exit().

Depending on the dev's specific requirements, they really just need the process to terminate with zero (the default!) or non-zero. If they're using Swift Argument Parser, it has built-in functionality for this. If they're using just the Swift stdlib and nothing else, they could call fatalError() on failure. I don't know what's the best choice for this example code.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Eh.. I'm not sure that I know what the best choice is either. When a test binary is executed by ctest, as in my use case, returning 0 or 1 from main() is important for the test harness to understand whether the test passed or failed. Anything more than that on the ctest side is up to whatever @etcwilde comes up with for https://gitlab.kitware.com/cmake/cmake/-/issues/26452

I feel like adding a

#if canImport(GlibC)
#import GlibC
#elseif canImport(YourCLibModule)
#import YourCLibModule
#endif

chain to the top of the example would get in the way of what it's actually trying to show that you need 🤷

I'll change it to whatever anyone feels strongly about though, as in theory more comprehensive support for the CMake use case could come soon ™️ to make this example obsolete-ish.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It may be sufficient to just show exit(EXIT_SUCCESS) without importing anything. Developers who are going down this path are presumably skilled enough to figure out how to make it compile…? 😇

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure... "compilable example code left as an exercise for the reader" is definitely one approach. Not my first choice, but it's not my library :). I've pushed up that change then.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, anybody who's digging down into the CMake scripts is on their own and I have to assume has some esoteric environment—we can't even guarantee Foundation is present! (We can guarantee libc is present because we won't build without it, at least.)


typealias EntryPoint = @convention(thin) @Sendable (_ configurationJSON: UnsafeRawBufferPointer?, _ recordHandler: @escaping @Sendable (_ recordJSON: UnsafeRawBufferPointer) -> Void) async throws -> Bool

@_extern(c, "swt_abiv0_getEntryPoint")
func swt_abiv0_getEntryPoint() -> UnsafeRawPointer

@main struct Runner {
static func main() async {
await Testing.__swiftPMEntryPoint() as Never
static func main() async throws {
nonisolated(unsafe) let configurationJSON: UnsafeRawBufferPointer? = nil
let recordHandler: @Sendable (UnsafeRawBufferPointer) -> Void = { _ in }

let entryPoint = unsafeBitCast(swt_abiv0_getEntryPoint(), to: EntryPoint.self)

if try await entryPoint(configurationJSON, recordHandler) {
exit(EXIT_SUCCESS)
} else {
exit(EXIT_FAILURE)
}
}
}
```

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit

Suggested change
point, refer to the [ABI documentation](ABI/JSON.md)
point, refer to the [ABI documentation](ABI/JSON.md).


## Integrate with CTest

Expand Down