From ea00879af05a3ce7325db779ad89405e11fed9de Mon Sep 17 00:00:00 2001
From: Rongsong Shen <rshen@shenrs.eu>
Date: Wed, 2 Sep 2026 11:06:19 +0800
Subject: [PATCH] update README.md to the newest build guide

---
 README.md | 46 +++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 43 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 5849134a..f245455b 100644
--- a/README.md
+++ b/README.md
@@ -58,6 +58,13 @@ Host gitea.shenrs.eu
 
 ## 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 package and release)
 
 ```sh
@@ -74,18 +81,51 @@ You can find the generated binaries at =result= directory
 
 ## 3.4 build (for daily develop)
 
+日常开发推荐直接使用 `src/tools/xce-build.sh`（若在 Claude Code 中开发，对应的是 `/xce-build` skill），
+它会执行 `meson setup` / `meson compile`，并在 `asan` profile 下跑测试。**注意它自己不会进入 `nix develop`
+环境**，需要先手动 `nix develop`，或者用 `nix develop --command` 包一层：
+
+```sh
+cd xce/src
+nix develop
+
+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)
+```
+
+或者不进入交互式 shell，直接一条命令跑：
+
+```sh
+cd xce/src
+nix develop --command tools/xce-build.sh controller
+```
+
+支持三种 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，不清空目录）。
+
+也可以手动执行底层的 nix + meson 命令（`xce-build.sh` 实际上就是对下面步骤的封装）：
+
 ```sh
 cd xce/src
 nix develop
 
 # using meson to generated build configuration (debug and address sanitize)
 
-meson setup build --buildtype=debug -Db_sanitize=address
+meson setup xce.build --buildtype=debug -Db_sanitize=address
 
 # run meson to build
-meson compile -C  build
+meson compile -C xce.build
 
-# The generated files will be in build/
+# The generated files will be in xce.build/
 ```
 
 ## 3.5 build AppImage package