diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/FORMATTING.md | 69 |
1 files changed, 69 insertions, 0 deletions
diff --git a/docs/FORMATTING.md b/docs/FORMATTING.md new file mode 100644 index 000000000..2208c3b3d --- /dev/null +++ b/docs/FORMATTING.md @@ -0,0 +1,69 @@ +# Formatting + +Shipwright's C/C++ in `soh/` is formatted with **clang-format 14**, the version +used by the OoT/MM decompilation that the vendored `soh/src/` tree comes from. +clang-format's output is not stable across major versions, so the major version +matters: any **14.x** produces identical output for this tree (verified across +all formatted files), but clang-format 15+ will reformat differently and fail +CI. Patch version (14.0.0 vs 14.0.6) does not matter. + +## Format the tree + +```bash +./run-clang-format.sh +``` + +This formats every C/C++ file in `soh/` in place, skipping the decompiled +headers (`soh/src`, `soh/include`) and autogenerated assets (`soh/assets`), +matching what CI checks. + +The script calls `clang-format-14` by default. If your clang-format 14 is named +or located differently, point `CLANG_FORMAT` at it: + +```bash +CLANG_FORMAT=clang-format ./run-clang-format.sh # already 14.x +CLANG_FORMAT=/path/to/clang-format ./run-clang-format.sh # static binary +CLANG_FORMAT="uvx clang-format@14" ./run-clang-format.sh # uv wheel +CLANG_FORMAT='"/path with spaces/cf"' ./run-clang-format.sh # quote a spaced path +``` + +`CLANG_FORMAT` is treated as a command line, so it can carry arguments (the `uvx` +case) or a quoted path containing spaces. + +On Windows you have two options. Run `run-clang-format.ps1` from PowerShell: it +downloads clang-format 14.0.6 itself (needs [7-Zip](https://www.7-zip.org/) +installed) and formats the same fileset, so you don't have to install +clang-format or pass `CLANG_FORMAT`. Or run `run-clang-format.sh` from Git Bash +(ships with Git for Windows) or WSL, since it needs a Unix shell for +`find`/`xargs`; get the binary from the `uvx` wheel or the Windows static binary +below. + +## Getting clang-format 14 + +Recent distros and Homebrew often ship only newer clang-format. Any of these +gives you a 14.x binary: + +- **Debian/Ubuntu**: `sudo apt-get install clang-format-14` (where the package + still exists). +- **Arch**: AUR [`clang-format-static-bin`](https://aur.archlinux.org/packages/clang-format-static-bin). +- **Any Linux/macOS/Windows, no install**: download a static binary from + [muttleyxd/clang-tools-static-binaries](https://github.com/muttleyxd/clang-tools-static-binaries/releases/tag/master-796e77c) + (e.g. `clang-format-14_linux-amd64`), `chmod +x`, and point `CLANG_FORMAT` at it. +- **Any OS via a Python wheel**: `uvx clang-format@14` (with + [uv](https://docs.astral.sh/uv/)), or `pipx install clang-format==14.0.6`. +- **Homebrew (macOS or Linux)**: `brew install llvm@14` and use its + `clang-format`, or use one of the cross-platform options above. + +## Optional: format on commit + +The repo ships a [pre-commit](https://pre-commit.com/) config +(`.pre-commit-config.yaml`) that auto-formats staged C/C++ with a pinned 14.x +before each commit, so you never get caught by the CI check. With pre-commit +[installed](https://pre-commit.com/#install), enable it once: + +```bash +pre-commit install --install-hooks +``` + +`--install-hooks` downloads clang-format up front so your first commit isn't +slowed by it. |