260 lines
7.2 KiB
Markdown
260 lines
7.2 KiB
Markdown
# 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 命令：
|
||
|
||
```powershell
|
||
# 进入 quickjs 目录
|
||
cd quickjs
|
||
|
||
# 配置构建（Release 模式）
|
||
cmake -B build -DCMAKE_BUILD_TYPE=Release
|
||
|
||
# 编译项目
|
||
cmake --build build -j
|
||
|
||
# 或者使用 Makefile（如果 make 可用）
|
||
make
|
||
```
|
||
|
||
### 常用构建命令
|
||
|
||
```bash
|
||
# 标准构建（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）
|
||
|
||
示例：
|
||
```bash
|
||
cmake -B build -DCMAKE_BUILD_TYPE=Debug -DQJS_BUILD_EXAMPLES=ON
|
||
```
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
# 运行基本测试套件
|
||
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 版本：
|
||
|
||
```bash
|
||
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 数据生成器
|
||
|
||
## 相关资源
|
||
|
||
- 项目官网：https://quickjs-ng.github.io/quickjs/
|
||
- GitHub 仓库：https://github.com/quickjs-ng/quickjs
|
||
- 原 QuickJS 项目：https://bellard.org/quickjs
|
||
- ECMAScript 规范：https://tc39.es/ecma262/
|
||
|
||
## 注意事项
|
||
|
||
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 中的详细说明 |