README.md

以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

Salam 编程语言

Salam 是一种通用及系统编程语言，旨在高效软件开发，内置领域特定语言 (DSL)

✨ 介绍 Salam
快速安装
🧩 编辑器支持
- Visual Studio Code
🛠️ 编译器 (salam)
🐳 Docker & Docker Compose
🚀 Bun Workspaces：多应用开发与静态站点指南
🤝 贡献指南
🔍 参与代码审查
- GitHub PR 审查是如何工作的
  - 留下内联评论
建议代码更改
📖 术语表

✨ 介绍 Salam

Salam 语言，灵感源自 salam（سلام）一词，意为和平，专为卓越的效率、可靠性和现代软件开发而设计。Salam 从底层设计出发，旨在平衡底层控制与开发者生产力，消除了系统工程中常见的不必要语法摩擦。通过优先考虑清晰、易读且直观的架构，它降低了入门的认知门槛，为构建高性能软件营造了一个易于访问且包容的环境。

支持的语言

英语：完全支持，即可使用。
波斯语 (فارسی)：完全支持，即可使用。
阿拉伯语 (العربية)：目前开发中。我们需要阿拉伯语母语者的贡献以完成支持。

为什么选择 Salam？

🌍 针对波斯语和阿拉伯语使用者本地化：用您的母语编写和阅读代码。
🧑‍🎓 对初学者友好：Salam 让编程对每个人（包括学生和新开发者）都易于上手。
💻 强大的工具：易于使用，但具备满足您所有编码需求的强大功能。

主要特性

✏️ 直观的脚本编写和代码编译。
🚀 支持 Docker 以实现无缝开发。
🔧 用于最佳实践的 Linting 和代码检查。
🔄 内置用于版本控制和更新的命令。

快速安装

GNU-Linux/Mac:

{ curl -fsSL https://raw.githubusercontent.com/SalamLang/Salam/refs/heads/main/install.sh || wget -qO- https://raw.githubusercontent.com/SalamLang/Salam/refs/heads/main/install.sh; } | sh && export PATH="$HOME/.salam/bin:$PATH"

Windows:

powershell -NoProfile -Command "[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor 3072; (New-Object Net.WebClient).DownloadFile('https://raw.githubusercontent.com/SalamLang/Salam/refs/heads/main/install.bat','%TEMP%\salam-install.bat')" && call "%TEMP%\salam-install.bat" && set "PATH=%USERPROFILE%\.salam\bin;%PATH%"

🧩 编辑器支持

Visual Studio Code

从 Visual Studio Code Marketplace 安装官方 Salam Language 扩展，以获取语法高亮和语言支持。

🛠️ 编译器 (`salam`)

Salam 是静态类型且编译型语言。通用语言会转译为 C，并构建为原生可执行文件；嵌入的 layout: 块会编译为 HTML/CSS/JS。

构建

需要一个 C 编译器。tcc 是默认后端（内置数学库，速度快）；gcc/clang 也可用。

编译器位于 compiler/（一个自包含的子项目： src/、std/、tests/、tools/、Makefile、CMakeLists.txt）。从那里构建它：

cd compiler
sh tools/bash/build-compiler.sh   # quick build with tcc  ->  ./salam
# or, with CMake (out-of-tree build, then run the test suite via ctest):
cmake -B build && cmake --build build && ctest --test-dir build
# or just: make            # (release build via the Makefile -> ../salam at the repo root)

没有独立的运行时库：salam build 会将小型 C 运行时（print/strcat/pow/alloc 以及可选的边界检查）内联到生成的 C 代码中，因此编译后的程序是自包含的，仅链接 -lm（使用 tcc 时为 -lmsvcrt）。

用法

# general language -> native executable
salam build app.salam --output=app.exe         # then ./app.exe
salam cli build app.salam --keep-c             # optional 'cli' prefix; keep generated C
salam obj app.salam                            # compile to .o only

# layout DSL -> website
salam layout build page.salam                  # page.html + page.css + page.js
salam layout build page.salam --inline         # one self-contained page.html
salam layout build a.salam b.salam             # per-page html + merged style.css/script.js

# inspect any stage (general or layout)
salam inspect app.salam --emit-tokens-xml | --emit-ast-xml | --emit-symbol-xml
salam inspect app.salam --log-level=trace
salam build app.salam -DDEBUG                  # preprocessor define

# format source in place (auto-detects nothing - pass --lang=fa for Persian files)
salam format app.salam                         # reformat one file
salam format                                   # reformat every .salam under the cwd, recursively
salam format compiler/src/ tests/              # reformat given files and/or directories
salam format --check                           # report files that need formatting (exit 1 if any)
salam format app.salam --tabs                  # indent with tabs (convert spaces to tabs)
salam format compiler/src/ --indent=2          # indent with 2 spaces per level
salam format page.salam --lang=fa              # Persian source

# REPLs
salam cli       # general
salam layout    # layout

你好，世界：

func main {
    println "Hello, World!"
}

交叉编译

Salam 可以使用 LLVM 后端 为其他操作系统和架构生成可执行文件和目标文件。通过 --target=<triple> 向 build 或 obj 传递完整的 LLVM 目标三元组；当存在该参数时，编译器将通过 LLVM（clang/llc）进行路由，而不是使用默认的 C 后端，因此 --cc 和 --keep-c 不再适用。输出文件名遵循目标平台的约定（Windows 为 .exe，MSVC 目标文件为 .obj，ELF 无扩展名），并且 --output 会像往常一样覆盖它。

# Windows executable from Linux (MinGW target)
salam build main.salam --target=x86_64-w64-windows-gnu --output=app.exe

# WebAssembly (WASI)
salam build main.salam --target=wasm32-wasi --output=app.wasm

# a target-specific object file
salam obj main.salam --target=x86_64-pc-windows-msvc      # -> main.obj

目标已完全通过流水线连接：OS/架构预定义宏（SALAM_OS_WINDOWS, SALAM_ARCH_X64, …）描述目标，因此 @if SALAM_OS_WINDOWS 选择正确的分支，并且 link dynamic|static| framework "..." 指令会被传递给交叉链接器（例如 link dynamic "user32" → -luser32）。

先决条件。 交叉编译驱动 LLVM 工具链，因此您需要一个较新的 clang/llc（工具链调用的是 v22 版本），此外，对于 Windows 目标，还需要 LLVM 链接器 lld 和一个 sysroot（目标的 CRT、系统导入库和头文件）：

sudo apt install clang lld llvm        # toolchain (or an official LLVM release)

捆绑的 sysroot（用户零配置）。 使用 -DSALAM_BUNDLE_MINGW=ON 构建编译器时，MinGW-w64 sysroot 会被暂存到 <prefix>/share/salam/sysroots/<arch>-w64-mingw32/；salam build --target=…-windows-gnu 随后会自动发现并传递它，因此最终用户无需额外操作：

# copy an existing sysroot (e.g. from the mingw-w64 package)
cmake -B build -DSALAM_BUNDLE_MINGW=ON \
      -DSALAM_MINGW_SYSROOT=/usr/x86_64-w64-mingw32
# or download one (pin the hash for reproducibility)
cmake -B build -DSALAM_BUNDLE_MINGW=ON \
      -DSALAM_MINGW_URL=<llvm-mingw archive> -DSALAM_MINGW_SHA256=<hash>
cmake --build build && cmake --install build

将 $SALAM_SYSROOTS 指向一个包含按目标划分的 sysroot 子目录的目录，以在不重新构建的情况下覆盖或添加目标。自动发现按工具链而非原始三元组命名它们：<arch>-w64-mingw32/ 对应 *-windows-gnu （例如 x86_64-w64-mingw32/），<arch>-linux-musl/ 对应 *-linux-musl （例如 x86_64-linux-musl/）。

MSVC / macOS 目标。 自动 sysroot 发现目前仅处理 MinGW（*-windows-gnu）和 musl（*-linux-musl）。微软和苹果的 SDK 不可再分发且不会被自动发现，因此对于 *-windows-msvc 和 *-apple-darwin，您必须自行提供工具链/sysroot（例如 xwin 用于 MSVC），并通过 salam llvm 手动驱动 clang，直到这些目标的一等选择功能落地。在 Linux 上，优先使用 -windows-gnu（MinGW）三元组。

LLVM 后端支持该语言的一个不断增长的子集；交叉编译适用于该子集内的自包含程序及其导入。没有 --target 的宿主原生构建继续使用快速的 C 后端（tcc/gcc/clang）和完整的标准库。

🐳 Docker & Docker Compose

编译器附带一个多阶段 Dockerfile 和一个基于 Alpine Linux （musl，最轻量的实用基础）构建的 docker-compose.yml。构建上下文是编译器根目录（compiler/）。镜像包含编译器所需的一切：一个 C 编译器（gcc + tcc）、LLVM 22 后端（clang-22、llc-22、opt-22、 lli-22）以及 make，无需 CMake。

compose 文件位于 compiler/docker/；通过 -f 传递它，以便您可以从仓库根目录运行。有两种模式：

开发（实时重载）

编译器树通过 bind-mount 挂载，并且 ./salam 会在 src/ 的每次更改时自动重新编译（由 entr 提供支持，参见 tools/bash/docker-dev.sh）：

docker compose -f compiler/docker/docker-compose.yml up dev   # build, then watch & rebuild

在您的主机上编辑 compiler/src/ 下的任何文件，容器都会 ./salam 进行增量重建。要在相同环境中获取一个 shell：

docker compose -f compiler/docker/docker-compose.yml run --rm dev sh

生产环境（复制与构建）

生产阶段依次执行 COPY . 和 make && make install，将一个完全构建好的、自包含的编译器烘焙到镜像中。salam 是入口点，并且仓库根目录挂载在 /work，以便访问共享的 tests/：

docker compose -f compiler/docker/docker-compose.yml build prod
docker compose -f compiler/docker/docker-compose.yml run --rm prod build tests/en/basics/hello.salam --output=hello
docker compose -f compiler/docker/docker-compose.yml run --rm prod layout build page.salam --inline
docker compose -f compiler/docker/docker-compose.yml run --rm prod --help

纯 Docker（不使用 Compose）

使用 compiler/ 作为上下文进行构建（以便 Dockerfile 中的 COPY . 能够获取编译器树）：

docker build --target prod -f compiler/docker/Dockerfile -t salam:prod compiler   # production image
docker run --rm -v "$PWD":/work salam:prod build app.salam --output=app

docker build --target dev  -f compiler/docker/Dockerfile -t salam:dev  compiler   # dev image
docker run --rm -it -v "$PWD/compiler":/app salam:dev                             # live-rebuild loop

LLVM 和 Alpine 版本是可配置的构建参数 (--build-arg LLVM_VERSION=22, --build-arg ALPINE_VERSION=edge)。LLVM 22 目前位于 Alpine 的 edge 仓库中，这就是为什么 edge 是默认基础镜像。

Books (XeLaTeX)

教程书籍拥有自己的镜像，位于 books/docker/，因此您可以在不安装本地 TeX 发行版的情况下进行排版。一个 common XeLaTeX 镜像同时构建 both 语言：它基于完整的 TeX Live 方案，该方案已捆绑 xepersian（用于较重的从右到左波斯语书籍）、polyglossia + tcolorbox（用于较轻的英语书籍）以及 Latin Modern。books/ 目录通过 bind-mount 挂载，因此生成的 PDF 会写回主机的 books/<lang>/intro-programming/book.pdf：

docker compose -f books/docker/docker-compose.yml run --rm books        # both
docker compose -f books/docker/docker-compose.yml run --rm books en     # English only
docker compose -f books/docker/docker-compose.yml run --rm books fa     # Persian only

或者使用纯 Docker（构建一次，然后针对挂载的 books/ 树运行）：

docker build -t salam-books books/docker
docker run --rm -v "$PWD/books":/books salam-books all

🚀 Bun Workspaces: 多应用开发与静态站点指南

🚀 1. 快速入门执行指南

要从根目录同时启动整个本地化 monorepo 环境，请执行以下步骤。

安装工作区链接和缓存实例：

bun install

在高端口上并发启动所有服务器：

bun run dev:all

您的终端窗口将显示交错排列的日志，并清晰地以各自的包来源作为前缀：

Salam % bun run dev:all
$ bun run --filter='*' --parallel dev
@workspace/pages:dev         |
@workspace/pages:dev         |   VITE v8.1.3  ready in 61 ms
@workspace/pages:dev         |
@workspace/pages:dev         |   ➜  Local:   http://127.0.0.1:55002/
@workspace/editor:dev        |
@workspace/editor:dev        |   VITE v8.1.3  ready in 65 ms
@workspace/editor:dev        |
@workspace/editor:dev        |   ➜  Local:   http://127.0.0.1:55001/
@workspace/vercel-editor:dev |
@workspace/vercel-editor:dev |   VITE v8.1.3  ready in 91 ms
@workspace/vercel-editor:dev |
@workspace/vercel-editor:dev |   ➜  Local:   http://localhost:5173/
@workspace/vercel-editor:dev |   ➜  Network: use --host to expose
@workspace/runner:dev        |
@workspace/runner:dev        |  ⛅️ wrangler 4.107.0
@workspace/runner:dev        | ────────────────────
@workspace/runner:dev        | ⎔ Starting local server...
@workspace/runner:dev        | [wrangler:info] Ready on http://localhost:8787
@workspace/runner:dev        | [wrangler:info] GET / 200 OK (7ms)

📁 2. Monorepo 架构与核心配置

要配置工作区，请按字母顺序将仓库目录树结构化为如下形式：

salam-monorepo/
├── bunfig.toml
├── package.json
├── editor/
├── extensions/
│   └── vscode/
├── pages/
├── runner/
└── vercel-editor/

根配置文件

`package.json`（工作区根目录）

此文件以严格的字母顺序定义工作区，并利用 Bun 的并行过滤机制。它还通过 Bun 的工作区 catalog 集中管理共享依赖版本，并暴露用于本地开发、构建、Wrangler 类型生成和依赖更新的根脚本。

{
  "name": "salam-monorepo",
  "private": true,
  "workspaces": {
    "packages": [
      "editor",
      "extensions/vscode",
      "pages",
      "runner",
      "vercel-editor"
    ],
    "catalog": {
      "react": "^19.2.7",
      "react-dom": "^19.2.7",
      "tailwindcss": "^4.3.2",
      "@tailwindcss/vite": "^4.3.2",
      "@vitejs/plugin-react": "^6.0.3",
      "vite": "^8.1.3",
      "typescript": "^6.0.3",
      "wrangler": "^4.107.0",
      "@types/bun": "latest",
      "@types/node": "^26.1.0",
      "@types/react": "^19.2.17",
      "@types/react-dom": "^19.2.3"
    }
  },
  "scripts": {
    "dev:all": "bun run --filter='*' --parallel --if-present dev",
    "dev:editor": "bun run --filter='@workspace/editor' dev",
    "docs:myst": "bun run myst start",
    "dev:pages": "bun run --filter='@workspace/pages' dev",
    "dev:runner": "bun run --filter='@workspace/runner' dev",
    "dev:vercel": "bun run --filter='@workspace/vercel-editor' dev",
    "build:all": "bun run --filter='*' --if-present build",
    "build:myst": "bun run myst build --html",
    "build:vercel": "bun run --filter='@workspace/vercel-editor' build",
    "update:deps": "bun update -i -r",
    "clean": "rm -rf node_modules **/node_modules .bun-cache",
    "generate": "bun run --filter='@workspace/runner' generate",
    "typecheck": "bun run --filter='@workspace/runner' typecheck"
  },
  "devDependencies": {
    "@tailwindcss/vite": "catalog:",
    "@vitejs/plugin-react": "catalog:",
    "mystmd": "^1.10.1",
    "vite": "catalog:"
  }
}

有用的根命令：

bun run dev:all: 启动每个暴露了 dev 脚本的工作区
bun run dev:editor, bun run dev:pages, bun run dev:runner, 和 bun run dev:vercel: 一次启动一个工作区
bun run build:all: 运行每个工作区中存在的 build 脚本
bun run build:vercel: 在 vercel-editor/ 中构建 React/Vite 应用
bun run docs:myst: 启动 MyST 文档开发服务器
bun run build:myst: 将 MyST 文档构建为静态 HTML (_build/html/)
bun run generate: 为 runner/ 刷新 Cloudflare Wrangler 类型
bun run typecheck: 重新生成 Wrangler 类型并运行 runner/ TypeScript 检查
bun run update:deps: 交互式地更新整个工作区的依赖项

`bunfig.toml` (工作区根目录)

强制 Bun 持久地将执行环境视为具有开发优先行为。

[development]
development = true

🛠️ 3. 静态站点包实现

独立工作区使用您特定的包作用域（@workspace/pages）。它被设置为 "private": true，以防止意外将包发布到公共 npm 注册表。

静态站点配置

pages/package.json

{
  "name": "@workspace/pages",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "bunx vite --port 55002 --host 127.0.0.1"
  }
}

⚡ 4. 评估的 Serve 方法

根据您的资产编译流水线，您可以通过两种不同的命令行方式来运行并提供您的静态文件资产。

方法 A：Bun 原生开发引擎 (`bun run --watch index.html`)

Bun 充当全栈编译器。它查找运行时入口点，挂钩一个监视器循环，并将代码直接注入到运行时中。

PORT=55002 bun run --watch index.html

🟥 关键崩溃 Bug：如果 HTML 文件链接了 <script src="./app.js"> 标签，且 app.js 缺失、被删除或由另一个构建脚本按错误顺序生成，Bun 的依赖引擎会抛出致命的编译错误或段错误恐慌，导致整个根开发终端崩溃。

方法 B：本地隔离方法（`bunx vite`）

通过在目录上挂载专用的 Vite 开发上下文，完全绕过复杂的多环境集成。

bunx vite --port 55002 --host 127.0.0.1

🟩 修复方案：缺失的脚本或组件会安全地发出标准前端浏览器 404 Not Found 消息，而不是破坏您的后端引擎进程。

🔄 5. Global Monorepo Package Updates

为了在所有应用程序子目录中一起管理和升级外部依赖项，而无需进入各个 package 文件夹，请触发您的自定义根快捷方式：

bun run update:deps

解释脚本背后的标志 (`bun update -i -r`)

-i (--interactive): 启动一个交互式终端用户界面 (TUI)，映射出所有过时的资产。使用方向键和空格键选择性地选择要升级的包，或切换 l 以强制将包升级到其定义的 SemVer 范围之外的绝对 --latest 版本。
-r (--recursive): 强制 Bun 的解析引擎扫描 workspaces 字段下列出的所有项 (editor, pages, runner 等)，而不是纯粹在主目录内执行。

初始化时，Bun 会在终端输出网格中添加一个 Workspace 列，以便在将更改写入磁盘之前，您可以准确验证每个目标模块升级的绑定位置。

🔒 6. 安全剖析与最佳实践

在主机上运行服务器时，请遵守以下边界：

端口选择架构

网络端口范围从 1 到 65535。

1 - 1023: 系统特权根端口。避免使用这些端口。
1024 - 49151: 注册用户应用程序端口（例如，8080, 3000）。与其他应用程序重叠的风险较高。
49152 - 65535: 动态、私有和高端口。非常适合干净地设置工作区开发环境。

网络地址绑定（`0.0.0.0` 与 `127.0.0.1`）

0.0.0.0 (所有接口): 大多数服务器的默认配置。如果您处于开放的公共 Wi-Fi 网络（如咖啡馆），该网络上的任何人都可以通过查询您的本地 IP 地址来读取您未发布的静态代码。
127.0.0.1 (回环本地主机): 硬件受限隔离。只有您确切的物理计算机才能访问这些端口。强烈建议在不受信任的网络中使用。

安全命令公式

为了强制即时浏览器更新、跳过磁盘缓存、隔离网络窃听者并绕过编译器引擎崩溃，请使用此脚本公式：

bunx vite --port 55002 --host 127.0.0.1

📚 7. MyST 文档

该仓库附带一个由 mystmd 驱动的 MyST (Markedly Structured Text) 文档站点。源内容来自仓库中的 books/（TeX 书籍文件）和 .md 文件。

配置文件

myst.yml - MyST 项目配置（站点模板、仓库链接和自定义样式文件）。
.readthedocs.yaml - 用于托管生成文档的 Read the Docs 构建配置。
_build/ - 由 myst build --html（包括 _build/html/）生成的静态输出目录，在 .gitignore 中被 Git 忽略。

在本地运行文档

# Install workspace dependencies (includes mystmd)
bun install

# Start the live-reload docs server
bun run docs:myst

# Build the static HTML output to _build/html/
bun run build:myst

开发服务器（myst start）监视仓库中的 books/ 和 .md 文件，并在更改时重新构建。Read the Docs 使用 .readthedocs.yaml 自动构建和部署站点。

🤝 贡献

我们欢迎来自社区的贡献！

📖 阅读我们的贡献指南。
🌟 遵循我们的行为准则。

一起，让编码对所有人触手可及。

🔍 参与代码审查

欢迎大家参与代码审查，并鼓励大家积极参与。 你不需要是核心维护者才能审查拉取请求。事实上，审查 PR 是对 Salam 贡献最具影响力的方式之一，我们希望让它尽可能易于上手。

💡 代码审查比编写代码更难。 阅读他人的工作、理解其意图、发现边界情况，并以友善和清晰的方式传达反馈，需要真正的技巧。如果你正在这样做，谢谢你；这非常重要。

GitHub PR 审查是如何工作的

打开任何拉取请求，然后点击 Files changed 选项卡，查看每个被修改文件的差异。

留下内联评论

将鼠标悬停在差异中的任何行号上；会出现一个蓝色的 + 按钮。
点击它以打开针对该行或代码块的评论框。
写下你的想法，然后点击 Start a review（而不是 "Add single comment"），以便将所有你的备注批量处理在一起。

建议代码更改

在内联评论中，你可以使用带围栏的建议块来提出确切的替换：

```suggestion
your replacement code here
```

作者可以单击一次接受你的建议，无需手动编辑。

提交审查

当你读完所有文件后：

点击绿色的 Review changes 按钮（diff 的右上角）。
撰写一条总体总结评论。
选择以下三种结果之一：
- 💬 Comment - 分享想法，但不正式批准或阻止。非常适合提问、给新手的反馈或开启讨论。
- ✅ Approve - 你对更改感到满意。这是推动 PR 走向合并的绿色对勾。只有在你仔细阅读了更改后才批准。
- 🚫 Request changes - 在 PR 可以合并之前需要修复某些问题。要具体且具有建设性。
点击 Submit review。

优秀评审的技巧

简单的评论就完全没问题。 如果你是评审新手，仅仅留下一个深思熟虑的问题或记录你学到的东西，本身就极具价值。你不必批准或阻止。
友善且具体。 指向确切的行，解释_为什么_某事可能令人担忧，并在可能时提出替代方案。
假设善意。 作者为此付出了努力。将反馈表述为问题（“这可以是……吗？”）而不是命令（“把这改成……”）。
初学者的 PR 值得额外的温暖。 如果贡献者的简介或提交历史显示他们是新手，一句简短的鼓励话语会起到很大的作用。
真心批准时才批准。 绿色对勾代表信任。仅将其保留给你真正阅读过并感到自信的更改。

与社区共同成长

一致的审查者和贡献者会被注意到。积极参与审查、议题和讨论是社区成员成为受信任协作者的方式。随着时间的推移，杰出的贡献者可能会被邀请加入 Salam 核心团队 并承担额外的职责：

🏷️ 分诊角色 - 帮助标记、分类和确定传入议题和拉取请求的优先级。
🛡️ Discord / Telegram 版主 - 帮助保持实时频道友好且切题。
🔑 维护者权限 - 合并 PR，管理发布，并帮助塑造路线图。

💬 实时社区

Salam 核心团队活跃在我们的实时频道中。加入我们，提出问题，分享想法，讨论进行中的审查，或者只是打个招呼：

平台	链接
Discord	discord.gg/HfY3QHDPdv
Telegram	t.me/SalamProgrammingLanguage

这些空间向所有人开放，从好奇的新手到经验丰富的系统程序员。声音越多越好。

📖 术语表

本 readme、贡献指南以及编辑器 readme 中使用的术语。

术语	定义
Alpine Linux	基于 musl libc 构建的轻量级 Linux 发行版。用作 Salam 的 Docker 容器的基础镜像。
AST (Abstract Syntax Tree)	解析后源代码的树状表示。每个节点代表一个构造（表达式、语句、声明）。Salam 编译器在语义分析和代码生成之前构建 AST。
Biome	快速的 JavaScript/TypeScript 代码检查器和格式化器。作为 prek 钩子运行（`biome-check`）。
Bun	JavaScript 运行时、包管理器和打包器。在 Salam 单体仓库中用于管理工作区并运行开发服务器。
C ABI	C 应用程序二进制接口，是函数调用方式和内存中数据布局的低层契约。Salam 的 FFI 和 `extern` 声明依赖于 C ABI。
CI (Continuous Integration)	自动化的流水线，用于构建、测试和检查每个拉取请求。Salam 使用 GitHub Actions 进行 CI。
Clang	基于 LLVM 的 C 编译器。用于构建 Salam 编译器的受支持后端之一。
Cloudflare Workers	在边缘运行 JavaScript/TypeScript 的无服务器计算平台。`runner/` 工作区通过 Wrangler 部署到 Cloudflare Workers。
CMake	跨平台构建工具生成器。Salam 编译器可以使用 `cmake -B build && cmake --build build` 进行构建。
Codegen	代码生成后端。将编译器的 AST 和类型信息转换为目标输出（C 源代码、LLVM IR 或 WebAssembly 模块）。
Codespell	用于源代码和文档的拼写检查器。作为 prek 钩子运行以捕获拼写错误。
CTest	CMake 内置的测试运行器。在编译器的 CMake 构建后通过 `ctest --test-dir build` 调用。
defer	Salam 关键字，用于调度语句或代码块在封闭作用域结束时执行，无论作用域如何退出。
Docker	用于在隔离且可复现的环境中构建和运行 Salam 编译器的容器平台。
Docker Compose	用于定义和运行多容器 Docker 应用程序的工具。Salam 在 `compiler/docker/` 中提供了一个包含 `dev` 和 `prod` 服务目标的 `docker-compose.yml`。
doctoc	自动在 Markdown 文件中生成目录（Table of Contents）的工具。本 readme 和贡献指南中的目录块由 doctoc 维护。
DSL (Domain-Specific Language)	针对特定问题领域定制的语言。Salam 包含一个内置的布局 DSL，可将 `.salam` 文件编译为 HTML、CSS 和 JavaScript。
Emscripten	基于 LLVM 的工具链，将 C/C++ 编译为 WebAssembly。用于为 web 游乐场构建 `salam-wa.wasm` 和 `salam-wa.js`。
entr	当监视的文件发生变化时重新运行命令的工具。用于 Salam 的 Docker 开发模式，在源代码编辑时重新构建编译器。
FFI (Foreign Function Interface)	调用其他语言（通常是 C）编写的函数的机制。Salam 通过 `extern` 声明支持 FFI。
Fork	GitHub 上仓库的个人副本。贡献者 fork `SalamLang/Salam`，在其 fork 中工作，然后向原始仓库发起拉取请求。
GCC	GNU 编译器集合。Salam 构建工具支持的 C 编译器。
Gitleaks	作为 prek 审计钩子运行的密钥检测工具，用于防止意外提交 API 密钥或凭据。
GitHub Actions	Salam 的 CI/CD 平台。工作流在 `.github/workflows/` 中定义。
Layout DSL	Salam 内置的用于描述 UI 的子语言。`layout:` 块，或经过 `salam layout build` 处理的 `.salam` 文件，编译为 HTML、CSS 和 JavaScript。
Lexer	编译器流水线的第一个阶段：读取源文本并生成令牌流。
LLVM	低级虚拟机，一个编译器基础设施项目。用作可选后端（`clang-22`、`llc-22`、`opt-22`、`lli-22` 包含在 Docker 镜像中）。
Makefile	GNU Make 构建脚本（`compiler/Makefile`）。从 `compiler/` 运行 `make` 会在仓库根目录生成 `salam` 二进制的发布版本。
Markdownlint	Markdown 文件的 Linter。在 `README.md`、`CONTRIBUTING.md` 和其他文档中强制保持一致的风格。
musl	Alpine Linux 使用的 C 标准库。Salam 的 Docker 镜像基于 Alpine + musl 以实现最小化占用。
MyST (Markedly Structured Text)	一种扩展了 Markdown 以支持角色、指令和交叉引用的技术写作文档工具链。通过 `myst.yml` 进行配置；由 `mystmd` 包驱动（脚本为 `docs:myst` 和 `build:myst`）。
npm	Node Package Manager。在 Salam monorepo 中与 Bun 一起用于包管理。
Parser	编译器流水线的第二阶段：消费来自 lexer 的 token 流并构建 AST。
PR (Pull Request)	一种用于提议更改的 GitHub 机制：贡献者从功能分支发起 PR，审阅者发表评论，维护者将其合并。
prek	Salam 使用的 Git hook 管理器。Hooks 定义在 `prek.toml`（标准阶段和手动阶段）和 `prek-audit.toml`（专注于安全的审计检查）中。
prek-audit.toml	用于专注于安全的审计 hooks 的 prek 配置文件。使用 `prek run --all-files --config prek-audit.toml` 单独运行。
Prettier	一种具有明确观点的代码格式化工具，适用于 JavaScript、TypeScript、CSS 和 JSON。作为 prek hook 运行。
React	一种使用组件模型构建用户界面的 JavaScript 库。在 `vercel-editor/` 工作区中使用。
Read the Docs	免费的文档托管平台。Salam 的 MyST 文档通过 `.readthedocs.yaml` 自动构建并发布到该平台。
REPL	Read-Eval-Print Loop，一种交互式会话，您可以输入表达式并立即看到结果。`salam cli` 启动通用 REPL；`salam layout` 启动布局 REPL。
RTL (Right-to-Left)	阿拉伯语和波斯语文字所使用的文本方向。Salam Web 游乐场支持 RTL，并在选择波斯语时切换方向。
Semantic Analyzer	编译器流水线的第三阶段：在代码生成之前解析名称、检查类型并验证 AST。
SemVer (Semantic Versioning)	版本编号方案（`MAJOR.MINOR.PATCH`）。用于 Bun 的交互式更新工具和 GitHub 发布。
shfmt	Shell 脚本格式化器。作为 prek 手动阶段钩子运行，以规范化 `.sh` 文件中的缩进和样式。
Super-Linter	在 CI 中针对整个仓库运行广泛的语言特定 linter 的 GitHub Actions 工作流。
Tailwind CSS	实用优先的 CSS 框架。用于 Salam monorepo 工作区；通过 `@tailwindcss/vite` 插件集成。
TCC (Tiny C Compiler)	轻量级、快速的 C 编译器。Salam 快速构建脚本使用的默认后端。
Tree-walking interpreter	一种直接评估 AST 而无需先编译为原生代码的解释器。用于 Web 游乐场，并通过 `salam exec` / `salam run --interp` 用于纯计算程序。
TUI (Terminal User Interface)	在终端中渲染的交互式、键盘驱动界面。Bun 的 `bun update -i` 标志打开一个 TUI，用于选择要升级的包。
TypeScript	JavaScript 的类型化超集，可编译为纯 JavaScript。用于 `runner/` 和 `vercel-editor/` 工作区。
Upstream	原始的 `SalamLang/Salam` 仓库。贡献者将其添加为 Git 远程（`git remote add upstream …`）以保持其分支同步。
Virtual filesystem	Emscripten 的浏览器内文件系统层。`build-wasm.sh` 将 `std/` 目录预加载到其中，以便在浏览器中运行 Salam 时，导入解析和布局模式能够正常工作。
Vite	前端构建工具和开发服务器。用于 Salam monorepo 中提供编辑器和工作区页面服务。
WebAssembly (Wasm)	一种可在现代浏览器中以接近原生速度运行的便携式二进制指令格式。Salam 的 Web 游乐场由 Emscripten 生成的编译器 Wasm 构建提供支持。
Wrangler	Cloudflare 用于构建和部署 Workers 的 CLI。`runner/` 工作区使用 Wrangler 进行本地开发（`wrangler dev`）和 CI 类型生成。
yamllint	YAML 检查器。作为 prek 钩子运行，以验证 `.yml` 工作流和配置文件。