# 1. commit 规则
- 每个人 fork 自己的 branch， 从自己的 branch 做 PR，review 完再 commit

# 2. code format
## 2.1. C
推荐使用 clang-format，公共配置放在源码里面 xce/.clang-format

（理论上直接使用源码里面 xce/.clang-format 文件格式不会变）

### 2.1.1. vscode 可以在配置中加上如下内容
```
"C_Cpp.clang_format_style": "WebKit",
"C_Cpp.clang_format_fallbackStyle": "WebKit",
```

### 2.1.2. vim & emacs

clang-format -style="{BasedOnStyle: webkit}" -i  XX.c

## 2.2. golang

使用默认 gofmt

# 3. build environment and build (example of ubuntu)

构建**不依赖 nix**：直接在 Ubuntu（24.04 基线）上用 apt 系统库 + meson wrap
subprojects 构建。完整的依赖清单（工具链 + 11 个 apt 库的版本下限 + 6 个随仓库
提交的 wrap subproject 源码闭包）见 **[DEPS.md](DEPS.md)**。

## 3.1 build environment

一次性安装构建工具链与系统库（与 CI 的 `scripts/ci-ubuntu.sh` 完全一致）：

```sh
sudo apt-get update
# 工具链
sudo apt-get install -y build-essential pkg-config ninja-build \
    python3 python3-pip python3-venv git
# meson >= 1.5（Ubuntu 24.04 自带 1.3，pip 原地升级）
sudo apt-get install -y meson
meson --version | grep -qE '^1\.[5-9]' || pip3 install --break-system-packages 'meson>=1.5'
# cap'n proto（schema 编译器 + pycapnp 链接的 C++ 运行时）
sudo apt-get install -y capnproto libcapnp-dev
# C 库（DEPS.md "apt 可直接安装" 表）
sudo apt-get install -y libuv1-dev libssl-dev libedit-dev libsqlite3-dev \
    libhwloc-dev libcgroup-dev libtirpc-dev libcyaml-dev libyaml-dev \
    zlib1g-dev libsystemd-dev
# Go（apiserver/xcecli 依赖已全部 vendored，构建离线）
sudo apt-get install -y golang-go
```

其余依赖（c-capnproto、librtti、struct2json、tinylog、unity、packcc）不在系统里装——
它们以 meson wrap subproject 的形式提交在 `src/subprojects/`（源码闭包），meson
配置时自动拉取/构建，无需手动处理。

## 3.2 checkout source code

```sh
git clone ssh://forgejo@gitea.shenrs.eu/rshen/xce.git
cd xce
```

（参考第 1 节，fork 自己的 branch 再提交 PR）

## 3.3 build (for daily develop)

日常开发直接用 `src/tools/xce-build.sh`（若在 Claude Code 中开发，对应 `/xce-build`
skill）。脚本开头有依赖预检（缺工具/缺库时报出具体的 apt 包名，而不是构建中途的
晦涩报错），然后执行 `meson setup` / `meson compile`，asan profile 下还会自动跑测试：

```sh
cd xce/src

tools/xce-build.sh              # 全部组件 + 全部测试 (asan profile, 输出到 xce.build/)
tools/xce-build.sh controller   # 只构建/测试 controller (lib + controller + xce_test)
tools/xce-build.sh worker       # 只构建 worker
tools/xce-build.sh scheduler    # 只构建/测试 scheduler
tools/xce-build.sh apiserver    # 只构建/测试 apiserver + xcecli (Go)
```

支持三种 profile（`tools/xce-build.sh [component] [profile]`）：

- `asan`（默认）：debug + AddressSanitizer，输出目录 `xce.build/`，会运行测试
- `debug`：`-O0 -g3` 无 sanitizer，输出目录 `build.dbg/`，仅编译，用于 gdb 调试
- `release`：`-O3` 无 sanitizer，输出目录 `build.release/`，仅编译，用于 soak/性能测试

注意：单组件构建默认会先 `rm -rf` 对应的 build 目录再重新配置，若同一目录下已有其他
组件的产物会被清掉；需要在同一目录下累积多个组件时加 `--incremental`（增量
reconfigure，不清空目录；capnp 生成目标存在未修的依赖边缺失，增量构建若结果可疑
请退回全量重建，见脚本内 bug-1565 注释）。

也可以手动执行底层的 meson 命令（`xce-build.sh` 是对下面步骤的封装）：

```sh
cd xce/src

# generate build configuration (debug + address sanitizer)
meson setup xce.build --buildtype=debug -Db_sanitize=address

# build
meson compile -C xce.build

# The generated files will be in xce.build/
```

### 3.3.1 更新 Go 依赖（vendor 维护）

Go 模块（`frontend/apiserver`、`frontend/xcecli`、
`autoscaler/providers/baidu/src/bcctool`）的依赖以 `vendor/` 目录的形式提交进仓库，
构建时 `tools/go_build` 使用 `GOFLAGS=-mod=vendor`、`GOPROXY=off` 完全离线编译。

修改了某个模块的 `go.mod` / `go.sum`（新增、升级、删除依赖）后，重新生成对应模块
的 `vendor/` 并提交（普通环境即可，无需任何特殊 shell）：

```sh
cd xce/src/frontend/apiserver   # 其他两个模块同理
go mod tidy
go mod vendor
git add go.mod go.sum vendor
```

## 3.4 package (tarball 分发)

产品分发形态是自包含 tarball（daemon + CLI + `$ORIGIN` RPATH 的 bundled 非基础库
+ systemd unit 样例 + configs/schema + ttyd），打包规则见 `src/tools/xce-package.sh`
头部注释与 DEPS.md "运行期 bundle 规则"：

```sh
cd xce/src

tools/xce-build.sh all release        # 先出 release 构建（build.release/）
tools/xce-package.sh                  # 默认从 build.release/ 打到 dist/
# 或显式指定: tools/xce-package.sh build.release dist
```

产物：`dist/xce-<version>-<commit>-<fingerprint>-linux-x86_64.tar.gz`。目标机上：

```sh
tar -xzf xce-*.tar.gz && cd xce-*/
sudo ./install.sh                      # 默认装到 /opt/xce，PREFIX=... 可覆盖
```

## 3.5 CI

`scripts/ci-ubuntu.sh` 在裸 Ubuntu 24.04 容器里跑完整流水线（装依赖 → asan 全量
构建+测试 → release 构建 → 打 tarball smoke），与客户环境同构：

```sh
bash scripts/ci-ubuntu.sh
```

# 4. misc
## 4.1. Windows remap ctrl and alt key
create a reg file, e.g. remapkey.reg
```
Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Keyboard Layout]
"Scancode Map"=hex:00,00,00,00,00,00,00,00,05,00,00,00,38,00,1d,00,1d,00,38,00,38,e0,1d,e0,1d,e0,38,e0,00,00,00,00
```
then double click remapkey.reg to import it. Restart OS.