Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions .github/workflows/formatter-config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
name: Formatter configuration
on:
pull_request:
paths:
- '.uncrustify.cfg'
- 'devtools/format/**'
- 'SerialPrograms/CMakeLists.txt'
- 'SerialPrograms/cmake/Formatting.cmake'
- 'SerialPrograms/cmake/RunFormatting.cmake'
- '.github/workflows/formatter-config.yml'
workflow_dispatch:
permissions:
contents: read
jobs:
config-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-python@v6
with:
python-version: '3.12'
- name: Build pinned Uncrustify
shell: bash
working-directory: ${{ runner.temp }}
run: |
curl --fail --location --silent --show-error \
https://github.com/uncrustify/uncrustify/archive/refs/tags/uncrustify-0.83.0.tar.gz \
--output uncrustify.tar.gz
printf '%s %s\n' \
1d4d3ab3a991c66eb24cb0a3e690573b4882fd98bc6ec64a01c283998c20dc87 \
uncrustify.tar.gz | sha256sum --check --status
tar -xzf uncrustify.tar.gz
cmake -S uncrustify-uncrustify-0.83.0 -B uncrustify-build -DCMAKE_BUILD_TYPE=Release
cmake --build uncrustify-build --parallel 4
echo "$RUNNER_TEMP/uncrustify-build" >> "$GITHUB_PATH"
- run: python -m unittest discover -s devtools/format -v
115 changes: 115 additions & 0 deletions .uncrustify.cfg
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
# Uncrustify 0.83.0. Usage and scope: devtools/format/README.md.
# Keep include order, comment text, existing LF/CRLF and unlimited line width.
newlines = auto
input_tab_size = 4
output_tab_size = 4
indent_columns = 4
indent_continue = 4
indent_with_tabs = 0
indent_namespace = false
indent_access_spec = 1
code_width = 0
cmt_width = 0
cmt_reflow_mode = 0
cmt_indent_multi = false
mod_sort_include = false
mod_sort_using = false
mod_remove_duplicate_include = false

# Compact braces, with a space before control parentheses: if (ready()){
sp_before_sparen = force
sp_sparen_brace = remove
# Preserve alignment before short-function bodies (const/non-const overloads).
sp_fparen_brace = ignore
sp_cpp_lambda_paren_brace = remove
sp_cpp_lambda_square_brace = remove
sp_word_brace_ns = remove
sp_enum_brace = remove
sp_paren_brace = remove
sp_else_brace = remove
sp_brace_else = remove
sp_try_brace = remove
sp_catch_brace = remove
sp_brace_catch = remove
sp_do_brace_open = remove
sp_brace_close_while = remove
nl_if_brace = remove
nl_for_brace = remove
nl_while_brace = remove
nl_switch_brace = remove
nl_do_brace = remove
nl_try_brace = remove
nl_catch_brace = remove
nl_else_brace = remove
nl_brace_else = remove
nl_namespace_brace = remove
nl_class_brace = remove
nl_struct_brace = remove
nl_enum_brace = remove
# Preserve constructor brace/comment placement; attaching across a commented-out
# initializer moves the brace past the comment. Same-line gaps still collapse.
nl_fdef_brace = ignore

# Type-attached pointers/references; conventional operator/comma spacing.
sp_before_ptr_star = remove
sp_after_ptr_star = force
sp_before_byref = remove
sp_after_byref = force
sp_assign = force
sp_arith = force
sp_compare = force
sp_bool = force
sp_after_comma = force
sp_before_comma = remove

# Expand braced control bodies, but do not add/remove any braces or statements.
nl_split_if_one_liner = true
nl_split_for_one_liner = true
nl_split_while_one_liner = true
mod_full_brace_if = ignore
mod_full_brace_for = ignore
mod_full_brace_while = ignore
mod_full_brace_do = ignore
mod_full_brace_function = ignore
mod_paren_on_return = ignore
mod_paren_on_throw = ignore
mod_remove_extra_semicolon = false
mod_remove_empty_return = false
mod_enum_last_comma = ignore
mod_add_long_namespace_closebrace_comment = 0
# Keep type spacing: `remove` can merge `operator const Type` into constType.
# This preserves existing standalone class-name/brace spacing as well.
sp_after_type = ignore
sp_angle_shift = ignore
sp_permit_cpp11_shift = true
indent_class = true

sp_before_class_colon = force
sp_after_class_colon = force

# Preserve compact functions/tables and extra spacing between tokens.
# Leading declaration alignment still needs explicit protection; see README.
nl_func_leave_one_liners = true
nl_getset_leave_one_liners = true
nl_class_leave_one_liners = true
nl_cpp_lambda_leave_one_liners = true
nl_assign_leave_one_liners = true
nl_enum_leave_one_liners = true
align_keep_extra_space = true

# Keep closing-parenthesis columns and the repository's continuation layout.
# Keeping the first continuation verbatim makes some nested-lambda/table cases
# drift on every pass in 0.83.0. Use a stable four-space continuation instead.
indent_ignore_first_continue = false
indent_paren_close = -1

# The repository consistently spells parameter packs class... / typename....
sp_type_ellipsis = remove
sp_before_ellipsis = remove
# Keep a braced argument indented relative to the enclosing call's parentheses.
indent_paren_open_brace = true
indent_func_call_param = true

# Match existing lambda bodies inside calls; do not apply continuation twice.
indent_cpp_lambda_only_once = true
nl_brace_catch = remove
114 changes: 114 additions & 0 deletions devtools/format/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
# C++ formatting

Use **Uncrustify 0.83.0** with the root `.uncrustify.cfg`. This replaces the
initial clang-format proposal: Uncrustify can produce the repository's compact
`if (condition){`, `}else{` and `namespace Name{` spelling directly.
No regex postprocessor or change to AGENTS.md's style rules is needed.

## Install and preview

On macOS:

```sh
brew install uncrustify
uncrustify --version
```

Check for `Uncrustify-0.83.0` (Homebrew's release appends `_f`). CI builds that
release from a SHA-256-verified source archive. If your package manager supplies
a different version, install the pinned release before comparing formatter output.

From the repo root, preview a specific file without changing it:

```sh
uncrustify -q -c .uncrustify.cfg -l CPP \
-f SerialPrograms/Source/CommonFramework/Main.cpp -o /tmp/Main.formatted.cpp
git diff --no-index -- SerialPrograms/Source/CommonFramework/Main.cpp /tmp/Main.formatted.cpp
```

A diff exits 1 when changes are present; that is expected. Apply to an explicit
file only after reviewing the preview:

```sh
uncrustify -q -c .uncrustify.cfg -l CPP --replace --no-backup \
SerialPrograms/Source/CommonFramework/Main.cpp
```

To check an explicit file without writing it:

```sh
uncrustify -q -c .uncrustify.cfg -l CPP --check \
SerialPrograms/Source/CommonFramework/Main.cpp
```

Format edited files in a separate commit from behavioral changes. Preserve
unrelated changes and do not format vendored or generated files. The repository
contains legacy formatting differences; adopting the configuration does not
require reformatting all existing sources. This PR's CI tests the configuration,
not source-wide compliance. Do not enable a broad format-on-save hook yet.

## What this configuration covers

- Four spaces, no indentation tabs, unindented namespaces/access labels and
type-attached pointers/references.
- Compact control/namespace braces and spaced control parentheses. Existing
standalone class brace spacing and nested-template `>>` spelling are preserved.
Braced single-line `if`/`for`/`while` bodies expand onto multiple lines;
ordinary short functions and empty constructors stay compact.
- Existing LF or CRLF style, include order (including own-header-last and
registration-order exceptions), comment text and unlimited line width.
- Existing spacing within aligned declarations/overloads, parameter-pack
spelling (`class... Args`), four-space continuation layout and existing
closing-parenthesis columns. Lambdas inside calls keep their ordinary body indentation.
- No brace insertion/removal, statement removal, include sorting or generated
namespace comments. Missing-brace and namespace/API documentation requirements
remain the responsibility of review and existing code-health checks.

Formatting still changes indentation, spacing and some line breaks. C++ macros,
conditional compilation and newer syntax need review; a successful formatter
exit does not prove semantic equivalence or a successful native build. Main-tree
trials are performed in an isolated snapshot and reviewed before any formatting
commit is proposed. Known limitations are recorded in the fork PR/run record:

- Class/struct brace spacing is not fully enforced: standalone declarations
retain their existing spacing, and inherited declarations can gain a space
before `{`, for example
`struct Derived : public Base {`. Uncrustify 0.83.0 does not expose a separate
configurable spacing rule for this case. Restore the repository's compact
spelling when reviewing output; this formatter is not a complete code-health
compliance check.
- Leading spaces used to align const/non-const overloads are still normalized
to the block indentation. `align_keep_extra_space` preserves spacing between
tokens, not arbitrary leading columns. Protect a deliberate table explicitly
with the tool's `// *INDENT-OFF*` / `// *INDENT-ON*` markers, or leave that
region unformatted. Tests expose this limitation and verify protected tables
remain byte-identical. No markers are added to application sources by this PR.
- Function-definition brace line breaks are preserved to avoid moving a
constructor's brace across comments or commented-out initializer entries.
- Missing braces stay missing. Formatting is not a substitute for the existing
multiline-control-flow/braces lint rules.

## Configuration tests

These are tooling tests, not application tests. They call the real formatter:

```sh
python3 -m unittest discover -s devtools/format -v
```

For a non-PATH installation:

```sh
UNCRUSTIFY=/path/to/uncrustify python3 -m unittest discover -s devtools/format -v
```

Coverage includes exact brace spelling, indentation, pointers, includes,
line-ending preservation, comment/long-line preservation, templates/designated
initializers, raw strings, macro continuations/token pasting, constructor-comment placement and idempotence.
Regressions also preserve conversion-operator tokens, short functions, empty
constructors, intra-line alignment, argument/closing-parenthesis layouts, lambdas,
attached catch chains, parameter packs and repeated-pass stability for nested
lambdas/initializer tables. Known inherited-class spacing and
leading-overload alignment gaps are tested explicitly rather than claimed fixed.

Reference: [Uncrustify 0.83.0 options](https://github.com/uncrustify/uncrustify/blob/uncrustify-0.83.0/documentation/htdocs/default.cfg).
Loading
Loading