Skip to content

AGENTS.md

Latest commit

 

History

History
110 lines (83 loc) · 3.5 KB

AGENTS.md

File metadata and controls

110 lines (83 loc) · 3.5 KB

AGENTS.md

Project Overview

Swan is a Swift WebGPU binding library that provides Swift APIs for using WebGPU across multiple platforms. The initial implementation is a Swift binding to Google's Dawn library. This is currently a work-in-progress project not ready for production use.

Architecture

Core Components

  • WebGPU: Cross-platform facade that clients import. Conditionally re-exports WebGPUDawn (native) or WebGPUWasm (WASM)
  • WebGPUDawn: Native backend wrapping Dawn (macOS, Windows)
  • WebGPUWasm: WASM backend bridging to the browser's WebGPU API (WASI)
  • Dawn: Swift wrapper around Google's Dawn WebGPU implementation
  • CDawn: C bindings layer for Dawn
  • DawnData: Data structures and utilities for Dawn integration
  • GameOfLife: Demo/example application

Code Generation

The project uses Swift Package Manager plugins for code generation:

  • GenerateDawnBindingsPlugin: Generates Swift bindings from Dawn's C API
  • GenerateDawnAPINotesPlugin: Generates API notes for better Swift integration

Both plugins depend on executable targets that process dawn.json to generate appropriate Swift code.

Binary Dependencies

The project uses a binary target DawnLib that contains pre-built Dawn WebGPU libraries for multiple platforms (macOS, iOS, Linux, Windows). These are built via GitHub Actions and distributed as releases.

Development Commands

Building

You need to use the swift version that is defined in .swift-version. Please do so by ensuring that swiftly is first in the PATH variable:

export PATH="$HOME/.swiftly/bin:$PATH"

and let swiftly install and use the defined version:

swiftly install
swiftly use

It might be useful to clean up old artifacts when the version was changed. In that case run:

swift package clean

before finally running a build with:

swift build

WASM builds

The WASM SDK version is defined in .wasm-sdk-version. WASM builds need to set the swift-sdk and specify the WebGPU target in the build command:

BUILD_WASM=1 swift build --target WebGPU --swift-sdk $(cat .wasm-sdk-version)

Testing

swift test

Code Generation Plugins

# Generate Dawn API notes
swift package generate-dawn-apinotes

# Bindings are generated automatically during build via GenerateDawnBindingsPlugin

Code Formatting

The project uses swift-format with configuration in .swift-format:

  • Line length: 140 characters
  • Uses tabs for indentation
  • Ordered imports enabled

Platform Requirements

  • macOS 15+
  • iOS 18+
  • Swift 6.3+
  • Uses development snapshot toolchain (6.3-snapshot-2026-01-29)

Dependencies

  • swift-testing (for tests)
  • swift-log (for logging)
  • swift-syntax (for code generation)
  • swift-argument-parser (for CLI argument parsing)
  • swift-format (for code formatting)

Key Files

  • Package.swift: Swift Package Manager configuration
  • Dawn/ci_build_dawn.py: Python script for building dawn in CI
  • .wasm-sdk-version: WASM SDK version for cross-compilation to WebAssembly
  • .swift-format: Code formatting configuration
  • .vscode/settings.json: VS Code configuration with specific Swift toolchain path

Dawn Integration

The project maintains its own Dawn builds through GitHub Actions workflows that:

  1. Fetch specific Chromium/Dawn versions
  2. Build Dawn for multiple platforms
  3. Package as binary releases
  4. Update Package.swift with new binary target URLs

The Dawn source management and building is handled by Python scripts in the Dawn/ directory.