setup.cn.md

Camel 项目开发环境配置指南

English | 中文简体

1. 项目简介

Camel 是一个采用现代 C++ 技术栈构建的 AI 编程语言，前端基于 Antlr4 实现（需要 Java 环境支持），并整合了 Python 和 Node.js 工具链以实现跨平台开发。本指南旨在帮助开发者快速搭建 Camel 项目的开发环境。

---

2. 技术栈要求

以下是 Camel 项目所需的技术栈及版本要求：

组件	最低版本	推荐版本	验证命令
Python	3.9	3.11	python --version
Node.js	18	20 LTS	node -v
Java	11	21	java -version
Clang	19	20	clang --version
CMake	3.20	3.28	cmake --version
Conan	2.10	2.12	conan --version
Ninja	1.11	1.11	ninja --version

确保以上组件安装并配置正确后方可开展项目开发。

---

3. 环境配置

以下为开发环境的配置步骤，覆盖 Windows、macOS 和 Linux 平台的具体操作。

---

3.1 脚本语言环境安装

3.1.1 安装 Python

1. 前往 Python 官网 下载并安装适合您操作系统的版本。
2. 安装时勾选 Add Python to PATH 选项。
3. 打开终端，执行以下命令验证安装是否成功：

   python --version

3.1.2 安装 Node.js

1. 访问 Node.js 官网 下载最新版或 LTS 版本。
2. 安装完成后，在终端中运行以下命令验证安装：

   node --version
   npm --version

3.1.3 安装 Java

1. 可从 Oracle 官网 或 AdoptOpenJDK 下载并安装 Java。
2. 配置 JAVA_HOME 和 PATH 环境变量。
3. 打开终端，运行以下命令确认安装：

   java -version

---

3.2 C++ 开发工具链

3.2.1 Clang

1. 安装方法：
   • Windows：从 LLVM 官方下载页面 或 GitHub Release 获取安装程序。
   • macOS：安装 Xcode 命令行工具：

     xcode-select --install

     或使用 Homebrew：

     brew install llvm

   • Linux：通过包管理器安装，例如：

     # Ubuntu/Debian:
     sudo apt update && sudo apt install clang

     若需要更高版本，可参考 LLVM 官方文档 添加官方仓库并安装。
2. 验证安装：

   clang --version

---

3.2.2 CMake

1. 安装方法：

   • 从 CMake 官方下载页面 获取适合系统的安装程序或压缩包。
   • 也可以使用系统包管理器安装：

     # macOS:
     brew install cmake
     
     # Ubuntu/Debian:
     sudo apt install cmake

2. 验证安装：

   cmake --version

---

3.2.3 Conan

1. 安装方法：

   • 确保已安装 Python，然后使用 pip 安装 Conan：

     pip install conan

2. 验证安装：

   conan --version

---

3.2.4 Ninja

1. 安装方法：

   • 从 Ninja 官方 GitHub 下载可执行文件。
   • 或通过包管理器安装：

     # macOS:
     brew install ninja
     
     # Ubuntu/Debian:
     sudo apt install ninja-build

   • 或通过 pip 安装：

     pip install ninja

2. 验证安装：

   ninja --version

---

3.3 包管理工具配置

3.3.1 Conan 初始化配置

conan profile detect --force

3.3.2 自定义构建配置

编辑 ~/.conan2/profiles/default 文件，配置如下：

[settings]
os=Windows
arch=x86_64
compiler=clang
compiler.version=19
compiler.cppstd=23
build_type=Release

[conf]
tools.build:jobs=20
tools.cmake.cmaketoolchain:generator=Ninja Multi-Config

---

3.4 项目依赖安装

执行以下命令完成依赖安装：

1. 安装项目依赖（自动安装并初始化项目）：

   npm install

2. 手动初始化项目（如果需要）：

   npm run init

3. 若 Antlr4 语法定义有变更，重新生成解析器：

   npm run psrgen

4. 对于VSCode用户，推荐执行以下命令修复Intellisense报错：

   npm run fix:vsc

---

3.5 项目结构

• libcamel：Camel 核心共享库
• tools/：链接 libcamel 的独立工具
  • camel-cli：主入口，生成 camel 可执行文件
  • camel-cpp：.cml → C++ 转译并自动编译，产物到 tmp/
  • format：代码格式化工具 camel-format
  • codegen：从 AST 生成代码 camel-codegen
  • profiler：性能分析工具 camel-profiler

构建产物位于 build/tools/<tool>/<Config>/，camel 可执行文件会复制到项目根目录。

3.6 编译目标构建

1. 构建 Release 版本（首次或删除 build/ 后会自动执行 conan install）：

   npm run build

2. 构建 Debug 版本（支持断点调试）：

   npm run debug

3. 构建 RelWithDebInfo 版本（性能分析用）：

   npm run profile

4. 清理构建产物：

   npm run clean

5. CMake 编译选项（FastVM JIT、computed goto、Python 嵌入模块等）与 CAMEL_SKIP_PYTHON 环境变量说明，见 编译选项说明。

---

4. 参考资源

1. CMake 官方文档
2. Conan 2.0 最佳实践
3. LLVM Clang 工具链指南
4. Node.js 官方文档
5. Python 官方文档
6. Ninja 构建系统
7. Antlr4 官方文档