From 681c150c70a8aa4b187967e5f1f5212372dbc048 Mon Sep 17 00:00:00 2001 From: Zimin Li Date: Fri, 3 Jul 2026 09:01:12 +0000 Subject: [PATCH] docs: clearly document the fields of `cluster.yaml` in `README.md` --- README.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/README.md b/README.md index b9415f9..204f7b5 100644 --- a/README.md +++ b/README.md @@ -170,6 +170,35 @@ To achieve this, a `cluster.yaml` is required to be filled. This is the configur After having a successful build and a complete `cluster.yaml`, we are ready for compiling and executing a distributed program across the cluster. +
+📋 Full list of `cluster.yaml` fields (Click to expand) + +| Field | Required | Scope | Available Values / Meaning | +|-------|----------|-------|----------------------------| +| `common_dir` | Yes | Global | Root directory of the project source tree. For internal examples, set this to the InfiniCCL source root. For external programs, set this to the external project root. | +| `common_user` | No | Global | Default SSH user for remote nodes. If omitted and no node-level `user` is set, `root` is used. | +| `install_dir` | No | Global | Base directory for InfiniCCL installation artifacts. If omitted, `common_dir` is used. Libraries are installed under `/install/`. | +| `cmake_flags` | No | Global | CMake options applied to every node during `--build`, such as `-DAUTO_DETECT_BACKENDS=OFF`. Node-level `cmake_flags` override this value for that node. | +| `backend_args` | No | Global | Extra arguments passed to the selected backend launcher. Use a YAML mapping from a flag to a scalar or list of values, for example `--mca: ["pml ucx", "btl ^openib"]` for OpenMPI. | +| `backend_env` | No | Global | Environment variables exported for launcher/runtime setup on every node. Node-level `backend_env` overrides these values; path-like variables (`LD_LIBRARY_PATH`, `PATH`, `CPATH`, `LIBRARY_PATH`) are prepended to the global value. | +| `launcher_script` | No | Global | Path to a custom wrapper script. If omitted, `icclrun` generates `build/run_wrapper.sh` from `cluster.yaml`. For MPI launchers, the script path must be executable from every participating node. | +| `nodes` | Yes | Global | List of participating nodes. Each entry describes one host and its build/runtime settings. | +| `nodes[].ip` | Yes | Node | Node IP address or hostname. Use `localhost` or `127.0.0.1` for the local node. | +| `nodes[].user` | No | Node | SSH user for this node. Overrides `common_user`. | +| `nodes[].dir` | No | Node | Node-specific project source directory. Overrides `common_dir` for this node and is useful when the project path differs across hosts. | +| `nodes[].type` | Yes | Node | Architecture/build label used in build, install, and wrapper paths. Common values include `cpu`, `nvidia`, `iluvatar`, `metax`, `moore`, and `cambricon`. | +| `nodes[].slots` | No | Node | Number of processes to launch on this node. This usually matches the number of devices assigned to the node. Defaults to `8`. | +| `nodes[].cmake_flags` | No | Node | Node-specific CMake options used during `--build`, such as `-DUSE_CUDA=ON` or `-DUSE_MACA=ON`. Overrides global `cmake_flags` for this node. | +| `nodes[].backend_env` | No | Node | Node-specific runtime environment variables, such as `CUDA_VISIBLE_DEVICES`, `UCX_TLS`, or `UCX_NET_DEVICES`. Overrides or prepends to global `backend_env` values for this node. | + +> **Notes**: +> - `backend_args` and launcher-level environment forwarding are used by `--launcher ompi` and `--launcher mpich`. +> - `--launcher none` still uses the generated or configured wrapper script, but does not invoke `mpirun`. +> - Unknown YAML keys are ignored by the current launcher implementation. + +
+ + ### 1. Run Internal Examples #### 1.1. Run a Single Example