# 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 中的详细说明