**更现代、更好用的 C**
[](LICENSE)
[](https://go.dev/)
[](https://en.wikipedia.org/wiki/C_(programming_language))
> **Multi-language Support**：如需阅读英文或其他语言的文档，推荐使用 [docs/tools/translate.py](docs/tools/translate.py) 生成本地化文档方便阅读。Supported languages: English, 日本語, 한국어, Deutsch, Français, Español, Русский.
---
## Kaula 是什么
Kaula 是一门**静态类型的系统级编程语言**，编译到 C，由 Clang 生成原生代码。
核心设计目标：**用更简单的语法，获得接近 Rust 的安全保证**——通过 SOR（Sub-structural Ownership）在编译期消除数据竞争和悬垂指针，而不引入运行时开销。
---
## 快速开始
### 安装
```bash
# 构建编译器
python toolkit_build.py
# 或手动构建
cd compiler && go build -o ../bin/kaulac ./cmd/kaulac/
```
依赖：Python 3.8+、Go 1.21+、LLVM-mingw 或 MSVC（Windows）/ Clang（Linux/macOS）
### Hello World
```kaula
import std.io
fn main() {
println("Hello, Kaula!")
}
```
### 编译运行
```bash
# 基本编译
kaulac main.kl
# 启用调试符号
kaulac --debug main.kl
# Release 模式
kaulac --release main.kl
# 查看版本
kaulac --version
# 输出: kaulac v1.0.42 (26.8.23-master-67ffac3, sor-oxide)
```
---
## 版本号
Kaula 使用双版本号系统：
| 类型 | 格式 | 示例 | 说明 |
|------|------|------|------|
| **发布版本** | `v1.0.x` | `v1.0.42` | x = 自 v1.0 以来的提交次数 |
| **快照版本** | `YY.M.DD-branch-hash` | `26.8.23-master-67ffac3` | 构建时自动生成 |
版本号自动生成：
```bash
# 查看当前版本
python scripts/version.py
# 输出: kaulac v1.0.42 (26.8.23-master-67ffac3, sor-oxide)
# 更新 version.json（构建时自动调用）
python scripts/version.py --update
# 仅输出快照版本
python scripts/version.py --snapshot
# 输出: 26.8.23-master-67ffac3
# 仅输出发布版本
python scripts/version.py --release
# 输出: v1.0.42
```
详见 [docs/tools/versioning.md](docs/tools/versioning.md)。
---
## 包管理
### 添加第三方库
```bash
# 从 Git 仓库添加
kaulac pkg add https://github.com/nicbarker/clay.git
# 从本地路径添加
kaulac pkg add ../my-kaula-lib --name mylib
# 列出已安装的包
kaulac pkg list
```
### 项目依赖
在 `kaula.json` 中声明依赖：
```json
{
"dependencies": {
"webview": "0.12",
"clay": "^1.0",
"mylib": {
"git": "https://github.com/user/repo.git",
"tag": "v1.0.0"
}
},
"registry": "https://gitee.com/kaula-universe"
}
```
支持两种依赖格式：
- **版本约束**：简单字符串（如 `"0.12"` 或 `"^1.0"`），从注册表下载
- **Git 仓库**：对象格式，指定 git URL、标签、分支或 commit
```bash
# 拉取依赖
kaulac pkg fetch
# 更新依赖
kaulac pkg update
# 查看锁状态
kaulac pkg lock
```
### 本地路径覆盖
用本地目录覆盖远程依赖，适合开发调试：
```json
{
"patches": {
"mylib": { "path": "../mylib-dev" }
}
}
```
### 离线/在线模式
```bash
# CI/CD 中使用离线模式（缓存未命中则报错）
kaulac --offline main.kl
# 强制联网刷新依赖
kaulac --online main.kl
```
详见 [docs/tools/package-management.md](docs/tools/package-management.md)。
---
## 工作空间
多包项目管理：
```bash
# 初始化工作空间
kaulac workspace init packages/core packages/utils app
# 列出成员
kaulac workspace list
# 构建所有成员
kaulac workspace build
# 运行测试
kaulac workspace test
```
在 `kaula.json` 中配置：
```json
{
"workspace": {
"members": ["packages/core", "packages/utils", "app"],
"shared_deps": {
"testing": "^1.0"
}
}
}
```
---
## 调试支持
### DWARF 调试符号
```bash
# 生成调试符号
kaulac --debug main.kl
# 完整调试（含类型信息）
kaulac --debug --debug-level full main.kl
# 配合 GDB 调试
gdb ./main
(gdb) source tools/debug/kaula_pretty_printers.py
(gdb) break main.kl:10
(gdb) run
```
### LLDB 支持
```bash
lldb ./main
(lldb) command script import tools/debug/kaula_lldb_formatters.py
(lldb) breakpoint set --file main.kl --line 10
(lldb) run
```
### 源码映射
```bash
# 生成源码映射文件
kaulac --debug --sourcemap main.kl
```
详见 [docs/tools/debugging.md](docs/tools/debugging.md)。
---
## 代码格式化
```bash
# 格式化文件（输出到 stdout）
kaulac fmt file main.kl
# 格式化并写回原文件
kaulac fmt file main.kl --write
# 批量格式化
kaulac fmt file main.kl utils.kl --write
# 检查文件是否已格式化
kaulac fmt check main.kl
```
格式化特性：
- 4 空格缩进
- Import 自动排序（`std.*` 优先）
- 二元表达式括号保留（基于优先级）
- 支持所有 Kaula 语法结构
详见 [docs/tools/formatter.md](docs/tools/formatter.md)。
---
## 编译选项
| 选项 | 说明 |
|------|------|
| `--opt