setup.en.md

Camel Project Development Environment Setup Guide

中文简体 | English

1. Project Overview

Camel is an AI programming language built with a modern C++ technology stack. Its frontend is implemented using Antlr4 (requires a Java runtime) and integrates Python and Node.js toolchains for cross-platform development. This guide is designed to help developers quickly set up the development environment for the Camel project.

---

2. Technical Requirements

The following table lists the required components and their version specifications for the Camel project:

Component	Minimum Version	Recommended Version	Verification Command
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

Ensure that the above components are properly installed and configured before proceeding with development.

---

3. Environment Setup

The following steps outline the setup process for the development environment, covering Windows, macOS, and Linux platforms.

---

3.1 Installing Script Language Environments

3.1.1 Installing Python

1. Visit the Python official website to download and install the version suitable for your operating system.
2. During installation, check the Add Python to PATH option.
3. Open a terminal and run the following command to verify the installation:

   python --version

3.1.2 Installing Node.js

1. Visit the Node.js official website to download the latest or LTS version.
2. After installation, verify it in the terminal:

   node --version
   npm --version

3.1.3 Installing Java

1. Download and install Java from the Oracle official website or AdoptOpenJDK.
2. Configure the JAVA_HOME and PATH environment variables.
3. Open a terminal and confirm the installation:

   java -version

---

3.2 C++ Development Toolchain

3.2.1 Clang

1. Installation Methods:
   • Windows: Download from the LLVM official download page or GitHub Releases.
   • macOS: Install via Xcode command line tools:

     xcode-select --install

     Or use Homebrew:

     brew install llvm

   • Linux: Install via package manager, e.g.:

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

     For newer versions, refer to the LLVM official documentation to add the official repository and install.
2. Verify Installation:

   clang --version

---

3.2.2 CMake

1. Installation Methods:

   • Download the installer or archive from the CMake official download page.
   • Alternatively, use a package manager:

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

2. Verify Installation:

   cmake --version

---

3.2.3 Conan

1. Installation:

   • Ensure Python is installed, then use pip to install Conan:

     pip install conan

2. Verify Installation:

   conan --version

---

3.2.4 Ninja

1. Installation Methods:

   • Download the executable from the Ninja official GitHub.
   • Or install via a package manager:

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

   • Alternatively, install via pip:

     pip install ninja

2. Verify Installation:

   ninja --version

---

3.3 Package Management Configuration

3.3.1 Conan Initialization

conan profile detect --force

3.3.2 Custom Build Configuration

Edit the ~/.conan2/profiles/default file with the following configuration:

[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 Installing Project Dependencies

Run the following commands to install project dependencies:

1. Initialize dependencies (only needed once):

   npm run init

2. Update Conan dependencies:

   npm run install

3. If Antlr4 grammar definitions are updated, regenerate the parser:

   npm run psrgen

---

3.5 Building Targets

1. Build the Release version:

   npm run build

2. Build the Debug version (for breakpoint debugging):

   npm run debug

3. Clean build artifacts:

   npm run clean

---

4. Recommended VSCode Configuration

4.1 Basic Configuration

Create a .vscode/settings.json file:

{
    "files.associations": {
        ".opencmlrc": "json"
    },
    "editor.tabSize": 4
}

4.2 Debug Configuration

Create a .vscode/launch.json file:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "C++ Debug (Windows)",
      "cwd": "${workspaceFolder}",
      "type": "cppvsdbg",
      "request": "launch",
      "program": "${workspaceFolder}/build/Debug/camel.exe",
      "symbolSearchPath": "${workspaceFolder}/build/Debug",
      "args": ["inspect", "--cst", "D:\\Projects\\Camel\\test\\format\\format.cml"],
      "console": "externalTerminal",
      "logging": {
        "moduleLoad": false,
        "trace": true
      },
    }
  ]
}

4.3 Include Path Configuration

Create a .vscode/c_cpp_properties.json file:

{
  "configurations": [
    {
      "includePath": [
        "${workspaceFolder}/src",
        "${workspaceFolder}/vendor",
        "${workspaceFolder}/third_party"
      ],
      "cppStandard": "c++23"
    }
  ]
}

---

5. Reference Resources

1. CMake Official Documentation
2. Conan 2.0 Best Practices
3. LLVM Clang Toolchain Guide
4. Node.js Official Documentation
5. Python Official Documentation
6. Ninja Build System
7. Antlr4 Official Documentation