# GPUX — Pure-Rust 8-Platform GPU Application Framework (Built on GPUI & GPUI-Kit)

> GPUX is a unified 8-platform application framework in pure Rust (`macOS`, `Linux`, `Windows`, `iOS`, `Android`, `HarmonyOS NEXT`, `Web WASM`, and `MiniProgram`). It combines GPUI's hardware-accelerated GPU rendering pipeline (Metal, Vulkan, DirectX 12, OpenHarmony XComponent, WebGPU/WebGL2), `gpui-kit` native components, zero-serialization in-process typed service bindings (`ServiceRegistry` at `1.2µs` call latency), and a unified packaging CLI (`gpux-cli`).

## Canonical URLs & Documentation Map

- Website Home: https://gpux.waya.ink/index.html
- Documentation Overview: https://gpux.waya.ink/guide/index.html
- System Prerequisites: https://gpux.waya.ink/guide/prerequisites.html
- Getting Started & 9-Ecosystem Installation: https://gpux.waya.ink/guide/getting-started.html
- Project Structure: https://gpux.waya.ink/guide/project-structure.html
- Unified Architecture & GPU Pipeline: https://gpux.waya.ink/guide/architecture.html
- Typed Service Bridge (`ServiceRegistry` & `app.bind`): https://gpux.waya.ink/guide/bindings.html
- Reactive State (`Store<T>`) & Navigation (`Router<R>`): https://gpux.waya.ink/guide/state-and-router.html
- 21 Themes & Design Tokens: https://gpux.waya.ink/guide/theming.html
- Fine-Grained Permissions & Security Model: https://gpux.waya.ink/guide/security.html
- Mobile (`iOS`, `Android`, `HarmonyOS NEXT`) Hosts: https://gpux.waya.ink/guide/mobile.html
- Web WASM & MiniProgram (`WeChat`, `Douyin`, `Alipay`) Hosts: https://gpux.waya.ink/guide/web-and-miniprogram.html
- CLI Reference (`/reference/cli`): https://gpux.waya.ink/reference/cli.html
- Configuration Reference (`gpux.json` Schema): https://gpux.waya.ink/reference/config.html
- Rust SDK API Reference: https://gpux.waya.ink/reference/rust-api.html
- Environment Variables Reference: https://gpux.waya.ink/reference/environment.html
- Packaging, Signing & CI/CD Distribution: https://gpux.waya.ink/guide/distribution.html
- Native UI Component Book (GPUI-Kit): https://gpux.waya.ink/ui/index.html
- System Capabilities & Official Plugins: https://gpux.waya.ink/plugins.html
- Verified Cross-Framework Benchmarks: https://gpux.waya.ink/benchmarks.html
- Showcase Gallery: https://gpux.waya.ink/showcase.html
- Releases & Roadmap: https://gpux.waya.ink/releases.html

## Workspace Crates Architecture

1. `gpux` (`crates/gpux`): Unified user-facing SDK (`gpux::prelude::*`, `Store<T>`, `Router<R>`, `ResponsiveContext`, `Breakpoint`, re-exports `gpux-core`, `gpux-bridge`, `gpux-desktop`, `gpux-mobile`, `gpux-web`, and `gpui-kit`).
2. `gpux-core` (`crates/gpux-core`): Platform-independent runtime:
   - `Platform`: `MacOS`, `Linux`, `Windows`, `Ios`, `Android`, `HarmonyOS`, `Web`, `MiniProgram`
   - `AppManifest`: Strongly-typed `gpux.json` configuration parser
   - `SafeAreaInsets`: Hardware display cutout / Dynamic Island / gesture bar / MiniProgram capsule insets
3. `gpux-bridge` (`crates/gpux-bridge`): Zero-macro typed service registry (`ServiceRegistry::register`, `call`, `call_raw`) and fine-grained permission model (`PermissionRegistry`).
4. `gpux-desktop` (`crates/gpux-desktop`): Desktop host for macOS, Linux, and Windows powered by GPUI and `gpui-kit` (`DesktopApp`, `run_with_view`).
5. `gpux-mobile` (`crates/gpux-mobile`): Mobile host (`MobileHost`, `TouchPhase`, `MobileBuildProfile`, `gpux_mobile_entry!`) for iOS (`aarch64-apple-ios`), Android (`aarch64-linux-android`), and HarmonyOS NEXT (`aarch64-unknown-linux-ohos`).
6. `gpux-web` (`crates/gpux-web`): Web & MiniProgram WASM host (`WebHost`, `WebHostConfig`, `WebBackend`, `WasmHostKind`, `WebFontFallback`, `run_web_with_view`) for `wasm32-unknown-unknown`.
7. `gpux-cli` (`crates/gpux-cli`): Developer CLI (`gpux init`, `gpux dev`, `gpux build`, `gpux doctor`, `gpux plugin`, `gpux permission`, `gpux icon`, `gpux migrate`).

## Idiomatic Quickstart Example

```rust
use gpux::prelude::*;
use gpux::kit::button::{Button, ButtonVariants};
use gpux::kit::{h_flex, v_flex, ActiveTheme, StyledExt};

pub struct TelemetryCard {
    store: Store<u64>,
    services: ServiceRegistry,
}

impl Render for TelemetryCard {
    fn render(&mut self, _window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
        let count = self.store.get();
        v_flex()
            .p_5()
            .gap_3()
            .bg(cx.theme().background)
            .text_color(cx.theme().foreground)
            .child(format!("Cluster Requests: {count}"))
            .child(
                h_flex().gap_2().child(
                    Button::new("sample-btn")
                        .primary()
                        .label("Sample Node")
                        .on_click(cx.listener(|this, _, _, cx| {
                            this.store.update(|n| *n += 1);
                            cx.notify();
                        })),
                ),
            )
    }
}
```

## CLI Commands Summary

- `gpux init <name> [--identifier com.example.app]`: Scaffold a new 8-platform GPUX project with `gpux.json`, `Cargo.toml`, and `src/main.rs`.
- `gpux dev [--target desktop|ios|android|harmonyos|web|miniprogram] [--port 1420]`: Launch the target runtime in development mode.
- `gpux doctor`: Inspect Rust, Cargo, and installed desktop/mobile/WASM cross-compilation targets.
- `gpux build --target <macos|linux|windows|ios|android|harmonyos|web|miniprogram> [--release]`: Compile and package for the specified target platform.
- `gpux plugin <list|add|remove>` & `gpux permission <list|add>`: Manage official plugins and fine-grained security capabilities.
- `gpux icon <source.png>` & `gpux migrate [--dry-run]`: Generate multi-platform icon sets and upgrade `gpux.json` schemas.