edb63e6095
Section 3 documented the retired nix path (nix.conf edits, nix build .#xcecore, AppImage, nix develop self-wrap). Replace it with the actual build as it now works on plain Ubuntu: - 3.1 one-shot apt install (toolchain + 11 C libraries), pointing at DEPS.md for the versioned dependency table and the wrap-subproject source closure for everything apt does not carry - 3.3 daily development via tools/xce-build.sh (profiles, --incremental caveat), plus the plain meson commands it wraps; Go vendor refresh without any special shell - 3.4 tarball packaging via tools/xce-package.sh + install.sh (the shipping distribution form, replacing the AppImage section) - 3.5 scripts/ci-ubuntu.sh as the CI entry point Co-Authored-By: Claude Code <noreply@anthropic.com>
160 lines
5.9 KiB
Markdown
160 lines
5.9 KiB
Markdown
# 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.
|