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

[ADKaster]

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:

• Code and documentation should follow the style of the Style Guide.
• If public symbols are renamed or modified, DocC references should be updated.

[ADKaster]

cc @compnerd

[ADKaster]

Hm. Chatting with Jonathan on Slack some more, it seems like the fact that this works with the Swift OSS toolchain on linux is a toolchain bug: we shouldn't be able to access the private module from user code.

Another alternative (with -enable-experimental-feature Extern) looks like this:

import Foundation

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 throws {
        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)
        }
    }
}

[grynspan]

@ADKaster Did you want to proceed with this PR?

[ADKaster]

@grynspan I've updated the PR to address your two comments and other discussions we had on slack. I'm not 100% sure on the formatting, but the example code as-is does work.

[grynspan]

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

[ADKaster]

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

[grynspan]

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.

[ADKaster]

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.

[grynspan]

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…? 😇

[ADKaster]

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.

[grynspan]

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.)

[stmontgomery]

nit

Suggested change

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

[stmontgomery]

I'd like to see at least a code comment related to failure tracking leading to a non-zero exit status. Bonus points for actually implementing that logic in the example code!