wangdongpo/quickjs-prj
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
quickjs-prj/AGENTS.md
wangdongpo 4600cb0957 完成迁移
2026-02-02 12:48:25 +08:00

7.2 KiB
Raw Permalink Blame History

QuickJS 项目上下文文档

项目概述

这是一个包含 QuickJS JavaScript 引擎及其相关项目的工作空间。QuickJS 是一个小型且可嵌入的 JavaScript 引擎，旨在支持最新的 ECMAScript 规范。

目录结构

D:\workspace\quickjs-prj\
├── quickjs/          # QuickJS-ng 主项目源码（QuickJS 的维护分支）
├── yps-quickjs/      # 空目录，可能用于自定义项目
└── AGENTS.md         # 本文档

主项目（quickjs/）

QuickJS-ng 是原 QuickJS 项目（由 Fabrice Bellard 和 Charlie Gordon 创建）的维护分支，在原项目进入休眠状态后，由社区重新启动开发，旨在继续推进该引擎的发展。

主要特点：

  • 小型且可嵌入的 JavaScript 引擎
  • 支持最新的 ECMAScript 规范
  • 用 C 语言编写（C11 标准）
  • 跨平台支持（Windows、Linux、macOS、WASI 等）

核心技术组件：

  • quickjs.c - 核心 JavaScript 引擎实现
  • quickjs.h - 公共 API 头文件
  • quickjs-libc.c/h - 标准 C 库扩展
  • libregexp.c/h - 正则表达式引擎
  • libunicode.c/h - Unicode 支持
  • qjs.c - 命令行解释器（REPL）
  • qjsc.c - JavaScript 字节码编译器

构建和运行

构建系统

QuickJS 使用 CMake 作为主要构建系统，同时提供了辅助的 Makefile 用于简化常见操作。

Windows 构建说明

由于当前运行环境为 Windows（win32），需要手动运行 CMake 命令：

# 进入 quickjs 目录
cd quickjs

# 配置构建（Release 模式）
cmake -B build -DCMAKE_BUILD_TYPE=Release

# 编译项目
cmake --build build -j

# 或者使用 Makefile（如果 make 可用）
make

常用构建命令

# 标准构建（Release 模式）
make

# Debug 构建（无优化，适合开发调试）
make debug

# 清理构建
make clean

# 完全清理（删除 build 目录）
make distclean

# 安装到系统（默认 /usr/local）
make install

构建选项（CMake）

可以通过 CMake 变量或环境变量配置构建选项：

  • BUILD_SHARED_LIBS - 构建共享库（默认：OFF）
  • QJS_BUILD_EXAMPLES - 构建示例程序（默认：OFF）
  • QJS_BUILD_CLI_STATIC - 构建静态 qjs 可执行文件（默认：OFF）
  • QJS_BUILD_CLI_WITH_MIMALLOC - 使用 mimalloc 内存分配器（默认：OFF）
  • QJS_DISABLE_PARSER - 禁用 JS 源码解析器（默认：OFF）
  • QJS_ENABLE_ASAN - 启用地址消毒器（默认：OFF）
  • QJS_ENABLE_MSAN - 启用内存消毒器（默认：OFF）
  • QJS_ENABLE_TSAN - 启用线程消毒器（默认：OFF）
  • QJS_ENABLE_UBSAN - 启用未定义行为消毒器（默认：OFF）

示例：

cmake -B build -DCMAKE_BUILD_TYPE=Debug -DQJS_BUILD_EXAMPLES=ON

运行测试

# 运行基本测试套件
make test

# 运行完整的 Test262 测试套件
make test262

# 快速运行 Test262（仅测试核心功能）
make test262-fast

# 更新 Test262 测试结果（在实现新功能后）
make test262-update

# 运行性能基准测试
make microbench

可执行文件

构建完成后，在 build/ 目录下会生成以下主要可执行文件：

  • qjs - QuickJS 命令行解释器（REPL）
  • qjsc - JavaScript 到 C 的编译器
  • run-test262 - Test262 测试套件运行器
  • api-test - API 测试程序

Amalgamated 构建

如果需要单文件编译，可以使用 amalgamated 版本：

make amalgam

这将在 build/ 目录生成 quickjs-amalgam.zip，包含合并后的源文件。

开发约定

代码风格

  • 使用 C11 标准
  • 严格的编译器警告：-Wall -Werror -Wextra（MSVC 有特定配置）
  • 遵循项目的现有代码风格和命名约定
  • 使用 4 空格缩进（根据现有代码推断）

编码规范

  • 所有字符串应为纯 ASCII 或 UTF-8 编码
  • 除非单独传递长度参数，C 字符串必须以 null 结尾
  • 使用项目提供的类型定义（如 JSRuntime, JSContext 等）

版本控制

  • 项目使用 Git 进行版本控制
  • 版本号在 quickjs.h 中定义（QJS_VERSION_MAJOR, QJS_VERSION_MINOR, QJS_VERSION_PATCH）
  • 遵循 MIT 许可证

提交和贡献

  • 参考现有的 GitHub Actions 工作流（.github/workflows/）
  • CI 流程包括：
    • ci.yml - 持续集成
    • docs.yml - 文档构建
    • release.yml - 发布流程
    • tsan.yml - 线程消毒器测试
    • valgrind.yml - 内存泄漏检测

平台特定注意事项

Windows：

  • 默认栈大小设置为 8MB（防止栈溢出）
  • 需要 _WIN32_WINNT=0x0601（Windows 7+ 支持）
  • MinGW 构建需要静态链接选项

macOS：

  • GCC 11+ 需要额外的编译器标志（-Wno-maybe-uninitialized）

WASI：

  • 需要模拟进程时钟和信号

项目文档

项目包含详细的文档，位于 quickjs/docs/docs/ 目录：

  • installation.md - 安装指南
  • building.md - 构建说明
  • cli.md - 命令行工具使用
  • intro.md - 项目介绍
  • es_features.md - 支持的 ES 特性
  • stdlib.md - 标准库文档
  • supported_platforms.md - 支持的平台
  • developer-guide/ - 开发者指南（API、内部机制等）

文档使用 Docusaurus 构建，位于 quickjs/docs/ 目录。

示例代码

项目包含多个示例，位于 quickjs/examples/ 目录：

  • hello.js - 基本的 Hello World 示例
  • hello_module.js - 模块使用示例
  • fib.js / fib.c - 斐波那契数列（JS 和 C 模块）
  • test_fib.js - 斐波那契测试
  • pi_bigint.js - 使用 BigInt 计算 Pi

这些示例需要启用 QJS_BUILD_EXAMPLES 选项才能构建。

重要文件

核心源文件

  • quickjs.h - 主 API 头文件（1288+ 行）
  • quickjs.c - 核心引擎实现
  • quickjs-libc.h - 标准 C 库扩展头文件
  • quickjs-libc.c - 标准 C 库扩展实现

构建配置

  • CMakeLists.txt - CMake 构建配置
  • Makefile - 辅助 Makefile（包装 CMake 命令）
  • meson.build - Meson 构建配置（可选）

测试

  • tests/ - 项目特定测试
  • test262/ - Test262 ECMAScript 兼容性测试
  • run-test262.c - Test262 运行器
  • tests.conf - 测试配置
  • test262.conf - Test262 配置

工具

  • amalgam.js - 生成 amalgamated 构建的脚本
  • unicode_gen.c - Unicode 数据生成器

相关资源

注意事项

  1. Windows 开发：需要手动运行 CMake 命令，参考上述构建说明
  2. 栈大小：Windows 上默认栈大小为 8MB，防止运行时栈溢出
  3. 编码：确保所有字符串使用 UTF-8 编码
  4. 调试：使用 make debug 或 CMake Debug 模式进行开发调试
  5. 测试：提交代码前确保 make test 和 make test262 通过

当前工作目录信息

  • 工作目录：D:\workspace\quickjs-prj
  • 平台：Windows (win32)
  • 操作系统：Windows 10.0.26100
  • Git 版本：2.48.1.windows.1
  • Python 版本：3.12.9

TODO 项

  • yps-quickjs/ 目录当前为空，可能需要添加自定义项目或说明
  • 如果需要其他构建选项或平台特定的配置，请参考 CMakeLists.txt 中的详细说明
Reference in New Issue View Git Blame Copy Permalink