xplatter

xplatter takes an API spec and generates performant bindings for every major user-facing platform's natural app development language.

Define a performance-critical API and implement it once in the cross-platform system language of your choice and get a set of ready-to-use, idiomatic API packages for mobile, web, and desktop.

Why

AI makes exploring solution space much faster and cheaper, but it still takes human and inference effort to keep it on track. Bindings and glue code are highly rote and very finicky. They require perfect predictability & repeatability. Tradional mechanistic code gen is faster, cheaper, more reliable for this application. It allows token budgets and human attention to be spent on solving the problem instead of maintaining the scaffold.

Who

This tool benefits projects that need to deliver performance critical logic behind platform-natural U/X across multiple (or all) user-facing platforms - Android, iOS, mobile web, desktop web, Linux, macOS, Windows. Examples would be projects implementing on-device inference, media processing, advanced rendering, or any other custom cpu/gpu intensive work.

Quick Start

Prerequisites

Go 1.25+ for building the tool and go backed implementation example
- Linux:
  - this did NOT work for me on WSL2: sudo apt install golang
  - this did: GO_VERSION=1.26.0 && curl -sL https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz | tar -C ${HOME}/.local -xzf -
    - if you are replacing an existing installation be sure to remove the old installation first.
    - add ${HOME}/.local/go/bin to PATH or make symbolic links in ${HOME}/.local/bin to go and gofmt
- macOS: brew install go
- Windows: winget install GoLang.Go
flatc FlatBuffers compiler for per-language struct codegen
- Linux: sudo snap install flatbuffers
- macOS: brew install flatbuffers
- Windows: winget install flatbuffers
standard build tools
- Linux: sudo apt install build-essential clang cmake
- macOS:
  - Xcode and Xcode command line tools
  - brew install cmake
- Windows:
  - !NOTE! run all make commands on Windows from git bash.
  - Gnu make: winget install -e --id GnuWin32.Make
    - OR if Android NDK installed, add ${ANDROID_NDK}/prebuilt/windows-x86_64/bin to PATH
  - winget install zig (cgo on windows needs a drop-in compiler replacement that is clang-compatible)
    - trust me. this is the easy path.
  - Install Visual Studio with C++ workload for desktop (not Visual Studio Code)
    - You may be able to just install the command line SDK but that path has not been tested
  - winget install cmake
npm or python3
- only used for running/testing WASM example
- examples/app-web/serve.sh will use either to start a CLI one-liner local http server to serve up JS and WASM files
- no virtual env or language-specific project setup needed

Only the tools for your selected target platforms are required — see Platform Tooling below.

Build

make build

This produces bin/xplatter.

Run

# Generate bindings from an API definition
bin/xplatter generate docs/example_api_definition.yaml -o generated

# Validate an API definition without generating
bin/xplatter validate docs/example_api_definition.yaml

# Scaffold a new project
bin/xplatter init --name my_api --impl-lang cpp

Run the Examples

Working examples with API implementations in C, C++, Rust, and Go with front end consumer apps targeting mobile, desktop, and web live under examples/. hello-xplatter defines a simple greeter API. All examples generate bindings, implement them, and run tests.

# Run all implementation examples
cd examples
make test-hello-impl-all

# Run individually
make test-hello-impl-c
make test-hello-impl-cpp
make test-hello-impl-rust
make test-hello-impl-go

# Run app examples (consumer-side binding usage)
make test-hello-app-all               # all apps
make test-hello-app-desktop-cpp
make test-hello-app-desktop-swift     # macOS only
make test-hello-app-ios               # macOS only (builds for simulator)
make test-hello-app-android           # requires Android SDK + NDK
make test-hello-app-web               # requires Emscripten

Run the Tests

make test          # all Go unit tests
make test-v        # verbose
make validate      # validate the example API definition

User Workflow

Define your API in YAML
Define your data types in FlatBuffers schemas (.fbs files)
Run xplatter generate your_api.yaml -o generated
Implement the generated abstract interface in your language (C++, Rust, Go, or plain C)
Build your implementation against the generated C header and shim
1. xplatter should be integrated into your project build system as a code gen dependency
Minimal installation
1. You only need xplatter.sh and the contents of bin/
2. The rest of the SDK is doc and examples.

The examples/hello-xplatter/ directory shows this workflow end-to-end for each supported language.

What It Generates

Pure C API header — the universal contract, including handle typedefs, FlatBuffer type definitions, platform service declarations, and export-annotated API functions
Kotlin + JNI bridge — idiomatic Kotlin API for Android
Swift + C bridge — idiomatic Swift API for iOS and macOS
JavaScript + WASM bindings — idiomatic JS API for web
Implementation interface + C ABI shim + stub implementation — for C, C++, Rust, or Go (controlled by impl_lang in the API definition)
Makefile + platform service stubs — build rules and platform-specific logging/resource stubs

Project Structure

src/                    Go source for the code gen tool
  gen/                  All code generators (cheader, impl_c, impl_cpp, impl_rust, impl_go, kotlin, swift, jswasm, makefiles, platform_services)
  cmd/                  CLI commands (generate, validate, init, dump_schema, version)
  model/                API model types and type system
  loader/               YAML loading
  resolver/             FlatBuffers schema parsing and type resolution
  validate/             Semantic validation
  testdata/             Test fixtures and golden files
examples/               Working hello-world examples in C, C++, Rust, Go
docs/                   Specifications, schemas, and example definitions
specs/                  FlatBuffers spec files

Documentation

Agent Guide — operational guide for AI coding agents
Architecture Overview — system layers, C ABI boundary rules, design rationale
Code Generation Specification — complete reference for all generators, type mappings, output files, naming conventions, symbol visibility
API Definition Specification — full reference for the YAML format
Example API Definition — working example demonstrating the YAML format
API Definition JSON Schema — machine-readable schema for validation and editor support

Platform Tooling

Not all targets can be built on every host OS. Only the tools for your selected targets are required.

Implementation Examples

These build and test the API implementation in each supported language. They run on any host OS with the appropriate compiler.

Example	Required Tools
C (`test-example-c`)	C11 compiler (clang)
C++ (`test-example-cpp`)	C++20 compiler (clang++), C11 compiler
Rust (`test-example-rust`)	Rust toolchain (rustc + cargo)
Go (`test-example-go`)	Go 1.25+, cgo-compatible C compiler

App Examples

These build consumer-facing apps that use the generated bindings. Platform availability depends on the host OS.

App	Host OS	Required Tools
Desktop C++ (`test-app-desktop-cpp`)	macOS, Linux	C++20 compiler, shared library from any impl backend
Desktop Swift (`test-app-desktop-swift`)	macOS	Swift compiler (`swiftc`), shared library from any impl backend
iOS (`test-app-ios`)	macOS	Xcode (provides `xcrun`, `xcodebuild`, `lipo`, `ar`, `swiftc`)
Android (`test-app-android`)	macOS, Linux, Windows	Android SDK, NDK r29+, JDK 17+
Web/WASM (`test-app-web`)	macOS, Linux, Windows	Emscripten (`emcc`)

Host OS / Target Matrix

Host OS	Buildable Targets
macOS	Desktop (C++ and Swift), iOS, Android, Web
Linux	Desktop (C++ only), Android, Web, Linux native
Windows	Android, Web, Windows native

Make Targets

Root Makefile:

Target	Description
`build`	Build `bin/xplatter` for the current platform
`test`	Run all Go unit tests
`test-v`	Run tests with verbose output
`test-examples-hello-impl-app-matrix`	Build all hello impls and test all apps against all impls
`validate`	Validate the example API definition
`dist`	Build cross-platform SDK archive
`fmt`	Format all Go source
`vet`	Run `go vet`
`clean`	Remove build artifacts

Examples Makefile (run from examples/):

Target	Description
`test-hello-impl-all`	Build and run all implementation examples
`test-hello-impl-c`	Run the C implementation example
`test-hello-impl-cpp`	Run the C++ implementation example
`test-hello-impl-rust`	Run the Rust implementation example
`test-hello-impl-go`	Run the Go implementation example
`test-hello-app-all`	Build and test all app examples
`test-hello-app-desktop-cpp`	Build and test the C++ desktop app
`test-hello-app-desktop-swift`	Build and test the Swift desktop app (macOS only)
`test-hello-app-ios`	Build the iOS app for simulator (macOS only)
`test-hello-app-android`	Build the Android app (requires Android SDK + NDK)
`test-hello-app-web`	Build the Web/WASM app (requires Emscripten)

Design Overview

Implementation language agnostic — any language that can export a Pure C ABI and compile to WASM with C ABI exports is a valid implementation choice. The generated bindings work the same regardless of what's behind the C ABI boundary.

Borrowing-only FFI boundary — the side that allocates is the side that deallocates. No ownership transfer, no release callbacks, no ref-counting across the boundary.

No callbacks — the C ABI is strictly unidirectional (bound language calls implementation). The implementation communicates back via a shared ring buffer with platform-native signaling.

Symbol visibility — generated shared libraries export only API-defined symbols via a per-API export macro. Platform services are link-time provided, not exported.

FlatBuffers for all data types — provides the type system, per-language struct codegen, zero-copy serialization, and binary-compatible data across platforms.

YAML + JSON Schema — API definitions are human-authored YAML validated by a JSON Schema, with editor autocompletion and inline validation support.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 194 Commits
.claude		.claude
.opencode/agents		.opencode/agents
docs		docs
examples		examples
specs		specs
src		src
.agentignore		.agentignore
.gitignore		.gitignore
AGENTS.md		AGENTS.md
ARCHITECTURE.md		ARCHITECTURE.md
LICENSE.md		LICENSE.md
Makefile		Makefile
README.md		README.md
TODO.md		TODO.md
TOMBSTONE.md		TOMBSTONE.md
USER_README.md		USER_README.md
build_codegen.sh		build_codegen.sh
xplatter.sh		xplatter.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

xplatter

Why

Who

Quick Start

Prerequisites

Build

Run

Run the Examples

Run the Tests

User Workflow

What It Generates

Project Structure

Documentation

Platform Tooling

Implementation Examples

App Examples

Host OS / Target Matrix

Make Targets

Design Overview

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

xplatter

Why

Who

Quick Start

Prerequisites

Build

Run

Run the Examples

Run the Tests

User Workflow

What It Generates

Project Structure

Documentation

Platform Tooling

Implementation Examples

App Examples

Host OS / Target Matrix

Make Targets

Design Overview

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages