Proposed blog post: Improving the usability of C libraries in Swift #1255

DougGregor · 2025-12-07T01:29:01Z

Here is a draft blog post on improving the usability of C libraries in Swift using header annotations or API notes. I use the WebGPU headers as an example.

finagolfin · 2025-12-07T23:11:15Z

_posts/2025-12-15-improving-usability-of-c-libraries-in-swift.md

+
+There are many interesting, useful, and fun C libraries in the software ecosystem. While one could go and rewrite these libraries in Swift, usually there is no need, because Swift provides direct interoperability with C. With a little setup, you can directly use existing C libraries from your Swift code. 
+
+When you use a C library directly from Swift, it will look and feel similar to using it from C. That can be useful if you're following sample code or a tutorial written in C, but it can also feel out-of-place. For example, here's a small amount of code using a C API:


Suggested change

When you use a C library directly from Swift, it will look and feel similar to using it from C. That can be useful if you're following sample code or a tutorial written in C, but it can also feel out-of-place. For example, here's a small amount of code using a C API:

When you use a C library directly from Swift, it will look and feel similar to using it from C. That can be useful if you're following sample code or a tutorial written in C, but it can also feel out of place. For example, here's a small amount of code using a C API:

finagolfin · 2025-12-07T23:17:03Z

_posts/2025-12-15-improving-usability-of-c-libraries-in-swift.md

+{
+  "compilerVersion": "Apple Swift version 6.2 (swiftlang-6.2.2.15.4 clang-1700.3.15.2)",
+  "target": {
+    "triple": "arm64-apple-macosx15.0",


This doesn't match the triple you used above, ie arm64-apple-macos14.

heckj · 2025-12-08T17:59:56Z

_posts/2025-12-15-improving-usability-of-c-libraries-in-swift.md

+
+Fortunately, we can improve this situtation, providing a safer and more ergonomic interface to WebGPU from Swift that feels like it belongs in Swift. More importantly, we can do so without changing the WebGPU implementation: Swift provides a suite of annotations that you can apply to C headers to improve the way in which the C APIs are expressed in Swift. These annotations describe common conventions in C that match up with Swift constructs, projecting a more Swift-friendly interface on top of the C code.
+
+In this post, I'm going to leverage these annotations to improve how Swift interacts with WebGPU. By the end, we'll be able to take advantage of Swift features like argument labels, methods, enums, and automatic reference counting, like this:


Suggested change

In this post, I'm going to leverage these annotations to improve how Swift interacts with WebGPU. By the end, we'll be able to take advantage of Swift features like argument labels, methods, enums, and automatic reference counting, like this:

In this post, I'm going to use these annotations to improve how Swift interacts with the WebGPU C code. By the end, we'll be able to take advantage of Swift features like argument labels, methods, enums, and automatic reference counting, like this:

heckj · 2025-12-08T18:01:25Z

_posts/2025-12-15-improving-usability-of-c-libraries-in-swift.md

+
+I'm going to do it from the command line, using `swift-synthesize-interface`. From the directory containing `webgpu.h` and `module.modulemap`, run:
+
+```swift


swift-synthesize-interface isn't in the path by default - so maybe mention you'll either need an open source toolchain on your path, or prefix the command with xcrun to use the command with the version of Swift that Xcode provides.

heckj · 2025-12-08T18:02:22Z

_posts/2025-12-15-improving-usability-of-c-libraries-in-swift.md

+} WGPUAdapterType WGPU_ENUM_ATTRIBUTE;
+```
+
+will be translated into:


Suggested change

will be translated into:

is translated into:

heckj · 2025-12-08T18:02:38Z

_posts/2025-12-15-improving-usability-of-c-libraries-in-swift.md

+public var WGPUAdapterType_Force32: WGPUAdapterType { get }
+```
+
+and there will be lots of global functions like this:


Suggested change

and there will be lots of global functions like this:

and there are lots of global functions like this:

dempseyatgithub · 2025-12-08T19:02:38Z

_posts/2025-12-15-improving-usability-of-c-libraries-in-swift.md

+}
+```
+
+The easiest thing to do is to put `module.modulemap` alongside the header itself. For my experiment here, I put it in the root direction of my `webgpu-headers` checkout. If you're in a Swift package, put it into its own target with this layout:


Should be “root directory” instead of “root direction”.

heckj · 2025-12-08T22:44:43Z

blog/improving-usability-of-c-libraries-in-swift/webgpu_apinotes.swift

@@ -0,0 +1,341 @@
+#! swift -enable-bare-slash-regex
+


Suggested change

//===----------------------------------------------------------------------===//

//

// This source file is part of the Swift.org open source project

//

// Copyright (c) 2025 Apple Inc. and the Swift.org project authors

// Licensed under Apache License v2.0

//

// See LICENSE.txt for license information

// See CONTRIBUTORS.txt for the list of Swift.org project authors

//

// SPDX-License-Identifier: Apache-2.0

//

//===----------------------------------------------------------------------===//

I think this'll sort of the license/soundness check in CI

Proposed blog post: Improving the usability of C libraries in Swift

777d223

DougGregor requested review from a team, davelester, shahmishal, timsneath and tkremenek as code owners December 7, 2025 01:29

finagolfin reviewed Dec 7, 2025

View reviewed changes

heckj reviewed Dec 8, 2025

View reviewed changes

dempseyatgithub reviewed Dec 8, 2025

View reviewed changes

heckj reviewed Dec 8, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Proposed blog post: Improving the usability of C libraries in Swift #1255

Proposed blog post: Improving the usability of C libraries in Swift #1255

DougGregor commented Dec 7, 2025

Uh oh!

finagolfin Dec 7, 2025

Uh oh!

finagolfin Dec 7, 2025

Uh oh!

heckj Dec 8, 2025

Uh oh!

heckj Dec 8, 2025

Uh oh!

heckj Dec 8, 2025

Uh oh!

heckj Dec 8, 2025

Uh oh!

dempseyatgithub Dec 8, 2025

Uh oh!

heckj Dec 8, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		There are many interesting, useful, and fun C libraries in the software ecosystem. While one could go and rewrite these libraries in Swift, usually there is no need, because Swift provides direct interoperability with C. With a little setup, you can directly use existing C libraries from your Swift code.

		When you use a C library directly from Swift, it will look and feel similar to using it from C. That can be useful if you're following sample code or a tutorial written in C, but it can also feel out-of-place. For example, here's a small amount of code using a C API:


		Fortunately, we can improve this situtation, providing a safer and more ergonomic interface to WebGPU from Swift that feels like it belongs in Swift. More importantly, we can do so without changing the WebGPU implementation: Swift provides a suite of annotations that you can apply to C headers to improve the way in which the C APIs are expressed in Swift. These annotations describe common conventions in C that match up with Swift constructs, projecting a more Swift-friendly interface on top of the C code.

		In this post, I'm going to leverage these annotations to improve how Swift interacts with WebGPU. By the end, we'll be able to take advantage of Swift features like argument labels, methods, enums, and automatic reference counting, like this:

	In this post, I'm going to leverage these annotations to improve how Swift interacts with WebGPU. By the end, we'll be able to take advantage of Swift features like argument labels, methods, enums, and automatic reference counting, like this:
	In this post, I'm going to use these annotations to improve how Swift interacts with the WebGPU C code. By the end, we'll be able to take advantage of Swift features like argument labels, methods, enums, and automatic reference counting, like this:


		I'm going to do it from the command line, using `swift-synthesize-interface`. From the directory containing `webgpu.h` and `module.modulemap`, run:

		```swift

	and there will be lots of global functions like this:
	and there are lots of global functions like this:

+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2025 Apple Inc. and the Swift.org project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of Swift.org project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//

Proposed blog post: Improving the usability of C libraries in Swift #1255

Are you sure you want to change the base?

Proposed blog post: Improving the usability of C libraries in Swift #1255

Conversation

DougGregor commented Dec 7, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants