快速开始

在 5 分钟内让 qzjs 跑起来。

前置条件

• C 编译器 — GCC 8+ 或 Clang 10+（POSIX；Windows/MSVC 尚不支持）
• CMake 3.10+
• Git（用于子模块）

克隆与构建

# 克隆仓库及所有子模块
git clone --recursive https://github.com/adam-ikari/qzjs.git
cd qzjs

# 配置并构建（Release 模式）
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

尺寸敏感的构建：加 -DQZ_PROFILE=minimal（仍满足 WinterTC 兼容， 2.45 MiB strip 后）。见构建选项。

构建产物 libqzjs.a（静态核心）和 libqz_full.a（供 CMake 消费方使用的链接接口聚合库）位于 build/ 目录，另有 build/qzjs.pc 供 pkg-config 使用。

你的第一个程序

创建 hello.c：

#include <qzjs/qzjs.h>
#include <stdio.h>

static void on_message(qz_t *rt, const char *json, size_t len, void *data) {
    (void)rt; (void)data;
    printf("received: %.*s\n", (int)len, json);
}

int main(void) {
    // 创建运行时 — qzjs 启动自己的内部线程和循环
    qz_config_t cfg = {0};
    cfg.initial_script = "console.log('Hello from qzjs!'); postMessage(1 + 1);";
    cfg.message_cb = on_message;
    qz_t *rt = qz_create(&cfg);
    if (!rt) {
        fprintf(stderr, "Failed to create runtime\n");
        return 1;
    }

    // 通过发送 JSON 消息驱动运行时
    qz_post_message(rt, "{\"cmd\":\"echo\",\"data\":\"hi\"}", 26);

    // 清理 — 优雅关闭
    qz_destroy(rt);
    return 0;
}

使用 pkg-config 编译并链接（自动带出完整静态链接行 — 全部 vendored 归档）：

cc -std=c99 -o hello hello.c $(pkg-config --cflags --libs qzjs)

树内构建时，先把 pkg-config 指向构建目录：

export PKG_CONFIG_PATH="$PWD/build"

带测试构建

cmake -B build -DCMAKE_BUILD_TYPE=Debug -DQZ_BUILD_TESTS=ON
cmake --build build -j$(nproc)
cd build && ctest --output-on-failure

测试带有标签，方便定向运行：

ctest -L offline   # 本地确定性测试（CI 默认）
ctest -L dap       # DAP 协议测试
ctest -L test262   # ECMA-262 一致性测试套件

下一步

• 构建 — 所有 CMake 选项详解
• 运行时生命周期 — 创建、使用、销毁
• 嵌入模式 — 基于消息的宿主模式