Crossa

Crossa is a compiler and native runtime that turns .cra sources into Android and iOS APIs.

Describe models, functions, and HTTP requests once. A single C++ frontend compiles them to typed IR. The same native runtime executes the work — networking, scheduling, decoding, and memory — and generated Kotlin and Swift APIs expose it as an AAR or XCFramework.

Foundation phase. The C++ frontend, typed IR, native HTTP/JSON runtime, Android AAR generation, iOS XCFramework generation, project linking, and CLI are available. Typed scalar/model/list responses use direct schema-aware decoding; explicit Json results use the generic JSON representation. Native-backed Android/iOS model and list views are available. Incremental streaming delivery remains post-V0, and the current closure audit is blocked by host sanitizer initialization.

Crossa in one minute

flowchart LR
    A[".cra sources"] --> B["C++ compiler frontend"]
    B --> C["Typed Crossa IR"]
    C --> D["Native C++ runtime"]
    D --> E["Android AAR"]
    D --> F["iOS XCFramework"]

Loading

• .cra is a small typed language for models, functions, and requests — not a general-purpose language.
• C++ is the only compiler frontend. It owns execution, networking, scheduling, and memory.
• Kotlin and Swift are thin integration surfaces. Crossa does not emit Retrofit, Ktor, Alamofire, or URLSession clients.

Get started

1. Install Crossa using the installation instructions.
2. Create a file named hello.cra:

fun add(a: Int, b: Int): Int {
    re a + b
}

print(add(1, 2))

3. Run it:

crossa run hello.cra

Output:

3

Validate source without executing functions or requests:

crossa check hello.cra

In a terminal, crossa with no arguments opens the interactive wizard.

A networking example

model User(
    id: Int,
    name: String
)

@AsyncAfter
fun getUser(id: Int): User {
    re CrossaRequest {
        url: "https://api.example.com/users/#id",
        method: GET
    }
}

User is the logical success type. With @AsyncAfter, the terminal result is one of:

Success(User)
Failed(CrossaError)
Cancelled

The native runtime plans the request, executes it over HTTP, decodes JSON into User, and delivers that terminal state through the generated platform API.

A complete imported example lives at examples/imports/runPosts.cra.

How a request moves through Crossa

flowchart TD
    A[".cra source"] --> B["Loader + lexer + parser"]
    B --> C["AST + semantic analysis"]
    C --> D["Typed IR"]
    D --> E["Native request plan"]
    E --> F["Bounded scheduler"]
    F --> G["HTTP transport + response buffer"]
    G --> H["JSON decoding + typed native model"]
    H --> I["Success / Failed / Cancelled"]

Loading

The CLI, Android, and iOS share this path. Kotlin and Swift do not parse .cra and do not implement a second HTTP runtime.

Why Crossa?

Instead of	Crossa
Repeating models and parsers on every platform	One typed .cra definition
Divergent Android and iOS networking stacks	One shared native runtime
Extra copies across native and managed heaps	Native-backed results where practical
A different client implementation per request	One frontend, one IR, one execution path
Manual SDK scaffolding for each app	Generated AAR and XCFramework artifacts

What is available today?

Area	Status
.cra loading, imports, lexer, parser, semantic analysis, and IR	Available
Variables, functions, models, List<T>, interpolation, print, and assert	Available
CrossaRequest with URL, path, query, headers, body, and HTTP methods	Available
JSON decoding for scalars, models, and lists	Available
Native scheduler, structured errors, and cancellation	Available
Kotlin generation	Available for pure translated IR
Generated @AsyncAfter Android and iOS APIs	Available
Android Gradle project and AAR generation	Available for arm64-v8a
iOS Debug/Release XCFramework generation	Available with Xcode and CMake
Android nested model/list result views	Available through native-backed ABI paths
Direct schema-aware typed decoders	Available for scalars, models, and lists; explicit Json remains generic
Streaming delivery to generated Android/iOS APIs	Post-V0; native transfer metrics are available while decoding remains buffered

Installation

Expand installation instructions

The installers download a compiled binary from GitHub Releases and verify it with SHA256SUMS. They do not clone this repository, require sudo, or edit shell profile files.

macOS ARM64 and Linux x86_64

curl -fsSL https://raw.githubusercontent.com/crossa-script/Crossa/main/scripts/install/install.sh | bash

To install a specific version:

curl -fsSL https://raw.githubusercontent.com/crossa-script/Crossa/main/scripts/install/install.sh | bash -s -- 0.1.0

Windows x86_64

To install the latest version:

irm https://raw.githubusercontent.com/crossa-script/Crossa/main/scripts/install/install.ps1 | iex

To install a specific version:

Invoke-WebRequest https://raw.githubusercontent.com/crossa-script/Crossa/main/scripts/install/install.ps1 -OutFile install.ps1
.\install.ps1 -Version 0.1.0

Installation location

macOS / Linux: ~/.crossa/bin/crossa
Windows:       %USERPROFILE%\.crossa\bin\crossa.exe

Set CROSSA_HOME before running the installer to use a different location. If the Crossa bin directory is not already on PATH, the installer prints the exact command to add it.

Supported release hosts

Operating system	Architecture	Release asset
macOS	ARM64 / Apple Silicon	crossa-vX.Y.Z-macos-arm64.tar.gz
Linux	x86_64	crossa-vX.Y.Z-linux-x86_64.tar.gz
Windows	x86_64	crossa-vX.Y.Z-windows-x86_64.zip

Verify the installation

crossa --version
crossa doctor

crossa doctor inspects the Crossa installation and any Android or iOS toolchains on the machine. It does not install dependencies or modify environment variables.

Platform outputs

flowchart LR
    A["Linked .cra project"] --> B["crossa generate-build android"]
    A --> C["crossa generate-build ios"]
    B --> D["Android Gradle project"] --> E["Debug / Release AAR"]
    C --> F["Xcode framework project"] --> G["Debug / Release XCFramework"]

Loading

Command	Output
crossa generate kotlin	Kotlin source for pure translated IR
crossa generate-build android	Android Gradle library project for AAR assembly
crossa generate-build ios	Xcode project and Debug/Release XCFrameworks

Project documentation

Current status

• V0 Closure Audit — current artifact, consumer, E2E, benchmark, and sanitizer-gate status.

Language and architecture

• Technical Architecture — system boundaries, ownership, and engineering rules.
• Language Foundation — current .cra syntax and semantics.
• Language Roadmap — implementation order and future milestones.
• Native Networking — request fields, response decoding, and limits.

Platforms

• Android AAR Generation — generated Android projects and build requirements.
• iOS XCFramework — XCFramework generation and Xcode integration.

Development

• Crossa CLI — commands, doctor, and interactive mode.
• Testing — test layers and fixtures.

Expand the full CLI reference

With stdin attached to a terminal, crossa with no arguments opens an interactive wizard. It collects a project root, source, and Android or iOS generation settings, prints the equivalent explicit command, then runs it. Enter accepts the displayed default; 0 goes back; 0 at the root exits. Non-TTY invocations never wait for input. --no-input makes that policy explicit.

Command	Purpose
crossa <file.cra>	Shortcut for crossa run <file.cra>
crossa run <file.cra>	Execute reachable top-level calls
crossa check <file.cra>	Validate source, imports, semantics, and IR without execution
crossa test <file.cra>	Run a source file with assertions
crossa generate kotlin <file.cra> --output <dir>	Generate Kotlin for pure IR
crossa generate-build android <project> --output <dir>	Generate an Android Gradle project
crossa generate-build ios <project> --output <dir>	Generate and build XCFrameworks
crossa doctor	Check the local toolchain
crossa --version	Print the installed version

Examples

crossa run examples/imports/runPosts.cra
crossa check examples/imports/runPosts.cra
crossa test tests/test-runner/pass.cra
crossa generate kotlin tests/kotlin-generator/Math.cra --output ./generated
crossa generate-build android ./crossa-project --output ./build/crossa-aar
crossa generate-build ios ./crossa-project --output ./build/crossa-xcframework

Show compiler and IR details during execution:

crossa run --debug test.cra

Android build tool versions can be overridden for one generated project:

crossa generate-build android ./crossa-project --output ./build/crossa-aar \
  --ndk-version 28.1.13356709 \
  --gradle-version 8.11.1 \
  --kotlin-version 2.1.10

Expand source-build and development instructions

Basic requirements are CMake, Ninja, a C++20 compiler, and libcurl. Android and iOS generation also requires the relevant platform toolchain.

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build
./build/crossa run test.cra

Run the complete local test suite:

./test.sh

JSONPlaceholder integration tests are optional because they require external network access:

CROSSA_RUN_NETWORK_INTEGRATION=1 ./test.sh

Architecture, ABI, IR, ownership, scheduler, transport, module-boundary, and major dependency changes require an ADR under docs/decisions/.

License

Crossa is available under the Apache License 2.0.