mirror of
https://github.com/HarbourMasters/Shipwright
synced 2026-08-21 14:55:27 -04:00
Philip Dubé
80 lines
3.2 KiB
Markdown
80 lines
3.2 KiB
Markdown
# 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.
|
|
|
|
## JSON assets
|
|
|
|
JSON in `soh/assets/custom` checked by CI with:
|
|
|
|
```sh
|
|
./scripts/lint-json.sh # check
|
|
./scripts/lint-json.sh --fix # reformat in place
|
|
```
|
|
|
|
## 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
|
|
and runs the JSON lint on staged assets before each commit, so you never get
|
|
caught by the CI checks. 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.
|