Mark image attachments as unavailable on non-Darwin/non-Windows. (#1330)

This PR explicitly marks the image attachments API bits in the core
Swift Testing library as unavailable on e.g. Linux. Developers who
attempt to use this API on Linux will get diagnostics such as:

> 🛑 'AttachableImageFormat' is unavailable: Image attachments are not
available on this platform.

Blocked on #1329.

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

Author: grynspan

.github/workflows/pull_request.yml

@@ -24,6 +24,6 @@ jobs:
     uses: swiftlang/github-workflows/.github/workflows/soundness.yml@main
     with:
       license_header_check_project_name: "Swift"
-      docs_check_container_image: "swift:6.2-noble"
+      docs_check_enabled: false
       format_check_enabled: false
       api_breakage_check_enabled: false

Package.swift

@@ -383,6 +383,7 @@ extension Array where Element == PackageDescription.SwiftSetting {
       .define("SWT_NO_DYNAMIC_LINKING", .whenEmbedded(or: .when(platforms: [.wasi]))),
       .define("SWT_NO_PIPES", .whenEmbedded(or: .when(platforms: [.wasi]))),
       .define("SWT_NO_FOUNDATION_FILE_COORDINATION", .whenEmbedded(or: .whenApple(false))),
+      .define("SWT_NO_IMAGE_ATTACHMENTS", .whenEmbedded(or: .when(platforms: [.linux, .custom("freebsd"), .openbsd, .wasi, .android]))),
 
       .define("SWT_NO_LEGACY_TEST_DISCOVERY", .whenEmbedded()),
       .define("SWT_NO_LIBDISPATCH", .whenEmbedded()),

Sources/Testing/Attachments/Images/AttachableImageFormat.swift

@@ -31,6 +31,9 @@
 /// @Metadata {
 ///   @Available(Swift, introduced: 6.3)
 /// }
+#if SWT_NO_IMAGE_ATTACHMENTS
+@available(*, unavailable, message: "Image attachments are not available on this platform.")
+#endif
 @available(_uttypesAPI, *)
 public struct AttachableImageFormat: Sendable {
   /// An enumeration describing the various kinds of image format that can be
@@ -77,6 +80,9 @@ public struct AttachableImageFormat: Sendable {
 
 // MARK: -
 
+#if SWT_NO_IMAGE_ATTACHMENTS
+@available(*, unavailable, message: "Image attachments are not available on this platform.")
+#endif
 @available(_uttypesAPI, *)
 extension AttachableImageFormat {
   /// The PNG image format.

Sources/Testing/Attachments/Images/Attachment+_AttachableAsImage.swift

@@ -8,6 +8,9 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
+#if SWT_NO_IMAGE_ATTACHMENTS
+@available(*, unavailable, message: "Image attachments are not available on this platform.")
+#endif
 @available(_uttypesAPI, *)
 extension Attachment {
   /// Initialize an instance of this type that encloses the given image.
@@ -101,6 +104,9 @@ extension Attachment {
 // MARK: -
 
 @_spi(Experimental) // STOP: not part of ST-0014
+#if SWT_NO_IMAGE_ATTACHMENTS
+@available(*, unavailable, message: "Image attachments are not available on this platform.")
+#endif
 @available(_uttypesAPI, *)
 extension Attachment where AttachableValue: AttachableWrapper, AttachableValue.Wrapped: _AttachableAsImage {
   /// The image format to use when encoding the represented image.

Sources/Testing/Attachments/Images/ImageAttachmentError.swift

@@ -11,6 +11,9 @@
 private import _TestingInternals
 
 /// A type representing an error that can occur when attaching an image.
+#if SWT_NO_IMAGE_ATTACHMENTS
+@available(*, unavailable, message: "Image attachments are not available on this platform.")
+#endif
 package enum ImageAttachmentError: Error {
 #if SWT_TARGET_OS_APPLE
   /// The image could not be converted to an instance of `CGImage`.
@@ -39,6 +42,9 @@ package enum ImageAttachmentError: Error {
 #endif
 }
 
+#if SWT_NO_IMAGE_ATTACHMENTS
+@available(*, unavailable, message: "Image attachments are not available on this platform.")
+#endif
 extension ImageAttachmentError: CustomStringConvertible {
   package var description: String {
 #if SWT_TARGET_OS_APPLE

Sources/Testing/Attachments/Images/_AttachableAsImage.swift

@@ -8,6 +8,14 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
+#if SWT_TARGET_OS_APPLE
+// Image attachments on Apple platforms conform to AttachableAsCGImage.
+#elseif os(Windows)
+// Image attachments on Windows platforms conform to AttachableAsIWICBitmapSource.
+#elseif !SWT_NO_IMAGE_ATTACHMENTS
+#error("Platform-specific misconfiguration: support for image attachments requires a platform-specific implementation")
+#endif
+
 /// A protocol describing images that can be converted to instances of
 /// [`Attachment`](https://developer.apple.com/documentation/testing/attachment).
 ///
@@ -18,6 +26,9 @@
 ///   A future Swift Evolution proposal will promote this protocol to API so
 ///   that we don't need to underscore its name.
 /// }
+#if SWT_NO_IMAGE_ATTACHMENTS
+@available(*, unavailable, message: "Image attachments are not available on this platform.")
+#endif
 @available(_uttypesAPI, *)
 public protocol _AttachableAsImage: SendableMetatype {
   /// Make a copy of this instance to pass to an attachment.

Sources/Testing/Attachments/Images/_AttachableImageWrapper.swift

@@ -20,6 +20,9 @@
 /// @Comment {
 /// | Windows | [`HBITMAP`](https://learn.microsoft.com/en-us/windows/win32/gdi/bitmaps), [`HICON`](https://learn.microsoft.com/en-us/windows/win32/menurc/icons), [`IWICBitmapSource`](https://learn.microsoft.com/en-us/windows/win32/api/wincodec/nn-wincodec-iwicbitmapsource) (including its subclasses declared by Windows Imaging Component) |
 /// }
+#if SWT_NO_IMAGE_ATTACHMENTS
+@available(*, unavailable, message: "Image attachments are not available on this platform.")
+#endif
 @available(_uttypesAPI, *)
 public final class _AttachableImageWrapper<Image>: Sendable where Image: _AttachableAsImage {
   /// The underlying image.
@@ -38,6 +41,9 @@ public final class _AttachableImageWrapper<Image>: Sendable where Image: _Attach
   }
 }
 
+#if SWT_NO_IMAGE_ATTACHMENTS
+@available(*, unavailable, message: "Image attachments are not available on this platform.")
+#endif
 @available(_uttypesAPI, *)
 extension _AttachableImageWrapper {
   public var wrappedValue: Image {

cmake/modules/shared/CompilerSettings.cmake

@@ -42,6 +42,9 @@ if(CMAKE_SYSTEM_NAME STREQUAL "WASI")
   add_compile_definitions("SWT_NO_DYNAMIC_LINKING")
   add_compile_definitions("SWT_NO_PIPES")
 endif()
+if (NOT (APPLE OR CMAKE_SYSTEM_NAME STREQUAL "Windows"))
+  add_compile_definitions("SWT_NO_IMAGE_ATTACHMENTS")
+endif()
 
 file(STRINGS "${SWT_SOURCE_ROOT_DIR}/VERSION.txt" SWT_TESTING_LIBRARY_VERSION LIMIT_COUNT 1)
 if(SWT_TESTING_LIBRARY_VERSION)