Simply Patrick

Rust Proc Macro：builder-derive 實戰

February 13, 2026 programming rust proc-macro derive builder ai-assisted codex

最近在看 builder-derive 這個小專案時，會再次被 Rust 的 procedural macro 驚艷到：

你在程式碼裡只寫一行 #[derive(Builder)]，編譯器就幫你生出一整套 Builder API。

但它到底怎麼做到的？

這篇就用 builder-derive 的實作，從 TokenStream 一路追到實際生成的程式碼，拆解 Rust proc macro 的完整流程。

先看使用端：我們到底得到了什麼

先看最終使用方式：

use builder_derive::Builder;

#[derive(Builder, Debug)]
struct User {
    username: String,
    email: String,
    age: Option<u32>,
    tags: Vec<String>,
}

let user = User::builder()
    .username("alice".to_string())
    .email("[email protected]".to_string())
    .age(30)
    .build()?;

這裡我們沒有手寫 UserBuilder，也沒有手寫 setter、build()。

#[derive(Builder)] 在編譯期把這些東西全部產生出來。

Proc Macro 的核心心法：編譯期程式碼產生器

很多人第一次接觸 macro 會覺得它像「文字替換」。 Rust 的 procedural macro 比這個更嚴謹：

編譯器把你標註 derive 的語法轉成 TokenStream
macro crate 用 syn 把 token parse 成 AST（語法樹）
你在 AST 上做檢查與分析
用 quote 產生新的 Rust tokens 丟回編譯器
編譯器把這段新程式碼當成真的程式去編譯

builder-derive 的模組切分很清楚：

src/lib.rs：入口
src/parse.rs：輸入合法性檢查
src/field.rs：欄位型別分析
src/generate.rs：程式碼生成

第 1 步：入口函式（lib.rs）

builder-derive 的入口非常典型：

#[proc_macro_derive(Builder)]
pub fn derive_builder(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);

    match generate::impl_builder(&input) {
        Ok(tokens) => tokens.into(),
        Err(e) => e.to_compile_error().into(),
    }
}

這段有三個重點：

#[proc_macro_derive(Builder)] 把這個函式註冊成 derive macro。
parse_macro_input! 把原始 token 解析成 syn::DeriveInput。
發生錯誤時用 to_compile_error() 轉成編譯錯誤，而不是 panic。

也就是說，macro 的錯誤訊息其實是你主動設計出來的 UX。

第 2 步：先擋掉不支援的型別（parse.rs）

在 parse.rs 裡，專案先做輸入驗證：

只接受「具名欄位 struct」
拒絕 enum / union / tuple struct / unit struct

這個設計超務實。因為 Builder 的生成邏輯依賴欄位名稱，沒有欄位名就沒辦法安全產生 setter。

像這段 compile-fail 測試會得到清楚錯誤：

#[derive(Builder)]
enum MyEnum {
    Variant1,
    Variant2,
}

錯誤訊息是：

Builder can only be derived for structs, not enums

builder-derive 這裡做得很對：把「不可能支援」的 case 儘早在編譯期擋下來，使用者不用等到 runtime 才踩雷。

第 3 步：欄位分析（field.rs）

接著是整個 macro 的關鍵資料結構 FieldInfo，每個欄位會被分析出：

欄位名稱 name
原始型別 ty
是否 Option<T>
Option<T> 的內層型別 T
是否 Vec<T>

怎麼判斷 `Option<T>`？

它用 syn::Type pattern matching：

先確認是 Type::Path
抓路徑最後一段（例如 Option）
看識別字是不是 Option
若是，從 angle-bracket 參數拿出 T

這是 proc macro 最常見也最實用的技巧： 不要自己 parse 字串；直接操作 AST。

`syn` 到底在做什麼？

可以把 syn 想成「Rust 語法的解析器 + AST 資料模型」。

在 builder-derive 裡，syn 主要做三件事：

把 TokenStream 轉成 DeriveInput（看到 struct 名稱、可見性、欄位）
用 enum pattern matching 檢查資料型別（Data::Struct / Fields::Named）
深入欄位型別結構（Type::Path -> PathSegment -> PathArguments）判斷 Option<T>、Vec<T>

為什麼這很重要？因為 procedural macro 要的是「語法結構」，不是字串比對。

舉例來說，Option<String>、std::option::Option<String> 在字串上看起來不同，但在 AST 層都能被一致處理。這就是 syn 在 macro 裡的核心價值。

另外像 syn::Error::new_spanned(...) 也很關鍵：它可以把錯誤綁在原始程式碼 span 上，讓編譯錯誤直接指到真正寫錯的那一行。

這個專案一個值得注意的設計

對 Option<T> 欄位，setter 參數型別是 T，不是 Option<T>。

也就是你寫：

.age(30)

而不是：

.age(Some(30))

這讓 API 更順手。不過 tradeoff 是：目前 API 不能顯式設定 None，只能「不呼叫 setter」來得到 None。

第 4 步：用 quote 生成程式碼（generate.rs）

generate.rs 裡把生成工作拆成四塊，這個切法很值得學：

generate_builder_struct
generate_builder_constructor
generate_setter_methods
generate_build_method

`quote!` 怎麼把 AST 變回 Rust 程式？

quote 的角色是「把分析結果重新組裝成 token」。

在這個專案裡，最常用的語法有兩個：

#var：把變數插進模板
#(...)*：把 iterator 產生的多段程式碼展開

例如：

let builder_fields = field_infos.iter().map(|field| {
    let name = &field.name;
    let builder_ty = field.builder_field_type();
    quote! { #name: #builder_ty }
});

quote! {
    struct #builder_name {
        #(#builder_fields,)*
    }
}

這段可以讀成：「每個欄位先變成一小段 token，最後用 repetition 一次展開成完整 struct 欄位列表。」

也因為這種寫法，macro 可以維持很強的可組合性：

每個生成函式只負責一種片段
最後在 impl_builder 把片段拼回完整輸出

對大型 macro 專案來說，這比單一巨大 quote! 區塊更容易維護。

4.1 生成 Builder struct

每個 builder 欄位都用 Option<...> 包起來，目的是追蹤「這個欄位有沒有被設定」。

4.2 生成 `builder()`

在原始 struct 上加：

impl User {
    pub fn builder() -> UserBuilder { ... }
}

所有欄位初始化成 None。

4.3 生成 setter（可 chain）

每個 setter 都是這個形狀：

pub fn field(mut self, value: T) -> Self {
    self.field = Some(value);
    self
}

self by value + 回傳 Self，就是 fluent API 的來源。

4.4 生成 `build()`，而且不同欄位策略不同

builder-derive 在這裡把欄位分三類處理：

Option<T>：直接 passthrough（沒設就 None）
Vec<T>：沒設就 unwrap_or_default()，變空陣列
其他欄位：必填，沒設就回 Err("field is required")

這個策略很實用，因為 Vec<T> 在很多 config 型別裡確實適合預設空集合。

展開後大概長怎樣？

以這個輸入：

#[derive(Builder)]
struct Config {
    host: String,
    port: u16,
    timeout: Option<u64>,
    features: Vec<String>,
}

macro 會產生近似這樣的程式碼（簡化版）：

struct ConfigBuilder {
    host: Option<String>,
    port: Option<u16>,
    timeout: Option<u64>,
    features: Option<Vec<String>>,
}

impl Config {
    fn builder() -> ConfigBuilder {
        ConfigBuilder {
            host: None,
            port: None,
            timeout: None,
            features: None,
        }
    }
}

impl ConfigBuilder {
    fn host(mut self, value: String) -> Self {
        self.host = Some(value);
        self
    }

    fn port(mut self, value: u16) -> Self {
        self.port = Some(value);
        self
    }

    fn timeout(mut self, value: u64) -> Self {
        self.timeout = Some(value);
        self
    }

    fn features(mut self, value: Vec<String>) -> Self {
        self.features = Some(value);
        self
    }

    fn build(self) -> Result<Config, String> {
        Ok(Config {
            host: self.host.ok_or_else(|| "host is required".to_string())?,
            port: self.port.ok_or_else(|| "port is required".to_string())?,
            timeout: self.timeout,
            features: self.features.unwrap_or_default(),
        })
    }
}

重點是：這些都發生在編譯期，你 runtime 不需要額外 macro 成本。

錯誤處理：compile-time 跟 runtime 分工

這個專案的錯誤策略很清楚：

Compile-time（macro 階段）

型別不支援就直接編譯失敗
錯誤訊息會標到對應程式碼位置（透過 syn::Error::new_spanned）

Runtime（build 階段）

缺必要欄位時，build() 回 Result::Err(String)

這種分工很合理：

能在語法層判斷的，就盡量提早失敗
必須等使用者呼叫流程才能判斷的，就用 Result 回報

為什麼這個範例很適合學 proc macro

builder-derive 的好處是它「剛好夠真實，但不會太重」：

有完整 pipeline（parse -> analyze -> generate）
有 compile-fail test（trybuild）
有 integration tests 驗證行為
邏輯分層乾淨，不會全部擠在一個檔案

如果正要開始學 proc macro，建議順序是：

先看 src/lib.rs 入口
再看 parse.rs 怎麼做輸入保護
再看 field.rs 怎麼做型別判斷
最後看 generate.rs 的 quote! 拼裝

這樣你比較不會一開始就被 quote! 的 token interpolation 淹沒。

目前限制與下一步

以目前實作來看，還有幾個可以進化的方向：

支援 generics（例如 struct Foo<T>）
支援 #[builder(...)] 欄位屬性（default、setter(into)、skip）
更結構化的錯誤型別（取代 String）
允許 optional setter 傳 Option<T>（可顯式設 None）

但以「教學用、理解 proc macro 原理」來說，現在這個版本其實已經很漂亮了。

結語

Rust 的 procedural macro 真正厲害的地方，不是語法炫技，而是把重複樣板在「編譯期」變成可驗證、可維護的程式碼生成流程。

builder-derive 這個專案剛好把這件事示範得很清楚：

用 syn 看懂你的 Rust 程式
用 quote 生成你本來不想手寫的 boilerplate
用型別檢查和測試把 macro 行為收斂到可預期

下次看到 #[derive(...)]，你可以把它想成： 「這不是魔法，是一個在編譯器裡跑的小型 code generator。」

專案連結：rust-52-projects/builder-derive

wasm-bindgen 產生的 JS 膠水程式碼在做什麼

February 10, 2026 TIL rust wasm

看了 wasm-pack build --target web 產生的 pkg/ 目錄，搞懂了 JS 膠水程式碼的角色。

wasm-pack 輸出四個檔案：

檔案	用途
`.wasm`	編譯後的 WASM 二進位
`.js`	JS 膠水程式碼（runtime 必須）
`.d.ts`	TypeScript 型別宣告（純靜態，runtime 不用）
`_bg.wasm.d.ts`	原始 WASM exports 的型別宣告

.d.ts 不參與執行——它們只給 TypeScript 編譯器做型別檢查用。整個流程不涉及 TypeScript 編譯。

膠水程式碼做兩件事：

1. 載入 WASM：init() 用 WebAssembly.instantiateStreaming 串流編譯 .wasm 檔，邊下載邊編譯。

2. 雙向橋接 WASM 和瀏覽器 API：

JS → WASM：處理型別轉換。WASM 只懂數字，所以字串要先編碼成 UTF-8 寫進 WASM 線性記憶體，再傳指標和長度：

export function start(canvas_id, grid_width, grid_height) {
    const ptr0 = passStringToWasm0(canvas_id, wasm.__wbindgen_malloc, ...);
    const len0 = WASM_VECTOR_LEN;
    return wasm.start(ptr0, len0, grid_width, grid_height);
}

WASM → JS：web_sys 的每個呼叫都對應一個 JS import 函式。以 WebGPU 的 device.createBuffer() 為例，Rust 端呼叫 web_sys → WASM 呼叫 import → JS 膠水程式碼呼叫真正的瀏覽器 API：
```
__wbg_createBuffer_fb1752eab5cb2a7f: function(arg0, arg1) {
    const ret = arg0.createBuffer(arg1);
    return ret;
}
```

在 wgpu Game of Life 專案裡，膠水程式碼包含大約 200 個這樣的橋接函式，全部由 wasm-bindgen 在建置時根據 #[wasm_bindgen] 和 web_sys 的使用自動生成。

WASM 裡的 Rust Async 沒有 Runtime

February 10, 2026 TIL rust wasm

在做 wgpu Game of Life 時發現一件事：WASM 環境下的 Rust async 不需要 Tokio 或 async-std——瀏覽器的 event loop 就是 runtime。

在 native Rust，你需要一個 executor 來 poll futures。但在 WASM，wasm-bindgen-futures 把 Rust 的 Future 轉換成 JavaScript 的 Promise，交給瀏覽器的 event loop 來驅動：

#[wasm_bindgen]
pub async fn start(canvas_id: &str) {
    // 每個 .await 都是把控制權交還給瀏覽器的 event loop
    let adapter = instance.request_adapter(&options).await;
    let (device, queue) = adapter.request_device(&desc, None).await;
}

JavaScript 端看到的就是一個回傳 Promise 的函式：

await wasm.start("canvas");

每次 .await 時，Rust future 暫停執行，控制權回到瀏覽器。當底層的 JS 操作（例如 WebGPU 的 requestAdapter）完成時，瀏覽器透過 microtask 觸發 Rust 的 waker，從暫停處繼續執行。

	Native	WASM
Runtime	Tokio / async-std	瀏覽器 event loop
Executor	Rust 端的 thread pool	JS microtask queue
Spawn	`tokio::spawn`（多執行緒）	`spawn_local`（單執行緒）

所以 Cargo.toml 只需要 wasm-bindgen-futures，不需要任何 Rust async runtime。

用 Rust + WebGPU 在瀏覽器跑 Game of Life

February 9, 2026 programming rust webassembly wasm webgpu wgpu gpu shader ai-assisted claude-code

這個專案把 Conway’s Game of Life 搬到 GPU 上面跑——用 Rust 的 wgpu 寫 WebGPU compute shader，編譯成 WASM 在瀏覽器裡執行。128x128 的網格、上萬個細胞的模擬，全部在 GPU 上平行計算。

專案原始碼：wgpu-game-of-life

先玩再說

操作方式：Play/Pause 開始模擬，點擊畫布可以畫細胞，Speed 調整速度。需要 WebGPU 支援的瀏覽器（Chrome 113+、Edge 113+、Firefox 141+）。

顏色代表細胞年齡：綠色是新生的，黃色是年輕的，橘色是成熟的，白色是古老的 still life 結構。

為什麼做這個？

在完成 WASM Markdown 編輯器之後，我想更深入探索 WASM 的可能性。Markdown 編輯器純粹是 CPU 計算，但現代瀏覽器已經支援 WebGPU——可以直接存取 GPU 的算力。

Game of Life 是個完美的入門專案：

天然適合平行計算：每個細胞的下一代只取決於鄰居，可以完全並行
需要 compute shader + render pipeline：同時學兩種 GPU 程式設計模式
視覺回饋即時：寫完馬上看到結果
規模剛好：不會太大，但足以理解 GPU 程式設計的核心概念

技術架構

整體流程

核心是 ping-pong 雙緩衝：兩個 storage buffer 交替讀寫。每一步模擬時，compute shader 從一個 buffer 讀取當前狀態，計算下一代寫入另一個 buffer，然後交換。Render pipeline 負責把結果畫到畫面上。

專案結構

wgpu-game-of-life/
├── Cargo.toml
├── src/
│   ├── lib.rs           # WASM 進入點，匯出 API
│   ├── gpu.rs           # wgpu 初始化、pipeline 建立、模擬邏輯
│   ├── compute.wgsl     # Compute shader（Game of Life 規則）
│   └── render.wgsl      # Vertex + Fragment shader（網格視覺化）
├── index.html
└── www/
    ├── index.js         # 控制邏輯、動畫迴圈、滑鼠互動
    └── styles.css

Rust 依賴項

[dependencies]
wgpu = "24"                        # WebGPU API
wasm-bindgen = "0.2"               # JS 互操作
wasm-bindgen-futures = "0.4"       # async 支援（wgpu 初始化是 async 的）
web-sys = { version = "0.3", features = ["Document", "Window", "Element", "HtmlCanvasElement", "console"] }
console_error_panic_hook = "0.1"
js-sys = "0.3"
bytemuck = { version = "1", features = ["derive"] }

跟 Markdown 編輯器比，多了 wgpu（核心）、wasm-bindgen-futures（因為 GPU 初始化是非同步的）和 bytemuck（安全地把 Rust 資料轉成 GPU buffer 需要的位元組）。

Compute Shader：Game of Life 規則

這是整個專案最核心的部分——用 WGSL 寫的 compute shader：

@group(0) @binding(0) var<uniform> grid: vec2u;
@group(0) @binding(1) var<storage, read> cells_in: array<u32>;
@group(0) @binding(2) var<storage, read_write> cells_out: array<u32>;

@compute @workgroup_size(8, 8)
fn main(@builtin(global_invocation_id) id: vec3u) {
    if (id.x >= grid.x || id.y >= grid.y) { return; }

    // 數 8 個鄰居（環形邊界）
    var neighbors: u32 = 0u;
    for (var dy: i32 = -1; dy <= 1; dy++) {
        for (var dx: i32 = -1; dx <= 1; dx++) {
            if (dx == 0 && dy == 0) { continue; }
            let nx = u32((i32(id.x) + dx + i32(grid.x)) % i32(grid.x));
            let ny = u32((i32(id.y) + dy + i32(grid.y)) % i32(grid.y));
            neighbors += select(0u, 1u, cells_in[cell_index(nx, ny)] > 0u);
        }
    }

    let idx = cell_index(id.x, id.y);
    let age = cells_in[idx];

    // Conway's rules + 年齡追蹤
    if (neighbors == 3u && age == 0u) {
        cells_out[idx] = 1u;                    // 誕生
    } else if (age > 0u && (neighbors == 2u || neighbors == 3u)) {
        cells_out[idx] = min(age + 1u, 255u);   // 存活，年齡 +1
    } else {
        cells_out[idx] = 0u;                    // 死亡
    }
}

幾個重點：

@workgroup_size(8, 8)：每個工作群組處理 8x8 = 64 個細胞，GPU 會自動分配到各個核心
cells_in 是唯讀，cells_out 是可寫：避免讀寫衝突，這就是為什麼需要兩個 buffer
環形邊界（toroidal wrapping）：左邊超出會接到右邊，上面超出接到下面
年齡追蹤：不只是 0/1，而是記錄細胞存活了幾代（上限 255）

128x128 的網格需要 dispatch ceil(128/8) × ceil(128/8) = 16 × 16 = 256 個工作群組，每個群組 64 個執行緒，總共 16,384 個 GPU 執行緒平行計算。

Render Shader：年齡上色

Fragment shader 根據年齡把細胞染成不同顏色：

fn age_color(age: u32) -> vec4f {
    if (age == 0u) {
        return vec4f(0.06, 0.06, 0.12, 1.0);  // 死亡：深色背景
    }
    let t = clamp(f32(age - 1u) / 50.0, 0.0, 1.0);

    // 顏色漸層：亮綠 → 黃綠 → 橘 → 暖白
    let c0 = vec3f(0.15, 0.90, 0.30);  // 新生
    let c1 = vec3f(0.80, 0.90, 0.15);  // 年輕
    let c2 = vec3f(0.95, 0.60, 0.10);  // 成熟
    let c3 = vec3f(1.00, 0.85, 0.70);  // 古老

    // 三段線性插值
    if (t < 0.33) { return mix(c0, c1, t / 0.33); }
    else if (t < 0.66) { return mix(c1, c2, (t - 0.33) / 0.33); }
    else { return mix(c2, c3, (t - 0.66) / 0.34); }
}

渲染方式是畫一個全螢幕四邊形（6 個頂點、2 個三角形），fragment shader 根據 UV 座標查詢對應的細胞年齡。這比為每個細胞生成幾何體（instanced rendering）更簡單，而且效能足夠。

Rust 端：wgpu 初始化

wgpu 在 WASM 環境下的初始化跟 native 基本一樣，只是 surface 從 canvas 建立：

// 從 HTML canvas 建立 surface
let instance = wgpu::Instance::new(&wgpu::InstanceDescriptor {
    backends: wgpu::Backends::BROWSER_WEBGPU | wgpu::Backends::GL,
    ..Default::default()
});

let surface = instance
    .create_surface(wgpu::SurfaceTarget::Canvas(canvas))
    .expect("failed to create surface");

// 請求 adapter 和 device（非同步）
let adapter = instance.request_adapter(&wgpu::RequestAdapterOptions {
    compatible_surface: Some(&surface),
    ..Default::default()
}).await.expect("no adapter");

let (device, queue) = adapter.request_device(
    &wgpu::DeviceDescriptor {
        required_limits: wgpu::Limits::downlevel_webgl2_defaults()
            .using_resolution(adapter.limits()),
        ..Default::default()
    },
    None,
).await.expect("no device");

Backends::BROWSER_WEBGPU | Backends::GL 讓它在支援 WebGPU 的瀏覽器用 WebGPU，不支援的用 WebGL2 作為 fallback。

Ping-Pong 雙緩衝

最有趣的設計是 bind group 的建立——為了實現 ping-pong，我們建兩組 bind group：

let compute_bind_groups = [
    // Step 0: 讀 A，寫 B
    create_bind_group(&cell_buffers[0], &cell_buffers[1]),
    // Step 1: 讀 B，寫 A
    create_bind_group(&cell_buffers[1], &cell_buffers[0]),
];

每一步模擬只要切換 step_index，就自動交換讀寫方向。

WASM API 設計

Rust 端透過 thread_local! 儲存全域狀態，匯出簡單的函式給 JavaScript：

為什麼需要 thread_local!？因為 #[wasm_bindgen] 匯出的必須是自由函式，JavaScript 呼叫 step()、render() 時不會帶著物件——所以 Simulation 必須存在模組層級的 static 裡。但一般的 static 要求內容必須實作 Sync，而 RefCell 不是 Sync。Simulation 裡面持有的 wgpu 資源（Device、Queue、Surface 等）也不是 Send/Sync 的。thread_local! 讓每個執行緒擁有自己的副本，繞過了 Sync 的限制——在 WASM 環境下本來就只有一個執行緒，所以它實際上就是一個不需要 Sync 的全域可變變數。

thread_local! {
    static SIMULATION: RefCell<Option<Simulation>> = RefCell::new(None);
}

#[wasm_bindgen]
pub async fn start(canvas_id: &str, grid_width: u32, grid_height: u32) {
    console_error_panic_hook::set_once();
    let sim = Simulation::new(canvas_id, grid_width, grid_height).await;
    SIMULATION.with(|s| *s.borrow_mut() = Some(sim));
}

#[wasm_bindgen]
pub fn step() {
    with_sim(|sim| sim.step());
}

#[wasm_bindgen]
pub fn toggle_cell(x: u32, y: u32) {
    with_sim(|sim| sim.toggle_cell(x, y));
}

start() 是 async 的，因為 wgpu 初始化（request_adapter、request_device）都是非同步操作。其他函式都是同步的。

CPU 端的細胞鏡像

一個實作上的巧妙之處：我們在 CPU 端維護一份細胞狀態的副本。

為什麼？因為當使用者點擊畫布要切換某個細胞時，從 GPU 讀回資料（readback）是很昂貴的操作。所以我們在 CPU 端維護一份鏡像，toggle 時修改 CPU 資料再上傳到 GPU：

pub fn toggle_cell(&mut self, x: u32, y: u32) {
    let idx = (y * self.grid_width + x) as usize;
    self.cells[idx] = if self.cells[idx] > 0 { 0 } else { 1 };
    self.queue.write_buffer(&self.cell_buffers[buf_idx], 0,
        bytemuck::cast_slice(&self.cells));
    self.render();
}

每次 step() 時也同步執行 CPU 端的模擬，確保鏡像保持一致。

建置與執行

cd wgpu-game-of-life
wasm-pack build --target web
python -m http.server 8080
# 開啟 http://localhost:8080

建置輸出：

WASM 檔案：117 KB
JS 膠水程式碼：57 KB
總計：~174 KB

比 Markdown 編輯器的 235 KB 還小，主要因為 wgpu 的 WASM backend 大部分邏輯在瀏覽器原生的 WebGPU API 裡。

學到的東西

WebGPU / wgpu 特定

Compute shader 比想像中簡單：WGSL 語法接近 Rust，workgroup/dispatch 的概念很直覺
Bind group 是關鍵抽象：它定義了 shader 能存取哪些資源，切換 bind group 就能改變資料流向
wgpu 的跨平台設計很優秀：同一份 Rust 程式碼，換個 backend 就能在 native 和 WASM 上跑
GPU readback 很貴：不要隨便從 GPU 讀資料回來，用 CPU 鏡像是常見的解法

跟 Markdown 編輯器的比較

	Markdown 編輯器	Game of Life
GPU 使用	無	Compute + Render
非同步初始化	否	是（wgpu 需要 async）
主要瓶頸	CPU 解析	GPU shader 編譯
互動模式	文字輸入	滑鼠繪圖 + 動畫迴圈
套件大小	235 KB	174 KB

結語

這是我第一次寫 GPU shader 程式——用 Rust 配 wgpu 的體驗非常好。wgpu 把 WebGPU 的複雜性封裝得很乾淨，而 WGSL shader 語言的設計也很現代。

如果你也想學 WebGPU，Game of Life 真的是個很好的起點：概念簡單、視覺效果漂亮、而且剛好涵蓋 compute pipeline 和 render pipeline 兩個核心概念。

參考資源

深入理解 cargo-apk：從 Rust 到 Android APK 的完整流程

February 8, 2026 programming rust android build-tools ndk gradle cargo-apk ai-assisted claude-code

當我們用 Rust 開發 Android 應用時，cargo-apk 是一個自動化整個建置流程的工具——從 Rust 原始碼編譯、產生 AndroidManifest.xml、整合 Gradle、到最後簽章產出 APK。這篇文章深入探討 cargo-apk 的內部運作機制，以及現代替代方案。

什麼是 cargo-apk

cargo-apk 是 rust-mobile 團隊開發的命令列工具，負責：

將 Rust cdylib 編譯為多個架構的 .so 檔案（ARM64、ARMv7、x86 等）
從 Cargo.toml 自動產生 AndroidManifest.xml
呼叫 aapt/aapt2 處理 Android 資源
透過 Gradle 組裝 APK（DEX 編譯 + ZIP 打包）
用 keystore 簽章 APK

重要提醒：cargo-apk 在 2024-2025 年已標記為 deprecated，官方推薦改用 xbuild，後者支援跨平台（Android、iOS、Web、桌面）且持續維護。本文仍詳細介紹 cargo-apk 的運作原理，因為理解這些底層機制有助於除錯和選擇合適的建置工具。

1. APK 檔案結構剖析

APK 本質上是一個 ZIP 壓縮檔，包含應用程式執行所需的所有元件。理解 APK 結構是掌握建置流程的第一步。

標準 APK 目錄結構

app.apk (ZIP archive)
├── AndroidManifest.xml         # 應用程式中繼資料（二進位 XML）
├── classes.dex                 # Dalvik Executable（Android Runtime 執行檔）
├── classes2.dex                # 額外的 DEX 檔案（若超過大小限制）
├── resources.arsc              # 編譯後的資源表（二進位格式）
├── META-INF/                   # 簽章和資訊清單
│   ├── MANIFEST.MF             # 套件資訊清單
│   ├── CERT.SF                 # 簽章檔案
│   └── CERT.RSA                # 憑證和簽章資料
├── assets/                     # 開發者自訂的未編譯資源
│   └── (custom files)
├── res/                        # 編譯後的資源（不在 resources.arsc 中）
│   ├── drawable/
│   ├── layout/
│   └── values/
└── lib/                        # 平台特定的原生函式庫
    ├── arm64-v8a/              # ARM 64-bit（現代裝置主流）
    │   └── libflashcard_app.so
    ├── armeabi-v7a/            # ARM 32-bit（舊裝置支援）
    │   └── libflashcard_app.so
    ├── x86/                    # Intel 32-bit（模擬器/平板）
    │   └── libflashcard_app.so
    └── x86_64/                 # Intel 64-bit（模擬器）
        └── libflashcard_app.so

Rust 為什麼編譯成 `.so` 檔案？

Android 要求所有原生程式碼編譯為動態連結函式庫（shared object, .so），放在 lib/<ABI>/ 目錄下。Rust 專案必須將 crate-type 設為 ["cdylib"]：

[lib]
crate-type = ["cdylib"]

cdylib 產生 C-compatible 的動態函式庫，Android Runtime 可以在執行時載入並呼叫其中的符號（透過 System.loadLibrary()）。

2. 建置流程五階段

cargo-apk 的建置流程可以拆解為五個連續的階段。理解每個階段的輸入輸出，有助於除錯建置問題。

Phase 1: Rust 編譯

cargo-apk 針對每個目標架構呼叫 rustc：

# 對於 ARM64
rustc --target aarch64-linux-android \
      --crate-type cdylib \
      -C linker=aarch64-linux-android-clang \
      ...

# 對於 ARMv7
rustc --target armv7-linux-androideabi \
      --crate-type cdylib \
      -C linker=armv7a-linux-androideabi-clang \
      ...

關鍵環節：

NDK 工具鏈選擇：每個架構使用對應的 clang linker（由 ANDROID_NDK_ROOT 提供）
Sysroot 連結：連結到 NDK 的平台 headers 和 libraries
RUSTFLAGS 設定：加入 -L 指定 NDK 函式庫路徑

輸出：

target/aarch64-linux-android/release/libmyapp.so
target/armv7-linux-androideabi/release/libmyapp.so
target/x86_64-linux-android/release/libmyapp.so

Phase 2: AndroidManifest.xml 產生

cargo-apk 從 Cargo.toml 的 [package.metadata.android] 讀取設定，自動產生 manifest：

[package.metadata.android]
package = "com.example.flashcard_app"
min_sdk_version = 21
target_sdk_version = 33

# 權限宣告
permissions = [
    "android.permission.INTERNET",
    "android.permission.WRITE_EXTERNAL_STORAGE"
]

# 建置目標架構
build_targets = ["aarch64-linux-android", "armv7-linux-androideabi"]

# Activity 主題
activity_theme = "@android:style/Theme.NoTitleBar.Fullscreen"

產生的 AndroidManifest.xml 範例：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.example.flashcard_app">

    <uses-sdk android:minSdkVersion="21" android:targetSdkVersion="33"/>
    <uses-permission android:name="android.permission.INTERNET"/>

    <application>
        <activity android:name="android.app.NativeActivity"
                  android:theme="@android:style/Theme.NoTitleBar.Fullscreen">
            <!-- 指定要載入的原生函式庫名稱 -->
            <meta-data android:name="android.app.lib_name"
                       android:value="flashcard_app"/>

            <intent-filter>
                <action android:name="android.intent.action.MAIN"/>
                <category android:name="android.intent.category.LAUNCHER"/>
            </intent-filter>
        </activity>
    </application>
</manifest>

關鍵觀念：

NativeActivity：Android 提供的類別，自動處理原生程式碼的生命週期
android.app.lib_name：指定要載入的 .so 檔案名稱（不含 lib 前綴和 .so 後綴）
Rust 程式碼必須實作 android_main 函式作為進入點

Phase 3: 資源處理（aapt/aapt2）

Android Asset Packaging Tool 負責編譯資源檔：

aapt2 compile --dir res/ -o compiled_resources/
aapt2 link --manifest AndroidManifest.xml \
           -o base.apk \
           compiled_resources/*.flat

輸出：

resources.arsc：二進位資源表，包含所有字串、顏色、尺寸定義
編譯後的 XML 資源檔案

Phase 4: Gradle APK 組裝

cargo-apk 呼叫 Gradle 進行最終組裝：

複製 .so 檔案到 jniLibs/<arch>/
編譯 Java/Kotlin 程式碼（若有）為 bytecode
產生 DEX：將 bytecode 轉換為 Dalvik Executable
打包 ZIP：將所有元件組合成 APK

Gradle 的 build.gradle 片段：

android {
    compileSdkVersion 33

    sourceSets {
        main {
            jniLibs.srcDirs = ['jniLibs']  // 原生函式庫來源
        }
    }
}

Phase 5: APK 簽章

最後一步是用 keystore 簽章 APK：

Debug 簽章（預設）：

apksigner sign --ks ~/.android/debug.keystore \
               --ks-pass pass:android \
               --ks-key-alias androiddebugkey \
               app-debug.apk

Release 簽章（自訂 keystore）：

[package.metadata.android]
release_keystore_path = "/path/to/release.jks"
release_keystore_password = "env:KEYSTORE_PASSWORD"
release_keystore_key_alias = "my-key"

簽章過程會在 APK 的 META-INF/ 目錄加入三個檔案：

MANIFEST.MF：列出 APK 中所有檔案及其 SHA-256 雜湊值
CERT.SF：MANIFEST.MF 的簽章
CERT.RSA：憑證和 RSA 簽章資料

Android OS 在安裝時會驗證這些簽章，確保 APK 沒有被竄改。

3. Cargo.toml 設定詳解

完整的 [package.metadata.android] 設定範例：

[package.metadata.android]
# 應用程式識別碼
package = "com.example.flashcard_app"
apk_name = "flashcard-app"

# SDK 版本
min_sdk_version = 21      # Android 5.0 Lollipop
target_sdk_version = 33   # Android 13
max_sdk_version = 34

# 建置目標架構
build_targets = [
    "aarch64-linux-android",      # ARM64（主要）
    "armv7-linux-androideabi"     # ARMv7（相容性）
]

# 權限宣告
permissions = [
    "android.permission.INTERNET",
    "android.permission.ACCESS_FINE_LOCATION"
]

# 硬體功能需求
features = ["android.hardware.location"]

# Activity 設定
activity_theme = "@android:style/Theme.NoTitleBar.Fullscreen"
main_activity_attributes = {
    "android:screenOrientation" = "portrait"
}

# Intent Filters（深度連結）
[[package.metadata.android.intent_filters]]
actions = ["android.intent.action.VIEW"]
categories = ["android.intent.category.DEFAULT", "android.intent.category.BROWSABLE"]
data = [{ scheme = "https", host = "example.com", path_prefix = "/app" }]

# 除錯設定
strip_symbols = false     # 保留符號以供除錯
debug = true

# Release 簽章
release_keystore_path = "/path/to/release.jks"
release_keystore_password = "env:KEYSTORE_PASSWORD"
release_keystore_key_alias = "my-key"
release_keystore_key_password = "env:KEY_PASSWORD"

4. NDK 整合機制

cargo-apk 如何找到並使用 Android NDK：

NDK 路徑解析

優先順序：

ANDROID_NDK_ROOT 環境變數
ANDROID_NDK_HOME 環境變數
local.properties 檔案中的 ndk.dir

工具鏈選擇（按架構）

架構	Rust Target	NDK Linker
ARM 64-bit	`aarch64-linux-android`	`aarch64-linux-android-clang`
ARM 32-bit	`armv7-linux-androideabi`	`armv7a-linux-androideabi-clang`
Intel 64-bit	`x86_64-linux-android`	`x86_64-linux-android-clang`
Intel 32-bit	`i686-linux-android`	`i686-linux-android-clang`

Sysroot 和 API Level

NDK 為每個 API level 提供不同的 sysroot（系統標頭檔和函式庫）：

$ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/
├── sysroot/
│   └── usr/
│       ├── include/         # C/C++ 標頭檔
│       └── lib/
│           ├── aarch64-linux-android/21/  # API 21 的 ARM64 函式庫
│           ├── aarch64-linux-android/28/  # API 28 的 ARM64 函式庫
│           └── ...

Rust 編譯時會連結到對應 API level 的 sysroot，確保產生的 .so 與目標 Android 版本相容。

5. 與手動 NDK 整合的比較

面向	cargo-apk	手動 NDK 整合
設定複雜度	`cargo install cargo-apk`	下載 NDK、設定路徑、撰寫建置腳本
Manifest 產生	自動從 Cargo.toml	手動編寫 XML
多架構建置	自動迴圈處理	每個架構手動呼叫
APK 組裝	Gradle 自動整合	手動呼叫 aapt + gradle
簽章	自動 keystore 處理	手動呼叫 apksigner
控制粒度	高層自動化	完全控制每個步驟
學習曲線	低（單一指令）	高（理解整個 Android 建置鏈）

cargo-apk 的核心價值是自動化——一行指令完成從 Rust 到 APK 的所有步驟。但代價是較少的客製化彈性，並且依賴 Gradle（可能增加建置時間）。

6. 目前狀態與替代方案

cargo-apk 的現況

cargo-apk 在 2024 年標記為 deprecated，原因：

缺乏跨平台支援（僅限 Android）
維護資源有限
更現代的工具（xbuild）提供更好的開發體驗

xbuild：現代化的替代方案

xbuild 是 rust-mobile 團隊的新工具，支援多平台：

優勢：

跨平台支援：Android、iOS、Windows、Linux、Web
統一命令介面：x build、x run、x doctor
裝置管理：x devices 列出所有連接的裝置
持續開發：活躍維護，積極修復問題
App Store 發佈：內建發佈到 Google Play 和 App Store 的支援

安裝與使用：

# 安裝
cargo install xbuild

# 檢查環境
x doctor

# 建置並部署到裝置
x devices                        # 列出裝置
x build --device adb:<device-id> # 建置並安裝

三階段建置流程：

Fetch：下載預編譯的 Rust 標準函式庫
Build：透過 Cargo 編譯 Rust 程式碼
Package：產生平台特定套件（APK、iOS bundle 等）

cargo-ndk：函式庫專用工具

cargo-ndk 適合只需要編譯 Rust 函式庫（不需要完整 APK）的專案：

cargo install cargo-ndk

cargo ndk -t arm64-v8a -t armeabi-v7a \
          -o ./jniLibs \
          build --release

輸出為標準的 jniLibs/ 目錄結構，可直接整合到現有的 Android Studio 專案。

工具比較表

工具	用途	平台支援	開發狀態	適用場景
cargo-apk	完整 APK 建置	Android only	Deprecated (2024)	舊專案維護
xbuild	跨平台應用建置	Android/iOS/Web/Desktop	活躍開發	新專案首選
cargo-ndk	NDK 函式庫編譯	Android (library)	活躍開發	整合到現有 Android 專案

7. 踩過的坑與解決方案

實際使用 cargo-apk 時常見的問題：

問題 1：NDK 找不到

Error: Failed to read source.properties: Os { code: 2, kind: NotFound }

原因：cargo-apk 找不到 NDK 安裝路徑。

解法：

# 設定環境變數（Windows PowerShell）
[Environment]::SetEnvironmentVariable("ANDROID_NDK_ROOT", "C:\Users\p47ts\scoop\apps\android-clt\current\ndk\29.0.14206865", "User")
[Environment]::SetEnvironmentVariable("ANDROID_HOME", "C:\Users\p47ts\scoop\apps\android-clt\current", "User")

# 或在當前 shell（bash）
export ANDROID_NDK_ROOT="/path/to/ndk/29.0.14206865"
export ANDROID_HOME="/path/to/android-sdk"

問題 2：錯誤的架構

APK 安裝後閃退，logcat 顯示：

E/linker: library "libmyapp.so" not found

原因：裝置的 ABI 與 build_targets 不符（例如裝置是 ARM64，但只編譯了 ARMv7）。

解法：

確認裝置 ABI：

adb shell getprop ro.product.cpu.abi
# 輸出：arm64-v8a

修改 Cargo.toml 加入對應架構：

[package.metadata.android]
build_targets = ["aarch64-linux-android"]  # 對應 arm64-v8a

問題 3：APK 檔案過大

Release APK 超過 100MB，包含大量除錯符號。

解法：

啟用符號剝離：

[package.metadata.android]
strip_symbols = true  # 移除除錯符號

或在 Cargo.toml 設定 release profile：

[profile.release]
strip = true       # 剝離符號
opt-level = "z"    # 最小化檔案大小
lto = true         # Link-Time Optimization

問題 4：Feature flag 統一導致桌面建置失敗

使用 target-conditional 依賴時，Cargo 仍會統一 feature：

# ❌ 錯誤：桌面建置也會拉入 Android 依賴
[target.'cfg(target_os = "android")'.dependencies]
slint = { version = "1.9", features = ["backend-android-activity-06"] }

解法：

改用 feature flag：

[features]
android = ["slint/backend-android-activity-06"]

[dependencies]
slint = "1.9"

建置時明確啟用：

cargo apk build --features android --target aarch64-linux-android --lib

問題 5：Windows 上的 PDB 檔名衝突

warning: output filename collision.
The bin target `flashcard-app` has the same output filename as the lib target `flashcard_app`.
Colliding filename is: flashcard_app.pdb

原因：crate-type = ["cdylib", "lib"] 搭配同名的 [[bin]] 在 Windows 產生相同的 PDB 除錯檔案。

解法：

讓 bin 名稱與 package 名稱不同：

[package]
name = "flashcard-app"

[[bin]]
name = "flashcard"  # 不同於 package name
path = "src/main.rs"

8. 完整建置範例

從零開始建置 Android APK 的完整流程：

# 1. 建立專案
cargo new --lib my-android-app
cd my-android-app

# 2. 設定 Cargo.toml
cat >> Cargo.toml << 'EOF'
[lib]
crate-type = ["cdylib"]

[package.metadata.android]
package = "com.example.myapp"
min_sdk_version = 21
target_sdk_version = 33
build_targets = ["aarch64-linux-android", "armv7-linux-androideabi"]
EOF

# 3. 撰寫 Rust 入口點（src/lib.rs）
cat > src/lib.rs << 'EOF'
#[cfg(target_os = "android")]
#[no_mangle]
fn android_main(app: android_activity::AndroidApp) {
    // 應用程式邏輯
}
EOF

# 4. 設定環境變數（依實際路徑調整）
export ANDROID_NDK_ROOT="/path/to/ndk/29.0.14206865"
export ANDROID_HOME="/path/to/android-sdk"

# 5. 安裝 Rust Android target
rustup target add aarch64-linux-android armv7-linux-androideabi

# 6. 安裝 cargo-apk
cargo install cargo-apk

# 7. 建置 APK
cargo apk build --release

# 內部流程：
#   [Phase 1] rustc --target aarch64-linux-android ...
#             → target/aarch64-linux-android/release/libmyapp.so
#   [Phase 2] Generate AndroidManifest.xml from Cargo.toml
#   [Phase 3] aapt2 compile resources
#   [Phase 4] Gradle: package DEX + .so → APK
#   [Phase 5] apksigner sign with release.jks
#
# 輸出：target/release/apk/my-android-app.apk

# 8. 安裝到裝置
cargo apk run --release

建置完成後，APK 位置：

target/
└── release/
    └── apk/
        └── my-android-app.apk  # 已簽章的 APK

檢查 APK 內容：

unzip -l target/release/apk/my-android-app.apk
# 輸出：
# lib/arm64-v8a/libmyapp.so
# lib/armeabi-v7a/libmyapp.so
# AndroidManifest.xml
# classes.dex
# META-INF/MANIFEST.MF
# ...

總結

從 Rust 程式碼到可安裝的 Android APK，cargo-apk 自動化了複雜的建置鏈：

階段	輸入	輸出	關鍵技術
1. Rust 編譯	src/*.rs + Cargo.toml	libmyapp.so (多架構)	rustc + NDK toolchain
2. Manifest 產生	[package.metadata.android]	AndroidManifest.xml	NativeActivity 設定
3. 資源處理	res/, assets/	resources.arsc	aapt/aapt2
4. APK 組裝	.so + DEX + resources	unsigned APK (ZIP)	Gradle
5. 簽章	APK + keystore	signed APK	apksigner

何時使用哪個工具？

新專案：優先選擇 xbuild（跨平台、活躍開發、統一工具鏈）
整合現有 Android 專案：使用 cargo-ndk（只編譯 .so，由 Android Studio 處理其餘）
舊專案維護：可繼續使用 cargo-apk，但建議遷移到 xbuild

關鍵觀念回顧：

APK 是 ZIP：理解目錄結構有助於除錯打包問題
cdylib 必要性：Android 只能載入動態函式庫
多架構建置：一個 APK 包含所有架構的 .so，安裝時系統自動選擇
Manifest 自動化：Cargo.toml 配置轉換為 Android 設定
NDK 整合：正確設定環境變數是成功建置的關鍵

透過理解這些底層機制，即使遇到建置問題也能快速定位原因並解決。

參考資源

cargo-apk GitHub - 官方原始碼與文件
xbuild GitHub - 現代化的跨平台建置工具
cargo-ndk GitHub - NDK 函式庫編譯工具
Android NDK 文件 - 官方 NDK 開發指南
APK 檔案格式 - APK 結構詳解
Android Gradle Build 流程 - Gradle 建置系統文件

Rust Proc Macro：builder-derive 實戰

先看使用端：我們到底得到了什麼

Proc Macro 的核心心法：編譯期程式碼產生器

第 1 步：入口函式（lib.rs）

第 2 步：先擋掉不支援的型別（parse.rs）

第 3 步：欄位分析（field.rs）

怎麼判斷 Option<T>？

syn 到底在做什麼？

這個專案一個值得注意的設計

第 4 步：用 quote 生成程式碼（generate.rs）

quote! 怎麼把 AST 變回 Rust 程式？

4.1 生成 Builder struct

4.2 生成 builder()

4.3 生成 setter（可 chain）

4.4 生成 build()，而且不同欄位策略不同

展開後大概長怎樣？

錯誤處理：compile-time 跟 runtime 分工

Compile-time（macro 階段）

Runtime（build 階段）

為什麼這個範例很適合學 proc macro

目前限制與下一步

結語

wasm-bindgen 產生的 JS 膠水程式碼在做什麼

WASM 裡的 Rust Async 沒有 Runtime

用 Rust + WebGPU 在瀏覽器跑 Game of Life

先玩再說

為什麼做這個？

技術架構

整體流程

專案結構

Rust 依賴項

Compute Shader：Game of Life 規則

Render Shader：年齡上色

Rust 端：wgpu 初始化

Ping-Pong 雙緩衝

WASM API 設計

CPU 端的細胞鏡像

建置與執行

學到的東西

WebGPU / wgpu 特定

跟 Markdown 編輯器的比較

結語

參考資源

深入理解 cargo-apk：從 Rust 到 Android APK 的完整流程

什麼是 cargo-apk

1. APK 檔案結構剖析

標準 APK 目錄結構

Rust 為什麼編譯成 .so 檔案？

2. 建置流程五階段

Phase 1: Rust 編譯

Phase 2: AndroidManifest.xml 產生

Phase 3: 資源處理（aapt/aapt2）

Phase 4: Gradle APK 組裝

Phase 5: APK 簽章

3. Cargo.toml 設定詳解

4. NDK 整合機制

NDK 路徑解析

工具鏈選擇（按架構）

Sysroot 和 API Level

5. 與手動 NDK 整合的比較

6. 目前狀態與替代方案

cargo-apk 的現況

xbuild：現代化的替代方案

cargo-ndk：函式庫專用工具

工具比較表

7. 踩過的坑與解決方案

問題 1：NDK 找不到

問題 2：錯誤的架構

問題 3：APK 檔案過大

問題 4：Feature flag 統一導致桌面建置失敗

問題 5：Windows 上的 PDB 檔名衝突

8. 完整建置範例

總結

參考資源

怎麼判斷 `Option<T>`？

`syn` 到底在做什麼？

`quote!` 怎麼把 AST 變回 Rust 程式？

4.2 生成 `builder()`

4.4 生成 `build()`，而且不同欄位策略不同

Rust 為什麼編譯成 `.so` 檔案？