Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
96dff99
Propose pinned clang-format config with explicit style compatibility …
dayfine Nov 7, 2026
c0f34a3
Use Uncrustify for compact control braces with token-preservation reg…
dayfine Nov 7, 2026
d8b038f
Preserve compact functions, aligned spacing and authored argument lay…
dayfine Nov 7, 2026
6904e79
Preview and apply same-line formatting only within Git-edited C++ lines
dayfine Nov 7, 2026
16a53cc
Check formatter tooling when its CMake integration changes
dayfine Nov 7, 2026
b31e019
Merge remote-tracking branch 'origin/tooling/clang-format-config' int…
dayfine Nov 7, 2026
3a895bc
Add incremental format and format-check CMake targets without app builds
dayfine Nov 7, 2026
0dedcfe
Merge remote-tracking branch 'origin/tooling/incremental-cpp-format' …
dayfine Nov 7, 2026
7149f37
Merge origin/main into tooling/clang-format-config
dayfine Nov 7, 2026
78e7d32
Merge origin/tooling/clang-format-config into tooling/incremental-cpp…
dayfine Nov 7, 2026
1bca5d8
Merge origin/tooling/incremental-cpp-format into tooling/cmake-increm…
dayfine Nov 7, 2026
37a5441
Merge origin/main into tooling/clang-format-config
dayfine Nov 8, 2026
2ac8dfa
Merge origin/tooling/clang-format-config into tooling/incremental-cpp…
dayfine Nov 8, 2026
9402db2
Merge origin/tooling/incremental-cpp-format into tooling/cmake-increm…
dayfine Nov 8, 2026
04e9f91
Merge origin/main into tooling/clang-format-config
dayfine Nov 9, 2026
5c194c2
Merge origin/tooling/clang-format-config into tooling/incremental-cpp…
dayfine Nov 9, 2026
fc34b46
Merge origin/tooling/incremental-cpp-format into tooling/cmake-increm…
dayfine Nov 9, 2026
f16b625
Merge origin/main into tooling/clang-format-config
dayfine Nov 10, 2026
834fed7
Merge origin/tooling/clang-format-config into tooling/incremental-cpp…
dayfine Nov 10, 2026
34832e0
Merge origin/tooling/incremental-cpp-format into tooling/cmake-increm…
dayfine Nov 10, 2026
8ea889f
Merge origin/main into tooling/clang-format-config
dayfine Nov 11, 2026
83accc1
Merge origin/tooling/clang-format-config into tooling/incremental-cpp…
dayfine Nov 11, 2026
8421cb2
Merge origin/tooling/incremental-cpp-format into tooling/cmake-increm…
dayfine Nov 11, 2026
c3b7329
Merge origin/main into tooling/clang-format-config
dayfine Nov 12, 2026
c0780d7
Merge origin/tooling/clang-format-config into tooling/incremental-cpp…
dayfine Nov 12, 2026
a68f001
Merge origin/tooling/incremental-cpp-format into tooling/cmake-increm…
dayfine Nov 12, 2026
13a1ac7
Merge origin/main into tooling/clang-format-config
dayfine Nov 13, 2026
870fe21
Merge origin/tooling/clang-format-config into tooling/incremental-cpp…
dayfine Nov 13, 2026
3fb54b7
Merge origin/tooling/incremental-cpp-format into tooling/cmake-increm…
dayfine Nov 13, 2026
f8b5c80
Merge origin/main into tooling/clang-format-config
dayfine Nov 14, 2026
b7505c3
Merge origin/tooling/clang-format-config into tooling/incremental-cpp…
dayfine Nov 14, 2026
048db4f
Merge origin/tooling/incremental-cpp-format into tooling/cmake-increm…
dayfine Nov 14, 2026
f7253d7
Merge origin/main into tooling/clang-format-config
dayfine Nov 16, 2026
e946fd4
Merge origin/tooling/clang-format-config into tooling/incremental-cpp…
dayfine Nov 16, 2026
87bdc0c
Merge origin/tooling/incremental-cpp-format into tooling/cmake-increm…
dayfine Nov 16, 2026
f68c1b3
Merge origin/main into tooling/cmake-incremental-format
dayfine Nov 18, 2026
3d2fc77
Merge origin/main into tooling/cmake-incremental-format
dayfine Nov 19, 2026
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
4 changes: 4 additions & 0 deletions SerialPrograms/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,10 @@ add_custom_target(build-time-make-directory ALL
# Internal repo or not, we're always building from the SerialPrograms folder
set(REPO_ROOT_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../")

# Optional development targets; do not build or link the application.
include(cmake/Formatting.cmake)
pa_add_format_targets("${REPO_ROOT_DIR}")

# Determine environment
if(DEFINED ENV{GITHUB_ACTIONS})
message(STATUS "Detected CI environment, skipping qt deployment")
Expand Down
29 changes: 29 additions & 0 deletions SerialPrograms/cmake/Formatting.cmake
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# Incremental C++ formatting, with no application build dependency.
# cmake --build /path/to/build --target format # apply eligible edited-line spacing
# cmake --build /path/to/build --target format-check # non-writing check
include_guard(GLOBAL)

# Add explicit targets; defer Python/tool discovery until a formatting target is run.
function(pa_add_format_targets repo_root)
get_filename_component(format_repo "${repo_root}" ABSOLUTE)
set(PA_FORMAT_BASE "HEAD" CACHE STRING "Git parent ref for incremental formatting (merge base with HEAD)")
set(PA_FORMAT_PYTHON "" CACHE FILEPATH "Optional Python 3.8+ interpreter for formatting only")
foreach(format_target IN ITEMS format format-check)
if(format_target STREQUAL "format")
set(format_mode --write)
else()
set(format_mode --check)
endif()
add_custom_target(${format_target}
COMMAND "${CMAKE_COMMAND}"
"-DPA_FORMAT_REPO=${format_repo}"
"-DPA_FORMAT_BASE=${PA_FORMAT_BASE}"
"-DPA_FORMAT_MODE=${format_mode}"
"-DPA_FORMAT_PYTHON=${PA_FORMAT_PYTHON}"
-P "${CMAKE_CURRENT_FUNCTION_LIST_DIR}/RunFormatting.cmake"
COMMENT "Incremental C++ ${format_target}: Git-edited lines only"
USES_TERMINAL
VERBATIM
)
endforeach()
endfunction()
25 changes: 25 additions & 0 deletions SerialPrograms/cmake/RunFormatting.cmake
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Target-time adapter; invoked by Formatting.cmake, not during application configure.
# cmake --build /path/to/build --target format-check
cmake_minimum_required(VERSION 3.24)

if(NOT PA_FORMAT_MODE STREQUAL "--write" AND NOT PA_FORMAT_MODE STREQUAL "--check")
message(FATAL_ERROR "Use the format or format-check build target.")
endif()
if(PA_FORMAT_PYTHON)
set(Python3_EXECUTABLE "${PA_FORMAT_PYTHON}")
endif()
find_package(Python3 3.8 QUIET COMPONENTS Interpreter)
if(NOT Python3_Interpreter_FOUND)
message(FATAL_ERROR "Formatting needs Python 3.8+. Install it or configure PA_FORMAT_PYTHON=/path/to/python3.")
endif()
execute_process(
COMMAND "${Python3_EXECUTABLE}" "${PA_FORMAT_REPO}/devtools/format/format_changed.py"
--repo "${PA_FORMAT_REPO}" --base "${PA_FORMAT_BASE}" "${PA_FORMAT_MODE}"
RESULT_VARIABLE format_result
)
if(NOT format_result STREQUAL "0")
if(PA_FORMAT_MODE STREQUAL "--check" AND format_result STREQUAL "1")
message(FATAL_ERROR "Edited-line formatting remains. Run the format target, then review and stage its changes.")
endif()
message(FATAL_ERROR "Incremental formatter failed (${format_result}); see its diagnostic above. Requires Uncrustify 0.83.0 and Clang; clang-format is not used.")
endif()
58 changes: 58 additions & 0 deletions devtools/format/CMAKE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# CMake formatting targets

After this integration is present in the configured source checkout:

```sh
cmake --build /path/to/build --target format-check
cmake --build /path/to/build --target format
```

`format-check` previews eligible changes and fails if any remain. `format`
applies them. Neither target builds or links the app. They use the
[edited-line formatter](INCREMENTAL.md), not clang-format: tracked staged and
unstaged changes against HEAD, with all original leading columns/newlines kept.
They skip block reflows, preprocessor definitions and declaration lines. Review
the output and stage changes yourself; the index is never changed automatically.

The target belongs to the build directory's **configured source checkout**.
Running a lab build's target formats that lab checkout, not a different feature
worktree in the terminal's current directory. Use a build configured from your
feature worktree, or invoke the Python command with `--repo` to choose another.
An old build does not gain targets until its source picks up this integration
and CMake reconfigures.

Python 3.8+, Uncrustify 0.83.0 and Clang are needed when formatting eligible
changes. Python discovery happens only when a format target runs; it does not
add a Python/formatter requirement to normal app configuration. No dependency
is downloaded automatically and no clang-format installation is required.

Optional settings:

```sh
cmake -S SerialPrograms -B /path/to/build \
-DPA_FORMAT_BASE=origin/main \
-DPA_FORMAT_PYTHON=/path/to/python3
```

`PA_FORMAT_BASE` defaults to HEAD; another ref selects its merge base with HEAD
for whole-branch formatting. Use the actual parent for a stacked branch. Leave
`PA_FORMAT_PYTHON` empty to discover Python at target time. `UNCRUSTIFY` and
`CLANG` environment variables select non-PATH executables as with the CLI.

To configure a tools-only build without Qt/OpenCV or application dependencies:

```sh
cmake -S SerialPrograms -B /path/to/tools-build \
-DPA_CORE_ONLY=ON -DCOMMAND_LINE_EXE=OFF
cmake --build /path/to/tools-build --target format-check
```

This still performs normal CMake compiler/thread checks but compiles no app
when the explicit formatting target is requested. There is no `cmake --format`
flag; formatting is a project-defined build target. CTest registration for the
native application tests is a separate integration.

Tests live in `test_cmake.py` beside the formatter tests and include the actual
CMake module. They check source/build paths with spaces, a committed parent ref,
index preservation, useful missing-Python diagnostics, and that explicit format
targets do not run an unrelated ALL/application target.
91 changes: 91 additions & 0 deletions devtools/format/INCREMENTAL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
# Format edited lines only

Use this mode for routine development. It avoids the broad reindentation and
known declaration-spacing changes in the full-file formatter preview.

The tool needs Python 3, Uncrustify 0.83.0 and Clang (for a raw-token check).
It does not build or run SerialPrograms or connect a console.

From your code worktree, preview first:

```sh
python3 /path/to/tools/devtools/format/format_changed.py --repo .
```

While the tools PR is under review, the local checkout path is:

```sh
python3 ~/Projects/wt/incremental-cpp-format/devtools/format/format_changed.py --repo .
```

Then apply the reviewed proposal:

```sh
python3 ~/Projects/wt/incremental-cpp-format/devtools/format/format_changed.py --repo . --write
```

No directory change is necessary: `--repo ~/Projects/wt/bdsp-my-fix` selects
that checkout explicitly. The tool always uses the configuration beside its own
script, so the target branch need not merge the tools PR first.

## Scope and behavior

Default comparison is **HEAD against the working tree**, including staged and
unstaged edits. No commit is required. New files must first be tracked with
`git add`; untracked, deleted and renamed files are excluded. If a rename also
contains edits, commit the rename separately before using the default local mode.
Only `.h`, `.c`, `.cpp` and `.tpp` files in Common/SerialPrograms are considered.

For a whole branch, compare with its merge base with a chosen parent:

```sh
python3 /path/to/format_changed.py --repo . --base origin/main
```

Choose the actual parent for a stacked PR; do not compare a large story chain
with main when you only intend to format its top layer. The tool does not fetch.

- Runs Uncrustify on each selected file to obtain context, then accepts only
same-line whitespace edits on lines Git marks added/modified.
- Keeps every original leading column, including manual declaration alignment,
and every original newline. Untouched lines remain byte-identical.
- Skips formatter hunks that change line count, preprocessor directives and
their continuations, and lines containing class/struct/union keywords. Those
skips keep block reflows and known declaration-brace changes out of the patch.
- Checks the candidate with Clang's raw lexer before writing: significant token
kind/spelling must match, including quoted/raw string contents. This does not
preprocess includes or prove every macro-invocation behavior equivalent;
review the displayed patch. Macro definitions are protected; invocations in
ordinary code are not universally identifiable without preprocessing.
- Verifies all candidates first and refuses a stale source snapshot. It never
stages files, commits, switches branches or changes the index. After --write,
review and stage the formatting yourself.

This mode intentionally does **not** fix indentation, insert braces, expand
single-line control bodies, reflow blocks or assert complete style compliance.
Use existing lint/review for those. Skipped selected edits are reported on stderr;
stdout is the eligible patch. An unchanged result can mean the remaining
formatter suggestions were deliberately outside this mode's scope.

`--check` performs the same preview without writing and returns 1 if eligible
formatting remains; 0 means no eligible changes, and 2 indicates a tool, lexer,
version or source-snapshot error. Preview alone returns 0 without writing.
There is no automatic hook or source-format CI gate in this PR.

```sh
python3 /path/to/format_changed.py --repo . --check
```

Use `--uncrustify /path/to/uncrustify` / `--clang /path/to/clang` or environment
variables `UNCRUSTIFY` / `CLANG` for non-PATH installations.

## Tests

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

Tests call the real formatter and lexer, and use temporary Git repositories for
preview/check/write, staged-index preservation, explicit bases, unusual file
names, stale snapshots and refusal-before-write behavior. Application tests
remain native in their owning modules.
Loading